refine-readme-cybernetic — Workgraph live mirror

Metadata

Status	done
Assigned	`agent-2311`
Agent identity	`3184716484e6f0ea08bb13539daf07686ee79d440505f1fdf2de0357707034c3`
Model	`claude:opus`
Created	2026-05-04T15:25:27.566547807+00:00
Started	2026-05-04T15:49:06.378931424+00:00
Completed	2026-05-04T16:02:26.464584301+00:00
Tags	`priority-high,fix,docs,readme,positioning,refinement`, `eval-scheduled`
Eval score	0.94
└ blocking impact	0.95
└ completeness	0.95
└ constraint fidelity	0.55
└ coordination overhead	0.95
└ correctness	0.95
└ downstream usability	0.93
└ efficiency	0.90
└ intent fidelity	0.86
└ style adherence	0.92

Description

Second pass on the README rewrite. The first pass (rewrite-readme-manifesto-5) gets the manifesto opening + docs split right. This pass adds the deeper framing the user developed in another chat: cybernetic system positioning, validation as founding premise, Poietic-builds-itself as core evidence (not example), 'What this is not' to block wrong comparisons, and an explicit reviewer path.

What's new vs the prior rewrite

The first rewrite landed the 'agents transient, work persists' line and the operational/manifesto split. This task DEEPENS those:

From 'operating surface' to 'cybernetic system'

The first rewrite said 'WorkGraph is an operating surface for human/AI work.' Strong. Sharper:

WorkGraph is not an agent framework. It is a cybernetic system for coordinating work: agents generate, humans judge, evidence accumulates, failures reshape the plan, and the organization learns.

Most AI tools try to automate execution. WorkGraph closes the loop between execution, validation, and human judgment.

Promote 'validation bottleneck' from feature to founding premise

## The bottleneck is validation

AI systems can now generate code, analyses, prose, plans, and hypotheses faster
than humans can evaluate them.

That creates a new organizational problem: work accumulates faster than judgment.

WorkGraph is designed around this bottleneck. It keeps generation, evidence,
validation, repair, human judgment, and organizational memory in the same
durable structure.

Promote Poietic-builds-itself from example to core evidence

## The proof surface

Poietic PBC is being built through WorkGraph.

The company's incorporation, grant writing, research coordination, website
development, and public theory work have all passed through the graph. These
are not demos. They are the organization's own formation, exposed as inspectable
human/AI work.

WorkGraph is therefore both the product and the medium through which Poietic
becomes operational.

The phrase 'not demos — formation' is the heart of this section.

Promote theory page from side essay to foundation

## Theory-led design

WorkGraph was not designed by starting with agents and adding orchestration.

It started from a theory of organizations: work needs decomposition, dependency,
role, motivation, coordination, evaluation, memory, and adaptation.

The implementation maps those organizational primitives into a working system.

Link to graphwork.github.io/theory/ as foundational, not optional reading.

Add 'What this is not' to block wrong comparisons

## What WorkGraph is not

WorkGraph is not primarily a chatbot, agent benchmark harness, project-management
app, or agent orchestration framework.

Those categories center messages, scores, tickets, or agents.

WorkGraph centers **answerable work**: tasks with dependencies, claims, evidence,
validation, failures, handoffs, artifacts, and history.

Rename sections per the framing table

Old name	New name
Setup	Start a work graph
Verification workflow	Closing the validation loop
Agency System	Roles, judgment, and evolving agency
Service mode	The coordinator
Trace	Organizational memory
Examples	Public proof surfaces

(Note: Terminal-Bench should already be gone after fix-readme-s; don't re-add under any name)

Add a reviewer path

## Review this project in 10 minutes

1. Read the [Poietic mission](https://poietic.life/): why legible human/AI collaboration matters.
2. Inspect a public graph: incorporation, grant writing, research, or this website.
3. Read [the theory](https://graphwork.github.io/theory/): how tasks, roles, evaluations, traces, and evolution form a cybernetic organization.
4. Install WorkGraph only after you understand the system it instantiates.

That last bullet is unusual. Keep it. It tells reviewers not to treat the project as a CLI first.

The core interpretive sentence (place prominently)

WorkGraph is not evidence that agents can replace organizations. It is evidence that organizations can be rebuilt around legible human/AI feedback loops.

This deserves to land somewhere the eye catches — possibly as a pull-quote, possibly closing the manifesto section.

Alternate slogan candidates (use one or rotate)

'Many systems coordinate agents. WorkGraph coordinates work.'
'Many tools make agents act. WorkGraph makes work answerable.'
'WorkGraph is infrastructure for answerable work.'

The 'answerable' framing is strong because it captures both accountability and responsiveness.

Composition with prior task

The first rewrite (rewrite-readme-manifesto-5) does the structural work — manifesto opening, length cut, docs split. This task adds depth on top:

Cybernetic framing replaces 'operating surface' as the primary noun
Validation-bottleneck section added (founding premise)
Poietic-builds-itself promoted to core evidence
Theory-led design section added with foundational framing
'What this is not' added
Section renames per the table
Reviewer-path added
Core interpretive sentence placed prominently

Both tasks should compose without conflict. If the prior task already did some of these (because the agent picked them up from the previous task description), this task should not regress that — only deepen and add the missing pieces.

Validation

README contains 'cybernetic system' as a category descriptor
'The bottleneck is validation' section exists, framed as founding premise (not feature)
'The proof surface' section names Poietic explicitly + 'not demos — formation'
'Theory-led design' section exists with link to graphwork.github.io/theory/
'What WorkGraph is not' section exists, blocks LangGraph/CrewAI/AutoGen comparisons explicitly
Section renames per the table applied where the original sections still exist
'Review this project in 10 minutes' section exists with the 4 numbered steps
Core interpretive sentence ('not evidence that agents can replace organizations...') placed prominently
Length still ≤250 lines — this task adds depth, not bloat. If the new sections push past 250, prune redundant operational text (further docs migration if needed).
No regression of fix-readme-s (Terminal-Bench stays gone)
No regression of rewrite-readme-manifesto-5 (manifesto opening stays; docs/GUIDE.md split stays)
cargo build + cargo test pass
cargo install --path . was run before claiming done

Process note

This is the third README task in the chain (fix-readme-s → rewrite-readme-manifesto-5 → this). They compose: surgical removal, structural rewrite, depth refinement. After all three land, the README reads as a theory-led cybernetic-system manifesto with operational details cleanly delegated to docs/. That matches what poietic.life already says — closing the gap between the website's framing and GitHub's first impression.

## Description
Second pass on the README rewrite. The first pass (rewrite-readme-manifesto-5) gets the manifesto opening + docs split right. This pass adds the deeper framing the user developed in another chat: cybernetic system positioning, validation as founding premise, Poietic-builds-itself as core evidence (not example), 'What this is not' to block wrong comparisons, and an explicit reviewer path.

## What's new vs the prior rewrite

The first rewrite landed the 'agents transient, work persists' line and the operational/manifesto split. This task DEEPENS those:

### From 'operating surface' to 'cybernetic system'
The first rewrite said 'WorkGraph is an operating surface for human/AI work.' Strong. Sharper:

> WorkGraph is not an agent framework. It is a **cybernetic system** for coordinating work: agents generate, humans judge, evidence accumulates, failures reshape the plan, and the organization learns.
>
> Most AI tools try to automate execution.
> WorkGraph closes the loop between **execution, validation, and human judgment**.

### Promote 'validation bottleneck' from feature to founding premise

```md
## The bottleneck is validation

AI systems can now generate code, analyses, prose, plans, and hypotheses faster
than humans can evaluate them.

That creates a new organizational problem: work accumulates faster than judgment.

WorkGraph is designed around this bottleneck. It keeps generation, evidence,
validation, repair, human judgment, and organizational memory in the same
durable structure.
```

### Promote Poietic-builds-itself from example to core evidence

```md
## The proof surface

Poietic PBC is being built through WorkGraph.

The company's incorporation, grant writing, research coordination, website
development, and public theory work have all passed through the graph. These
are not demos. They are the organization's own formation, exposed as inspectable
human/AI work.

WorkGraph is therefore both the product and the medium through which Poietic
becomes operational.
```

The phrase 'not demos — formation' is the heart of this section.

### Promote theory page from side essay to foundation

```md
## Theory-led design

WorkGraph was not designed by starting with agents and adding orchestration.

It started from a theory of organizations: work needs decomposition, dependency,
role, motivation, coordination, evaluation, memory, and adaptation.

The implementation maps those organizational primitives into a working system.
```

Link to graphwork.github.io/theory/ as foundational, not optional reading.

### Add 'What this is not' to block wrong comparisons

```md
## What WorkGraph is not

WorkGraph is not primarily a chatbot, agent benchmark harness, project-management
app, or agent orchestration framework.

Those categories center messages, scores, tickets, or agents.

WorkGraph centers **answerable work**: tasks with dependencies, claims, evidence,
validation, failures, handoffs, artifacts, and history.
```

### Rename sections per the framing table

| Old name | New name |
|----------|----------|
| Setup | Start a work graph |
| Verification workflow | Closing the validation loop |
| Agency System | Roles, judgment, and evolving agency |
| Service mode | The coordinator |
| Trace | Organizational memory |
| Examples | Public proof surfaces |

(Note: Terminal-Bench should already be gone after fix-readme-s; don't re-add under any name)

### Add a reviewer path

```md
## Review this project in 10 minutes

1. Read the [Poietic mission](https://poietic.life/): why legible human/AI collaboration matters.
2. Inspect a public graph: incorporation, grant writing, research, or this website.
3. Read [the theory](https://graphwork.github.io/theory/): how tasks, roles, evaluations, traces, and evolution form a cybernetic organization.
4. Install WorkGraph only after you understand the system it instantiates.
```

That last bullet is unusual. Keep it. It tells reviewers not to treat the project as a CLI first.

### The core interpretive sentence (place prominently)

> WorkGraph is not evidence that agents can replace organizations. It is evidence that organizations can be rebuilt around legible human/AI feedback loops.

This deserves to land somewhere the eye catches — possibly as a pull-quote, possibly closing the manifesto section.

### Alternate slogan candidates (use one or rotate)

- 'Many systems coordinate agents. WorkGraph coordinates work.'
- 'Many tools make agents act. WorkGraph makes work answerable.'
- 'WorkGraph is infrastructure for answerable work.'

The 'answerable' framing is strong because it captures both accountability and responsiveness.

## Composition with prior task

The first rewrite (rewrite-readme-manifesto-5) does the structural work — manifesto opening, length cut, docs split. This task adds depth on top:
- Cybernetic framing replaces 'operating surface' as the primary noun
- Validation-bottleneck section added (founding premise)
- Poietic-builds-itself promoted to core evidence
- Theory-led design section added with foundational framing
- 'What this is not' added
- Section renames per the table
- Reviewer-path added
- Core interpretive sentence placed prominently

## Validation
- [ ] README contains 'cybernetic system' as a category descriptor
- [ ] 'The bottleneck is validation' section exists, framed as founding premise (not feature)
- [ ] 'The proof surface' section names Poietic explicitly + 'not demos — formation'
- [ ] 'Theory-led design' section exists with link to graphwork.github.io/theory/
- [ ] 'What WorkGraph is not' section exists, blocks LangGraph/CrewAI/AutoGen comparisons explicitly
- [ ] Section renames per the table applied where the original sections still exist
- [ ] 'Review this project in 10 minutes' section exists with the 4 numbered steps
- [ ] Core interpretive sentence ('not evidence that agents can replace organizations...') placed prominently
- [ ] Length still ≤250 lines — this task adds depth, not bloat. If the new sections push past 250, prune redundant operational text (further docs migration if needed).
- [ ] No regression of fix-readme-s (Terminal-Bench stays gone)
- [ ] No regression of rewrite-readme-manifesto-5 (manifesto opening stays; docs/GUIDE.md split stays)
- [ ] cargo build + cargo test pass
- [ ] cargo install --path . was run before claiming done

## Process note
This is the third README task in the chain (fix-readme-s → rewrite-readme-manifesto-5 → this). They compose: surgical removal, structural rewrite, depth refinement. After all three land, the README reads as a theory-led cybernetic-system manifesto with operational details cleanly delegated to docs/. That matches what poietic.life already says — closing the gap between the website's framing and GitHub's first impression.

Depends on

Required by

done refine-readme-concrete

Log

2026-05-04T15:25:27.542162160+00:00 Task paused
2026-05-04T15:25:58.224454475+00:00 Task published
2026-05-04T15:49:06.378935732+00:00 Spawned by coordinator --executor claude --model opus
2026-05-04T15:49:16.050021657+00:00 Starting: reading current README + prior task artifacts
2026-05-04T16:00:02.909675251+00:00 README at 247 lines (target ≤250); cybernetic framing, validation-bottleneck, theory-led design, proof surface, what-it-is-not, reviewer-path, core interpretive sentence all added; section renames applied
2026-05-04T16:00:13.535166431+00:00 Validated: cargo build OK; cargo test --lib 2163 passed 0 failed; cargo install --path . succeeded
2026-05-04T16:00:14.186340978+00:00 No regression: Terminal-Bench absent; manifesto opening + docs/GUIDE.md split preserved
2026-05-04T16:01:26.979694569+00:00 Committed: 39fbcbb8a — pushed to remote (wg/agent-2311/refine-readme-cybernetic)
2026-05-04T16:02:26.464595862+00:00 Task pending eval (agent reported done; awaiting `.evaluate-*` to score)
2026-05-04T16:04:17.517961027+00:00 PendingEval → Done (evaluator passed; downstream unblocks)