rawphp · rawphp · Jul 26, 2026 · Jul 25, 2026 · Jul 26, 2026
diff --git a/README.md b/README.md
@@ -1,22 +1,36 @@
 # Do Work
 
-A Claude Code and Codex skill that turns natural-language briefs into discrete, traceable tasks and executes them autonomously — with TDD, evidence gates, review, and a git commit per task.
+An agent-harness skill that turns natural-language briefs into discrete, traceable tasks and executes them autonomously — with TDD, evidence gates, review, and a git commit per task. Works with any agent that loads skills from a shared hub (Claude Code, Codex, Cursor, and others).
 
 Two commands: `/do-work start` to define the work, `/do-work go` to execute it.
 
+## User documentation
+
+Task-based guides for installing and running `/do-work` (not contributor internals):
+
+| Guide | Contents |
+|-------|----------|
+| [docs/README.md](docs/README.md) | Docs index |
+| [docs/getting-started.md](docs/getting-started.md) | Install → first start → first go |
+| [docs/concepts.md](docs/concepts.md) | UR, REQ, gates, evidence |
+| [docs/commands.md](docs/commands.md) | Command and flag reference |
+| [docs/troubleshooting.md](docs/troubleshooting.md) | Common failure symptoms |
+| [docs/HOW-IT-WORKS.md](docs/HOW-IT-WORKS.md) | Phase-by-phase deep dive |
+
 <p align="center">
  <img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License">
  <img src="https://img.shields.io/badge/tests-219%2F219-brightgreen?style=flat-square" alt="Tests">
 </p>
 
 <p align="center">
- <strong>Supported AI Providers</strong><br>
+ <strong>Any agent harness</strong><br>
  <a href=".claude/">
- <img src="https://img.shields.io/badge/Claude_Code-Anthropic-orange?style=flat-square&logo=anthropic" alt="Claude Code">
+ <img src="https://img.shields.io/badge/Claude_Code-example-orange?style=flat-square&logo=anthropic" alt="Claude Code">
  </a>
  <a href=".codex/">
- <img src="https://img.shields.io/badge/Codex_CLI-OpenAI-412991?style=flat-square&logo=openai" alt="Codex CLI">
+ <img src="https://img.shields.io/badge/Codex_CLI-example-412991?style=flat-square&logo=openai" alt="Codex CLI">
  </a>
+ <img src="https://img.shields.io/badge/any_skills_hub_agent-welcome-brightgreen?style=flat-square" alt="Any skills hub agent">
 </p>
 
 ---
@@ -44,7 +58,7 @@ curl -fsSL https://raw.githubusercontent.com/agent-native/do-work/main/install.s
 git clone https://github.com/agent-native/do-work.git ~/.agents/skills/do-work
 ```
 
-Override the hub directory with `AGENTS_SKILLS_HUB` (same as `install.sh`). Wire Claude Code, Codex, or other agents to load skills from that hub.
+Override the hub directory with `AGENTS_SKILLS_HUB` (same as `install.sh`). Wire any agent harness to load skills from that hub.
 
 ---
 

diff --git a/docs/HOW-IT-WORKS.md b/docs/HOW-IT-WORKS.md
@@ -1,12 +1,14 @@
 # How do-work Works
 
+> **Operators / first run:** use [getting-started.md](getting-started.md) for install and the happy path. This page is the phase-by-phase deep dive (design rationale included).
+
 A walkthrough of the do-work system — every phase, every file it produces, and the design reasoning behind each choice.
 
 ---
 
 ## What it is
 
-do-work is a Claude Code skill that turns a natural-language brief into a sequence of small, traceable, individually-committed tasks — executed autonomously with TDD.
+do-work is an agent-harness skill that turns a natural-language brief into a sequence of small, traceable, individually-committed tasks — executed autonomously with TDD. It runs on any agent that loads skills from a shared hub.
 
 It is **file-based**: every artifact (brief, decomposed task, claim stamp, commit) is a file in the project's git history. There is no daemon, no database, no in-memory queue, no central coordinator.
 
@@ -328,6 +330,10 @@ Defaults are picked from REQ shape (parallel claim ordering, layer enforcement)
 
 ## Reference
 
+- [getting-started.md](getting-started.md) — install and first run
+- [concepts.md](concepts.md) — user-facing mental model
+- [commands.md](commands.md) — command reference
+- [troubleshooting.md](troubleshooting.md) — failure symptoms
 - `SKILL.md` — full command reference and migration semantics
 - `agents/*.md` — per-phase agent instructions
 - `lib/*.sh` — coordination primitives (claim, footprint, deps, heartbeat, deadlock, cycle)

diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,43 @@
+# Do Work — user documentation
+
+Task-based guides for people who install and run `/do-work` in a project. Works with any agent harness wired to the shared skills hub.
+
+## Start here
+
+| If you want to… | Read |
+|-----------------|------|
+| Install the skill and run your first brief end-to-end | [Getting started](getting-started.md) |
+| Understand UR, REQ, `start` / `go`, and the gates | [Concepts](concepts.md) |
+| Look up a command or flag | [Commands](commands.md) |
+| Fix a failure symptom | [Troubleshooting](troubleshooting.md) |
+
+## Deeper reference
+
+| Page | Audience |
+|------|----------|
+| [How it works](HOW-IT-WORKS.md) | Operators who want phase-by-phase design detail |
+| [../README.md](../README.md) | Install one-liner, quick start, config overview |
+| [../agents/config.md](../agents/config.md) | Full `config.yml` schema |
+| [../SKILL.md](../SKILL.md) | Skill entrypoint and full behavioural reference |
+| [../CONTRIBUTING.md](../CONTRIBUTING.md) | Contributors changing the skill itself |
+
+## Happy path (two commands)
+
+```text
+/do-work start I need a user settings page with email and password change
+/do-work go UR-001
+```
+
+`start` records the brief and builds the backlog. `go` checks coverage, then runs the backlog when confidence meets the project threshold (default 90%).
+
+## Docs map
+
+```text
+docs/
+├── README.md ← you are here (index)
+├── getting-started.md ← install → first start → first go
+├── concepts.md ← mental model
+├── commands.md ← command reference
+├── troubleshooting.md ← symptoms → fixes
+└── HOW-IT-WORKS.md ← deep dive (design + phases)
+```
diff --git a/docs/commands.md b/docs/commands.md
@@ -0,0 +1,248 @@
+# Commands reference
+
+Lookup for `/do-work` commands: what each one does, when to use it, and which flags exist in the skill today.
+
+Invoke with no subcommand for help plus suggested next steps:
+
+```text
+/do-work
+```
+
+## Command map (when to use which)
+
+| Goal | Command |
+|------|---------|
+| First-time project folders | `/do-work install` |
+| Align old `.do-work/` with current skill | `/do-work upgrade` |
+| New work end-to-end (define) | `/do-work start [brief]` |
+| Execute a defined UR | `/do-work go UR-NNN` |
+| Record brief only | `/do-work intake [brief]` |
+| Creative review only | `/do-work ideate UR-NNN` |
+| Grill the brief | `/do-work question UR-NNN` |
+| Decompose only | `/do-work capture UR-NNN` |
+| Score coverage only | `/do-work verify UR-NNN` |
+| Sharpen REQ quality | `/do-work audit UR-NNN` |
+| Run backlog (no verify gate) | `/do-work run [UR-NNN]` |
+| Live situation room | `/do-work status [UR-NNN]` |
+| Stuck REQ → backlog | `/do-work unblock REQ-NNN` |
+| Re-dispatch stopped REQ | `/do-work resume REQ-NNN` |
+| Validate integrated UR paths | `/do-work close UR-NNN` |
+| Learn from run history | `/do-work retro` |
+| Draft social posts | `/do-work log` |
+
+---
+
+## Orchestrators
+
+### `/do-work start [brief]`
+
+**Job:** Record a brief and build the REQ backlog in one shot.
+
+**Pipeline:** intake → ideate (default) → capture. Does **not** run verify or implementation.
+
+| Flag | Effect |
+|------|--------|
+| `--no-ideate` | Skip ideate and its Grill/Continue/Stop gate |
+| `--no-layers` | Skip layer-coverage checks for this UR; records `layers_in_scope: []` |
+
+**Notes:**
+
+- Auto-installs `.do-work/` if missing
+- Ideate gate: **Grill** / **Continue** / **Stop** (Stop halts before capture)
+- After success, may offer next steps (Run Go / Verify only / Skip) when `next_steps.enabled` is true
+
+**Example:**
+
+```text
+/do-work start Add password reset email with rate limiting
+/do-work start Quick typo fix in README --no-ideate --no-layers
+```
+
+### `/do-work go [UR-NNN]`
+
+**Job:** Verify coverage for a UR, then audit and run when the confidence gate passes.
+
+**Pipeline:** verify → (if gate passes) audit → run → optional close offer → optional log.
+
+| Flag | Effect |
+|------|--------|
+| `--force` | Run even if score &lt; threshold; verify still runs |
+| `--auto-fix` | One verify pass that creates missing REQs, re-scores; run only if ≥ threshold afterward |
+| `--no-layers` | Skip layer-coverage checks; passed through to capture if `--auto-fix` re-runs capture |
+
+**Threshold:** `verify.threshold` in `.do-work/config.yml` (default **90**).
+
+**Example:**
+
+```text
+/do-work go UR-001
+/do-work go UR-001 --auto-fix
+/do-work go UR-001 --force
+```
+
+---
+
+## Setup
+
+### `/do-work install`
+
+Creates the per-project `.do-work/` folder structure and default `config.yml` in the current project.
+
+Use when you want structure before the first brief. `/do-work start` also installs automatically.
+
+### `/do-work upgrade`
+
+Brings existing `.do-work/` state into conformance with the current skill (detectors + fixes). Destructive rows require interactive confirmation. Idempotent.
+
+Use after upgrading the skill install when help or startup mentions pending migration / stale config keys.
+
+---
+
+## Define work (granular)
+
+### `/do-work intake [brief]`
+
+Records the brief **verbatim** as the next `UR-NNN/input.md`. No decomposition.
+
+Use when you want the UR on disk before ideate/capture, or to script the pipeline yourself.
+
+### `/do-work ideate [UR-NNN]`
+
+Surfaces assumptions, risks, and connections into `UR-NNN/ideate.md`. Ends with the interactive gate when run in flows that expect it.
+
+Use to pressure-test a brief without starting capture yet (or re-run after edits).
+
+### `/do-work question [UR-NNN]`
+
+Grills you one question at a time about the brief (assumptions, gaps, constraints).
+
+Use from the ideate **Grill** path or standalone when the brief is thin.
+
+### `/do-work capture [UR-NNN]`
+
+Decomposes `input.md` (and `ideate.md` if present) into backlog `REQ-NNN-slug.md` files. Applies layer rules, integration blocks, dependency cycle checks.
+
+Use to resume after a failed start-at-capture, or to re-decompose after you edited the brief.
+
+---
+
+## Check quality
+
+### `/do-work verify [UR-NNN]`
+
+Scores REQ coverage against the original brief (0–100%) and lists gaps. Includes layer, integration-block, and partial-confidence structural checks.
+
+| Flag | Effect |
+|------|--------|
+| `--auto-fix` | Create missing REQs, then re-score |
+
+Use before `run` when you are not using `go`, or after manual REQ edits.
+
+### `/do-work audit [UR-NNN]`
+
+Interrogates acceptance criteria quality; auto-fixes vague spots; reports changes. Always runs inside `go` when execution will proceed; does not re-score verify.
+
+Use standalone to sharpen REQs without starting the run loop.
+
+---
+
+## Execute and observe
+
+### `/do-work run [UR-NNN]`
+
+Executes the backlog: claim REQ → worker TDD loop → evidence validation → policy checks → post-build review → archive/ledger. Optional `UR-NNN` limits work to that UR’s REQs.
+
+Does **not** run the verify confidence gate (unlike `go`).
+
+| Flag | Effect |
+|------|--------|
+| `--parallel N` | One terminal dispatches up to N concurrent workers (default serial; capped at 10). Uses `parallel.max_workers` defaults when applicable |
+| `--budget <amount>` | Cap estimated model spend for this run; overrides `cost.budget`. Stops at the next REQ boundary after the in-flight REQ finishes integration. Empty budget = unlimited |
+
+**Parallelism without flags:** open multiple terminals and run `/do-work run` in each; claims coordinate via the filesystem/`git mv`.
+
+### `/do-work status [UR-NNN]`
+
+Read-only situation room: REQs, claimers (`hostname.pid`), heartbeats, deadlock warnings, coverage rollup. Optional UR scope.
+
+Use whenever something looks stuck or you are running parallel workers.
+
+### `/do-work unblock REQ-NNN`
+
+Forces a REQ out of `working/` back to the backlog: strips claim stamp, resets status. Includes judgment when partial commits exist.
+
+Use when a worker died, heartbeat is stale, or you need to break a deadlock after triage with `status`.
+
+Requires a REQ id (example: `/do-work unblock REQ-042`).
+
+### `/do-work resume REQ-NNN`
+
+Re-dispatches a fresh worker for a **stopped** REQ while preserving the claim and refreshing the heartbeat.
+
+Use after `concurrent-conflict` or a transient worker failure—not as a substitute for `unblock` when the claim should be cleared.
+
+Requires a REQ id (example: `/do-work resume REQ-042`).
+
+### `/do-work close UR-NNN`
+
+Validates the integrated result of a UR against the verbatim brief: walks path-unit entry points to terminal states and writes a closure report under the UR folder.
+
+Requires a UR id. `go` may offer close after a clean drain when path-unit REQs exist and no `closure.md` yet. Closure gaps do not block the log step.
+
+---
+
+## Learn and publish drafts
+
+### `/do-work retro`
+
+Mines the run ledger (and related feedback signals) into a human report and regenerates `.do-work/state/calibration.md` as advisory capture guidance.
+
+Use after several runs when you want capture to learn from history.
+
+### `/do-work log`
+
+Generates build-in-public **draft** posts for platforms listed in `log.platforms` (for example `x`, `linkedin`, `blog`). You choose drafts; history is recorded so the same work is not re-prompted forever.
+
+Skipped when `log.enabled` is false or `platforms` is empty. `go` can trigger log automatically after a clean run.
+
+---
+
+## Quick reference table
+
+Same surface as README / SKILL quick reference:
+
+| Command | What it does |
+|---------|--------------|
+| `/do-work start [brief]` | Brief + REQs; ideate on by default |
+| `/do-work start [brief] --no-ideate` | Skip creative review |
+| `/do-work start [brief] --no-layers` | Skip layer checks for this UR |
+| `/do-work go [UR-NNN]` | Verify; auto-run if ≥ threshold |
+| `/do-work go [UR-NNN] --force` | Verify + run regardless of score |
+| `/do-work go [UR-NNN] --auto-fix` | Verify, fix gaps once, run if ≥ threshold |
+| `/do-work go [UR-NNN] --no-layers` | Verify + run; skip layer checks |
+| `/do-work install` | Create `.do-work/` |
+| `/do-work upgrade` | Conformance fixes for `.do-work/` |
+| `/do-work intake [brief]` | Verbatim UR only |
+| `/do-work capture [UR-NNN]` | UR → REQ files |
+| `/do-work question [UR-NNN]` | Interactive grilling |
+| `/do-work audit [UR-NNN]` | REQ quality pass |
+| `/do-work ideate [UR-NNN]` | Assumptions and risks |
+| `/do-work verify [UR-NNN]` | Coverage score + gaps |
+| `/do-work verify [UR-NNN] --auto-fix` | Verify + create missing REQs |
+| `/do-work run [UR-NNN]` | Execute backlog (optional UR scope) |
+| `/do-work run --parallel N` | Single-session parallel workers |
+| `/do-work run --budget <amount>` | Spend cap for the run |
+| `/do-work status [UR-NNN]` | Situation room |
+| `/do-work close UR-NNN` | Integrated UR closure report |
+| `/do-work unblock REQ-NNN` | Stuck REQ → backlog |
+| `/do-work resume REQ-NNN` | Re-dispatch stopped REQ |
+| `/do-work retro` | Ledger → calibration report |
+| `/do-work log` | Build-in-public drafts |
+| `/do-work` | Help |
+
+## Related
+
+- [Getting started](getting-started.md)
+- [Concepts](concepts.md)
+- [Troubleshooting](troubleshooting.md)
+- Config schema: [`agents/config.md`](../agents/config.md)