refine-readme-concrete — Workgraph live mirror

Metadata

Status	done
Assigned	`agent-2317`
Agent identity	`3184716484e6f0ea08bb13539daf07686ee79d440505f1fdf2de0357707034c3`
Model	`claude:opus`
Created	2026-05-04T15:28:53.810586333+00:00
Started	2026-05-04T16:04:20.705590791+00:00
Completed	2026-05-04T16:16:42.550367847+00:00
Tags	`fix,docs,readme,onboarding`, `eval-scheduled`
Eval score	0.88
└ blocking impact	0.90
└ completeness	0.90
└ constraint fidelity	0.10
└ coordination overhead	0.90
└ correctness	0.90
└ downstream usability	0.85
└ efficiency	0.85
└ intent fidelity	0.87
└ style adherence	0.85

Description

Final pass on the README rewrite chain. Combines (1) concrete Getting Started flow with wg tui as the protagonist + (2) the deeper viral/positioning material the user developed: 'The work OS for human/AI organizations', 'Watch the organization think', 'The company is an output of the product, not a wrapper around it', visual-first opening with TUI GIF, real-trace demos instead of synthetic, section-reorder mirroring the website's ladder.

User direct quotes 2026-05-04 (combined from two refinement notes):

Quote 1 (Getting Started flow)

'wg tui needs to be clearly the ideal interface. we need a startup that's like install... ok now once installed, init with your preferred executor / system. show multiple ways (claude, codex, oai-compat wg nex) to init a .wg in a directory. then start the service. then wg tui.'

Quote 2 (the holy-shit / viral framing)

'I'm using this to do crazy stuff and I kind of want to show that to people in a way that catches them. ... It has to be like, holy shit, you know, it's not some dumb thing that we're doing. We're doing something crazy.'

'We didn't start this company because we wanted to start a company. We started it because we wanted to apply for grants to bootstrap the development of this system. ... The grant that's mentioned on poetic.life has been submitted. ... I did work with an agent one-on-one to implement a few copy edit type fixes in the repo, rather than just typing them in Emacs.'

'wg tui is the jam.'

The reframe — viral / strategic copy

Sharpest positioning (replace prior 'cybernetic system' opening)

# WorkGraph

**The work OS for human/AI organizations.**

Agents can come and go. The graph remains.

![WorkGraph TUI showing tasks, agents, claims, logs, and dependencies](docs/assets/wg-tui.gif)

WorkGraph 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.

Launch the operating surface:

\`\`\`bash
wg tui
\`\`\`

The validation-bottleneck section (already specced; tighten copy)

## The bottleneck is validation

AI can generate more work than humans can inspect.

WorkGraph exists because the hard problem is no longer only execution. It is
knowing what was done, what failed, what evidence exists, where judgment entered,
and how the organization should respond.

The proof surface — real Poietic, not 'examples'

## Why this is different

Poietic PBC was formed, organized, and grant-funded through WorkGraph.

These are not demos. They are public traces of real institutional work.

- Company formation
- Grant drafting and submission
- Scientific analysis
- Website and theory development

The user's viral candidate phrase to weave in somewhere prominent:

The company is not a wrapper around the product. The company is an output of the product.

OR (alternate):

Poietic is not merely building WorkGraph. Poietic is being built through WorkGraph.

Start the OS — the 4-step Getting Started

## Start the OS

\`\`\`bash
cargo install --git https://github.com/graphwork/workgraph
wg init
wg tui
\`\`\`

### Pick your executor

\`\`\`bash
wg init --route claude-cli                                              # Claude (default)
wg init --route codex-cli                                               # Codex
wg init -m nex:qwen3-coder -e https://your-endpoint:8080                # any OpenAI-compatible
\`\`\`

### Then let agents work

\`\`\`bash
wg service start
\`\`\`

Closing — 'Watch the organization think'

The README's effective punchline. Land it somewhere:

Watch the organization think.

OR a one-liner closing the proof-surface section:

The agents did not replace me. They made the work inspectable enough that I could steer it.

The section ORDER (mirror poietic.life's ladder)

The website's ladder is: mission → product/practice/theory → public traces → start graph.

The README must MIRROR THIS ORDER. New required ordering:

Title + manifesto opening (work OS line)
The bottleneck is validation (founding premise)
What WorkGraph is / what it gives you
What WorkGraph is not (block wrong comparisons)
Theory-led design
The proof surface — Poietic-builds-itself with real traces
Start the OS (Getting Started — 4 steps, three executor paths)
Reviewer's path / further reading
Links to docs/

CRITICAL: wg tui is shown FIRST as the launch command (in the manifesto opening's `bash` block), THEN re-shown in Getting Started. Both placements drive home it's the protagonist.

What MUST NOT happen

Do NOT lead with synthetic 'Design API / Build backend / Write tests' demo. Use real Poietic traces (grant, incorporation, theory, website) as the example.
Do NOT bury wg tui after install/config/agent material. It's the FIRST command shown.
Do NOT use 'task graph for getting things done' as the tagline. Use 'work OS' framing.
Do NOT re-add Terminal-Bench in any framing (fix-readme-s removed it; keep it gone).
Do NOT exceed ~200-250 lines. If new material pushes past, prune more operational text into docs/GUIDE.md.

What this task supersedes / extends

rewrite-readme-manifesto-5: structural rewrite + docs split. This task BUILDS on top.
refine-readme-cybernetic: cybernetic framing + validation-bottleneck + Poietic proof surface + theory-led + 'what is not' + reviewer path. This task RESHAPES the section order and SHARPENS the opening.

If those prior tasks landed cleanly: this task is targeted (reorder + Getting Started + visual-first). If those landed poorly: this task corrects the gaps.

GIF / screenshot — the visual front door

The README opening should include a TUI screenshot or GIF inline. If docs/assets/wg-tui.gif doesn't exist, this task either:

Creates a placeholder and adds a TODO note ('record real GIF before public push'), OR
Adds the markdown image reference even if the file doesn't exist yet (graceful fallback for GitHub renderer)

User intent: 'first emotional contact should be wg tui.' A static screenshot is acceptable; a real animated capture is better.

Validation

README opening uses 'work OS' framing, NOT 'task graph for getting things done'
Visual element (GIF or screenshot) referenced in the opening, before any text-heavy explanation
wg tui is the FIRST command shown in the entire README (not buried)
Section order mirrors poietic.life: mission → validation-bottleneck → what-it-is → what-it-is-not → theory → proof-surface → start-the-OS → reviewer-path → docs-links
'The company is not a wrapper around the product. The company is an output of the product.' (or equivalent 'Poietic is being built through WorkGraph') appears somewhere prominent
Three init paths shown (claude / codex / nex with endpoint), each as a one-liner under 'Pick your executor'
Real Poietic traces named in the proof surface (grant submission, incorporation, scientific analysis, website) — NOT synthetic demos
Closing punchline ('Watch the organization think' or 'The agents did not replace me — they made the work inspectable enough I could steer it') lands
Length still ≤250 lines; prune to docs/ if needed
No regression of fix-readme-s (Terminal-Bench gone), rewrite-readme-manifesto-5 (manifesto + split), refine-readme-cybernetic (cybernetic framing, what-is-not, reviewer path)
cargo build + cargo test pass
cargo install --path . was run before claiming done

Process note

This is the FOURTH README task in the chain (fix-readme-s → rewrite-readme-manifesto-5 → refine-readme-cybernetic → this).

After this lands the README does what poietic.life already does: theory-led, proof-led, tool-second. Reviewers can't easily mis-categorize as another agent framework because the order forces them through mission → why → proof → wg tui before they hit any CLI dance. The 'company is an output of the product' line is the viral hook the user explicitly wants.

The TUI being framed as the protagonist matters because it IS the experience that demonstrates the cybernetic loop. Treating it as 'one of many ways' undersells what makes WorkGraph remarkable in actual use.

## Description
Final pass on the README rewrite chain. Combines (1) concrete Getting Started flow with `wg tui` as the protagonist + (2) the deeper viral/positioning material the user developed: 'The work OS for human/AI organizations', 'Watch the organization think', 'The company is an output of the product, not a wrapper around it', visual-first opening with TUI GIF, real-trace demos instead of synthetic, section-reorder mirroring the website's ladder.

User direct quotes 2026-05-04 (combined from two refinement notes):

### Quote 1 (Getting Started flow)
> 'wg tui needs to be clearly the ideal interface. we need a startup that's like install... ok now once installed, init with your preferred executor / system. show multiple ways (claude, codex, oai-compat wg nex) to init a .wg in a directory. then start the service. then wg tui.'

### Quote 2 (the holy-shit / viral framing)
> 'I'm using this to do crazy stuff and I kind of want to show that to people in a way that catches them. ... It has to be like, holy shit, you know, it's not some dumb thing that we're doing. We're doing something crazy.'

> 'We didn't start this company because we wanted to start a company. We started it because we wanted to apply for grants to bootstrap the development of this system. ... The grant that's mentioned on poetic.life has been submitted. ... I did work with an agent one-on-one to implement a few copy edit type fixes in the repo, rather than just typing them in Emacs.'

> 'wg tui is the jam.'

## The reframe — viral / strategic copy

### Sharpest positioning (replace prior 'cybernetic system' opening)

```md
# WorkGraph

**The work OS for human/AI organizations.**

Agents can come and go. The graph remains.

![WorkGraph TUI showing tasks, agents, claims, logs, and dependencies](docs/assets/wg-tui.gif)

WorkGraph 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.

Launch the operating surface:

\`\`\`bash
wg tui
\`\`\`
```

### The validation-bottleneck section (already specced; tighten copy)

```md
## The bottleneck is validation

AI can generate more work than humans can inspect.

WorkGraph exists because the hard problem is no longer only execution. It is
knowing what was done, what failed, what evidence exists, where judgment entered,
and how the organization should respond.
```

### The proof surface — real Poietic, not 'examples'

```md
## Why this is different

Poietic PBC was formed, organized, and grant-funded through WorkGraph.

These are not demos. They are public traces of real institutional work.

- Company formation
- Grant drafting and submission
- Scientific analysis
- Website and theory development
```

The user's viral candidate phrase to weave in somewhere prominent:

> **The company is not a wrapper around the product. The company is an output of the product.**

OR (alternate):

> **Poietic is not merely building WorkGraph. Poietic is being built through WorkGraph.**

### Start the OS — the 4-step Getting Started

```md
## Start the OS

\`\`\`bash
cargo install --git https://github.com/graphwork/workgraph
wg init
wg tui
\`\`\`

### Pick your executor

\`\`\`bash
wg init --route claude-cli # Claude (default)
wg init --route codex-cli # Codex
wg init -m nex:qwen3-coder -e https://your-endpoint:8080 # any OpenAI-compatible
\`\`\`

### Then let agents work

\`\`\`bash
wg service start
\`\`\`
```

### Closing — 'Watch the organization think'

The README's effective punchline. Land it somewhere:

> **Watch the organization think.**

OR a one-liner closing the proof-surface section:

> **The agents did not replace me. They made the work inspectable enough that I could steer it.**

## The section ORDER (mirror poietic.life's ladder)

The website's ladder is: mission → product/practice/theory → public traces → start graph.

The README must MIRROR THIS ORDER. New required ordering:

1. Title + manifesto opening (work OS line)
2. The bottleneck is validation (founding premise)
3. What WorkGraph is / what it gives you
4. What WorkGraph is not (block wrong comparisons)
5. Theory-led design
6. **The proof surface** — Poietic-builds-itself with real traces
7. **Start the OS** (Getting Started — 4 steps, three executor paths)
8. Reviewer's path / further reading
9. Links to docs/

CRITICAL: `wg tui` is shown FIRST as the launch command (in the manifesto opening's \`bash\` block), THEN re-shown in Getting Started. Both placements drive home it's the protagonist.

## What MUST NOT happen

- Do NOT lead with synthetic 'Design API / Build backend / Write tests' demo. Use real Poietic traces (grant, incorporation, theory, website) as the example.
- Do NOT bury `wg tui` after install/config/agent material. It's the FIRST command shown.
- Do NOT use 'task graph for getting things done' as the tagline. Use 'work OS' framing.
- Do NOT re-add Terminal-Bench in any framing (fix-readme-s removed it; keep it gone).
- Do NOT exceed ~200-250 lines. If new material pushes past, prune more operational text into docs/GUIDE.md.

## What this task supersedes / extends

- rewrite-readme-manifesto-5: structural rewrite + docs split. This task BUILDS on top.
- refine-readme-cybernetic: cybernetic framing + validation-bottleneck + Poietic proof surface + theory-led + 'what is not' + reviewer path. This task RESHAPES the section order and SHARPENS the opening.

If those prior tasks landed cleanly: this task is targeted (reorder + Getting Started + visual-first). If those landed poorly: this task corrects the gaps.

## GIF / screenshot — the visual front door

The README opening should include a TUI screenshot or GIF inline. If `docs/assets/wg-tui.gif` doesn't exist, this task either:
- Creates a placeholder and adds a TODO note ('record real GIF before public push'), OR
- Adds the markdown image reference even if the file doesn't exist yet (graceful fallback for GitHub renderer)

User intent: 'first emotional contact should be wg tui.' A static screenshot is acceptable; a real animated capture is better.

## Validation
- [ ] README opening uses 'work OS' framing, NOT 'task graph for getting things done'
- [ ] Visual element (GIF or screenshot) referenced in the opening, before any text-heavy explanation
- [ ] `wg tui` is the FIRST command shown in the entire README (not buried)
- [ ] Section order mirrors poietic.life: mission → validation-bottleneck → what-it-is → what-it-is-not → theory → proof-surface → start-the-OS → reviewer-path → docs-links
- [ ] 'The company is not a wrapper around the product. The company is an output of the product.' (or equivalent 'Poietic is being built through WorkGraph') appears somewhere prominent
- [ ] Three init paths shown (claude / codex / nex with endpoint), each as a one-liner under 'Pick your executor'
- [ ] Real Poietic traces named in the proof surface (grant submission, incorporation, scientific analysis, website) — NOT synthetic demos
- [ ] Closing punchline ('Watch the organization think' or 'The agents did not replace me — they made the work inspectable enough I could steer it') lands
- [ ] Length still ≤250 lines; prune to docs/ if needed
- [ ] No regression of fix-readme-s (Terminal-Bench gone), rewrite-readme-manifesto-5 (manifesto + split), refine-readme-cybernetic (cybernetic framing, what-is-not, reviewer path)
- [ ] cargo build + cargo test pass
- [ ] cargo install --path . was run before claiming done

## Process note
This is the FOURTH README task in the chain (fix-readme-s → rewrite-readme-manifesto-5 → refine-readme-cybernetic → this).

Depends on

Required by

(none)

Log

2026-05-04T15:28:53.783609004+00:00 Task paused
2026-05-04T15:30:57.537929094+00:00 Task published
2026-05-04T16:04:20.705594668+00:00 Spawned by coordinator --executor claude --model opus
2026-05-04T16:05:39.261491172+00:00 Starting README refine: visual-first opening + work OS framing + 4-step Getting Started with 3 init paths + section reorder mirroring poietic.life ladder
2026-05-04T16:15:39.778115765+00:00 Validated: cargo build OK; cargo test --lib 2163 passed 0 failed; cargo install --path . succeeded
2026-05-04T16:15:55.109911841+00:00 README is 163 lines (≤250 cap); section order mirrors poietic.life ladder; wg tui is first command shown; three init paths in Pick-your-executor block; 'company is an output of the product' line preserved; 'Watch the organization think' closes
2026-05-04T16:16:22.100850037+00:00 Committed: ef14fce82 — pushed to remote (wg/agent-2317/refine-readme-concrete)
2026-05-04T16:16:42.550376002+00:00 Task pending eval (agent reported done; awaiting `.evaluate-*` to score)
2026-05-04T16:18:34.631863214+00:00 PendingEval → Done (evaluator passed; downstream unblocks)