refactor: overhaul workflow prompts with progressive loading

AGENTS.md

@@ -93,3 +93,24 @@ artifact_host: https://linear-agent.blmapp.com
 - Never run `scripts/sync.sh` pointed at a consumer repo automatically -
   syncs land in consumers via their own `update-skills` PR flow.
 - Don't commit `./tmp/` or `.DS_Store`.
+
+## Completing changes
+
+For an implementation or PR request, continue through the scoped edits,
+relevant verification, fixes, and requested PR handoff. Create a work branch or
+isolated worktree as needed. A plan or first implementation is not completion.
+Existing session authorization covers repeated in-scope local edits and checks;
+merge, release, deployment, production actions, and consumer sync need their own
+scope of authorization.
+
+Inspect the affected instructions, callers, and formats. Load other docs only
+when their subject matters to the change. Validate Markdown routes and sync
+behavior for skill changes; run daemon checks when daemon code or its contracts
+change. The local dispatch-survival check uses disposable fixtures. Continue
+its local repair/rerun cycle without asking again. Reuse passing checks until
+a relevant input changes; read back pushes and PR state before reporting them.
+
+Keep discovery descriptions brief and specific. Put conditional procedures in
+linked references with a clear read condition. Preserve model-independent role,
+permission, output, and evidence contracts; avoid adding a gate solely because
+a model once needed handholding.

CLAUDE.md

@@ -6,26 +6,10 @@ artifacts go) is defined in `AGENTS.md` - the skills read it from there.
 
 ## Rules
 
-- **You must verify after every mutation.** After a merge, push, PR
-  creation, file move, or any operation that changes state: read the
-  actual result back. Never trust command output alone - check that the
-  change landed where you expected it to.
-
-- **You must not solve discoverable problems.** If the agent can query it
-  at runtime (via MCP, the environment, or the repo), don't hardcode it.
-  Describe roles, boundaries, and rules - not configuration.
-
-- **Less is more.** Every line should earn its place. If removing a line
-  wouldn't change behavior, remove it. Overspecification leads to
-  configuration ceremony, leads to brittleness. When things are brittle,
-  they break.
-
-- **No feedback loops.** A step that mutates code after review invalidates
-  downstream work. The pipeline is linear. Refactoring and cold-read are
-  manual skills, never inline.
-
-- **You must never use em dashes.** Use commas, periods, colons, or
-  parentheses instead.
+- Discover runtime configuration through the repo or tools; do not hardcode it.
+- Fixes after review invalidate affected evidence. Keep final QA after the last
+  reviewed code change. Refactoring and cold-read remain manual skills.
+- Do not use em dashes.
 
 ## Claude-specific notes
 

README.md

@@ -14,8 +14,8 @@ The system at a glance:
 
 _Source: [docs/workflow-map.excalidraw](docs/workflow-map.excalidraw)_
 
-And the story of how it got here - conducted by hand, then Orchestra running
-itself, next the factory that feeds itself:
+The evolution from manually coordinated stages to an autonomous pipeline,
+with signal-driven intake as a direction for further automation:
 
 ![From workflow to software factory](docs/software-factory-story.png)
 
@@ -28,21 +28,21 @@ _Source: [docs/software-factory-story.excalidraw](docs/software-factory-story.ex
 |---|---|---|
 | `claude/skills/` | Claude Code workflow skills (`/do`, `/create-brief`, `/discussion`, `/investigate`, `/prepare-pull-request`, `postmortem`, `postmortem-loop`, `sentry-loop`, `codex`, `excalidraw-pr-diagrams`, `cold-read`) | `.claude/skills/` |
 | `claude/agents/` | Claude sub-agent definitions (reviewers, researchers, verifiers, socrates) | `.claude/agents/` |
-| `codex/skills/` | Codex role skills (implementer, verifiers, reviewers, researcher, investigator, refactor-simple/-deep) - thin pointers into `references/` | `.codex/skills/` |
+| `codex/skills/` | Codex `/do` and `/investigate` workflows, plus role skills for implementation, verification, review, research, and refactoring | `.codex/skills/` |
 | `references/` | Shared skill-system documents: work-item formats, verification methods, rubrics, sub-agent role instructions and output formats | `.references/` |
 | `templates/` | Per-project scaffolding (`AGENTS.md`, `CLAUDE.md`) to copy into a new consumer repo and fill in | not synced - copied once by hand |
 | `daemon/` | Orchestra-only Linear agent webhook service (macOS/launchd behind a Cloudflare Tunnel, or Linux/systemd); each deployment's identity comes from a site config kept in the consumer repo | not synced |
 | `machines/` | Orchestra-only, versioned physical-machine setup and operations artifacts | not synced |
-| `scripts/sync.sh` | The mirror logic (four `rsync --delete` targets) | - |
+| `scripts/sync.sh` | Mirrors Orchestra-owned entries in four destinations; preserves consumer-only entries | - |
 
 ## The rules that keep this sane
 
 1. **One direction.** orchestra → consumer, via PR. Each consumer repo
    carries an `update-skills` script (e.g. `pnpm update-skills` in
    bloomapi/bloom-mono) that fetches this repo's `main`, runs
    `scripts/sync.sh` against a temp worktree, and opens (or force-updates)
-   the consumer's `chore/orchestra-sync` PR. Run it after pushing a skill
-   change here.
+   the consumer's `chore/orchestra-sync` PR. Once the change is on `main`,
+   run that consumer flow when its sync is authorized.
 2. **Repo-agnostic skills.** Nothing in the synced directories may name a
    specific codebase, database ID, or machine path. All paths are
    consumer-repo-relative (`.references/…`, `.claude/agents/…`).
@@ -53,9 +53,11 @@ _Source: [docs/software-factory-story.excalidraw](docs/software-factory-story.ex
    wherever the consumer's `AGENTS.md` `Work-item tracking` section says
    (GitHub issues, Linear, anything the repo documents), and with no
    instructions there they stay local-only in `./tmp/<id>/`.
-4. **Idempotent.** The sync is a full mirror (`rsync --delete`); running it
-   twice produces zero diff. Nothing in the synced dirs is written to at
-   runtime.
+4. **Idempotent.** Each Orchestra-owned directory is an exact mirror
+   (`rsync --delete` within that entry); consumer-only entries remain.
+   Retired top-level names are removed by explicit lists in the scripts.
+   Running a sync twice produces zero diff. Runtime artifacts live outside
+   the synced instruction directories.
 5. **Postmortems** are posted as comments on the run's work item and PR -
    never as separate tracker issues (local-only when no tracker/anchor
    exists); proposed system changes are applied here in orchestra.
@@ -118,3 +120,17 @@ This repo supersedes the `tyler/` tree of `dcouple/skills`, which previously
 synced to `~/.claude`, `~/.codex`, and `~/.references` on each machine. Skills
 now travel with each consumer repo instead, so clones, CI, and cloud agents
 get them with no machine setup.
+
+## Reading and maintaining the workflows
+
+The Claude and Codex `/do` entrypoints route to stage-specific references:
+load execution boundaries once, then the current stage. Research depth,
+review lanes, and QA follow the work item's evidence requirements and the
+selected harness. Existing authorization carries through scoped edits,
+checks, fixes, and the requested PR handoff; merge and deployment have their
+own authorization boundaries.
+
+Use [WORKFLOW.md](WORKFLOW.md) for the stage map and authoritative role links.
+The [diagram index](docs/README.md) identifies each visual's scope and render
+command. Update both the Excalidraw source and its PNG when a depicted
+workflow changes.