← graph

rewrite-readme-manifesto-5

Rewrite: README — manifesto + 5-min path; move operational reference to docs/GUIDE.md

Metadata

Statusdone
Assignedagent-2303
Agent identityf51439356729d112a6c404803d88015d5b44832c6c584c62b96732b63c2b0c7e
Modelclaude:opus
Created2026-05-04T15:20:04.532222814+00:00
Started2026-05-04T15:33:05.454004673+00:00
Completed2026-05-04T15:47:23.837457274+00:00
Tagspriority-high,fix,docs,readme,positioning, eval-scheduled
Eval score0.79
└ blocking impact0.85
└ completeness0.80
└ coordination overhead0.85
└ correctness0.75
└ downstream usability0.75
└ efficiency0.85
└ intent fidelity0.81
└ style adherence0.80

Description

Description

Substantial README rewrite. Current README reads as 'a large CLI with a lot of knobs' (~700+ lines of operational detail before reaching conceptual material) when it should read as 'a durable substrate for human/AI work' — the thesis Poietic actually has.

User direct guidance 2026-05-04 (paraphrased + verbatim quotes preserved):

The reframe

  • Position from 'task graph for getting things done' → 'operating surface for human/AI work'
  • One-line thesis: 'Agents are transient. Work persists.'
  • Category framing: 'Most AI systems center the agent. WorkGraph centers the work.'
  • Length target: ~150-250 lines max

Why this matters

Quoting user: 'Right now, an outsider can easily misread WorkGraph as task tracker plus agent spawning. ... The remarkable part is not agents run tasks. ... What is potentially remarkable about WorkGraph is this: It treats work itself as the primary object, not the agent.'

The README undersells the actual invention. New positioning gives:

  • Clear category (substrate, not framework)
  • Clear enemy (agent-centric design)
  • Sharp slogan (agents transient, work persists)
  • Concrete proof surface (Poietic's reflexive use)

Spec for the new README

Top section (manifesto)

# WorkGraph

**WorkGraph is an operating surface for human/AI work.**

It records what needs doing, who or what claimed it, what blocked it, what evidence
was produced, where judgment entered, what failed, what was retried, and how the
work changed over time.

Agents can come and go. **The graph remains.**

WorkGraph is not an agent framework. It is the substrate beneath agents: a persistent,
inspectable graph where humans and machines coordinate through tasks, dependencies,
claims, evidence, artifacts, and history.

Most AI systems center the agent.
WorkGraph centers the work.

Then 'Why this matters' section

Quote the user's draft:

AI agents are increasingly capable, but their work is often ephemeral: hidden in chat logs, scattered across branches, trapped in prompt histories, or lost when a process exits. Real work needs continuity. WorkGraph makes work durable...

Then 'What WorkGraph gives you' (bulleted feature list)

  • Persistent task graph
  • Claims and handoffs
  • Execution history
  • Evidence and artifacts
  • Human judgment points
  • Agent continuity

Then a tiny 5-line demo

wg init
wg add 'Design API'
wg add 'Implement backend' --after design-api
wg service start
wg tui

Then core concepts (brief)

Tasks, dependencies, agents, claims, traces, verification, agency.

Then links section pointing to docs/

What to MOVE OUT to docs/GUIDE.md (or split across docs/)

Per user list — all of this leaves the README:

  • Config migration
  • Model routing / provider setup
  • wg service command table (full)
  • Dead-agent cleanup options
  • TUI keybindings
  • OpenRouter / provider setup
  • Agency federation commands
  • FLIP internals
  • Troubleshooting
  • Exhaustive command lists

Recommend creating docs/GUIDE.md as the operator manual that replaces what was inline in the README. Or split across multiple docs/ files (config, service, agency, etc.) if natural splits exist.

Validation

  • README is ≤250 lines (target ~150-200)
  • First paragraph reads as the manifesto, not as installation instructions
  • 'Agents are transient. Work persists.' appears prominently
  • 'Most AI systems center the agent. WorkGraph centers the work.' appears as a category line
  • Operational details (config, full commands, TUI keybindings, agency federation, etc.) are MOVED to docs/, not duplicated
  • docs/GUIDE.md (or equivalent split) exists and contains the moved content
  • Links from README to docs/ are clean and discoverable
  • No regression of fix-readme-s's TB removal — TB stays gone (this task does NOT re-add it under any framing)
  • cargo build + cargo test pass (defensive — docs only)
  • cargo install --path . was run before claiming done

Coordinate

Runs AFTER fix-readme-s. That task removes Terminal-Bench from the README; this task is the broader rewrite. They should compose: TB stays gone (no re-add), then this task restructures everything else.

Process note

This is a writing/judgment task, not an implementation. Pinned to claude:opus rather than codex:gpt-5.5 because the value is in the prose quality + structural choices, not in mechanical edit work. The user's draft material is high-quality; the task is to integrate it cleanly + finish the docs/ migration.

Depends on

Required by

Log