How to use the workflow

How to run a job end-to-end — from a free-form intake file through every stage and into 4_done/. Skim the architecture first if you have not yet — it explains the standalone agent roles (app-init/app-update, orchestrator, operation agents — D-41 folded creation into the orchestrator), the Kanban queues, and the three sources of truth.

Two invocation modes

Every user-invoked workflow prompt (orchestrator, promote, extend, app-init/app-update) can be launched from either of two cwd locations. Both are first-class supported and produce identical job-pipeline behaviour; the canonical rule is _processes/_shared/handoff-paths.md.

Pick one mode per session and stick with it. Each agent detects which mode it was invoked in by inspecting cwd only; sub-tree CLAUDE.md / AGENTS.md auto-loads are informational and do not change the mode. The agent then prints all subsequent "Next step" / "Next action" paths in that same mode, so copy-paste works first try.

The init agent is the one exception: it requires workflow-internal mode for its one-time bootstrap, then its hand-off prints both forms so you can switch to host-root mode for everything afterward if you prefer. Every other agent supports both modes from invocation 1.

Throughout this page, prompt paths are shown in workflow-internal form for brevity (bare _processes/...). When running in host-root mode, prefix every workflow-internal path with _code_workflow/.

Step 0 — First-time setup (run the init agent)

Before any other agent will run, _code_workflow/app.md must exist and not be the bootstrap placeholder ("To be generated", or the older "To Be Generated, once the init process is done."), and _code_workflow/config.json must declare which sub-agent runtimes are available on your machine. Both files are produced by the init agent in one pass (D-33, D-36).

How to run init

1. Open a fresh Claude Code session with cwd = _code_workflow/ (i.e. cd /path/to/_code_workflow && claude). Init runs in its own session so its direct AskUserQuestion carve-out (D-33b) works cleanly.
2. Send the prompt path _processes/00_app/app-init.prompt.md as the first message. Pasting the full prompt still works, but path-only invocation is the intended UX.
3. Answer init's targeted questions via AskUserQuestion. It auto-discovers everything it can from ../ (host's CLAUDE.md, AGENTS.md, README.md, dependency manifests, directory layout) and only asks where it cannot infer.
4. Init writes two files and reports back:
   • _code_workflow/app.md — host-fact H2 sections (Identity, Canonical context files, Tech stack, Directory map, Coding patterns, Security rules, Common commands, Test framework, Documentation conventions, Agent reading rules, Domain glossary, Never-do list). Built from _processes/00_app/app.template.md and validated against _processes/00_app/APP_CONTRACT.md.
   • _code_workflow/config.json — gitignored; shape {"runtimes": {"claude": true, "codex": <probed>}}. Init empirically probes each runtime: claude is recorded true unconditionally; codex is checked by running a trivial codex exec availability probe and looking for a clean response.
5. Hand off to the orchestrator — once init finishes, jump to "Starting a new job".

Re-validating later

Run the dedicated _processes/00_app/app-update.prompt.md agent when the runtime set changes (e.g. you just installed the Codex plugin) or when host facts drift. app-update runs the same deep host survey as app-init, regenerates a clean current app.md preserving only host-backed facts (dropping stale sections), and re-probes runtimes into config.json unconditionally. It is a separate, independently-runnable agent — not a mode or alias of app-init (D-39).

Non-Claude runtimes

Codex CLI, Aider, Cursor, and other agents that can't run the init prompt as-is should follow the manual port flow in _docs/how-to-port.md: copy _processes/00_app/app.template.md to _code_workflow/app.md, fill the host-fact sections by hand against the contract at _processes/00_app/APP_CONTRACT.md, and copy config.example.json to config.json with the right runtimes booleans.

Starting a new job

Two intake paths. Pick the one that matches the job's size.

Running the local app (optional)

The interface/ form works on its own (open it as a file, Copy/Download, hand-place into jobs/0_new/). For a smoother loop there is an optional local helper app — a tiny, zero-dependency Node service (_tools/app/server.js) that serves the form and a dashboard over your live jobs/ tree. It is a trusted local convenience: it binds 127.0.0.1 only, writes only ever to jobs/0_new/<slug>.md, never shells out, and never touches PROGRESS.md / .lock / queue moves / stage artifacts — the orchestrator stays the sole owner of job state.

Start / stop — the installer (recommended; multi-project)

Running the helper in more than one project at once would collide on host port 4319, the container name, and the Compose project name. The installer _tools/app/install.sh fixes that — it leases a unique port + container/compose name for this project from a durable per-user registry, so several projects' helpers run side by side. From the workflow root:

./_tools/app/install.sh install      # lease + build + up  (idempotent; recommended start)
./_tools/app/restart.sh              # same thing (thin shim over install.sh)
./_tools/app/restart.sh down         # bring THIS project down
./_tools/app/install.sh ls           # list every project + its leased port
./_tools/app/install.sh doctor --check-health   # docker/compose + /health diagnosis
./_tools/app/install.sh release      # return this project's port lease
./_tools/app/install.sh gc           # prune leases for deleted projects

The scripts ship executable; bash _tools/app/install.sh <cmd> is the bit-independent fallback for a vendored/zip copy that lost the execute bit. The script is the deterministic source of truth (port leasing under a lock, .env migration, naming, build + up), is idempotent, runs offline / in CI, and emits one JSON object on stdout. The first install writes a .env with CWAPP_PORT, CWAPP_NAME, and CWAPP_DISPLAY_NAME — all read by docker-compose.yml.

Start / stop (manual, single-project)

If you only run one project, bare Compose works from the workflow root:

docker compose up -d        # build + start (http://127.0.0.1:4319/)
docker compose down         # stop
docker compose logs -f      # follow logs

Then open http://127.0.0.1:<port>/ for the form (the Create button, a Dashboard link, and the project name in the header appear automatically when served this way) or /dashboard. <port> is 4319 by default, or whatever install.sh leased (install.sh ls lists it). The stack binds 127.0.0.1:<port>:4319 (never reachable off-host), mounts jobs/ read-write and interface/ + app.md read-only, and runs a /health healthcheck.

Without Docker (needs Node ≥ 18): WORKFLOW_ROOT="$PWD" node _tools/app/server.js from the workflow root.

The helper is not required for any workflow operation — it only removes manual file-shuffling. Verify it with node _tools/app/test/smoke.test.mjs, node _tools/app/test/parsers.test.mjs, and the installer with node _tools/app/test/install.test.mjs (offline).

Creating a job (run the orchestrator)

Since v0.6 (D-41) the orchestrator is the single main-flow prompt — it creates the job and runs the pipeline. Open a coding-agent session in either supported invocation mode and send the orchestrator prompt path: _processes/02_orchestrator/orchestrator.prompt.md from workflow-internal mode, or _code_workflow/_processes/02_orchestrator/orchestrator.prompt.md from host-root mode. Pasting the full file still works, but the prompt path alone is enough. There is no separate creation prompt anymore.

What the orchestrator picks up

What the creation/bootstrap step does (for a 0_new intake)

1. Reads the source file end-to-end.
2. Infers (or reads) the request type from the closed vocabulary.
3. Loads the matching preset from _processes/_shared/presets/<type>.md and seeds defaults (including the after_creation gate).
4. Generates the slug YY-MM-DD-kebab-title — or YY-MM-DD-NNN-kebab-title when the source intake filename starts with a three-digit sequence prefix (010-base.md → 26-07-24-010-base, D-3 as extended by D-76), so an ordered set of intakes keeps its order in the queues (collisions get -2, -3, …).
5. If Git → Create branch: yes, verifies the worktree is clean and the target branch does not already exist, then creates the branch <type>/<slug> from main. Worktree-dirty or branch-exists is an early refusal — nothing is written, the intake stays in jobs/0_new/ for a re-run.
6. Writes jobs/1_creation/<slug>/JOB.md (version 0.14) + PROGRESS.md, then seeds root continuity files note.md + key-findings.md.
7. Moves the source intake into jobs/1_creation/<slug>/00_intake/<source filename> as the last filesystem action (D-28; subfolder renamed from 00_init/ by D-36). The intake travels with the job; 0_new/ is left clean.

Reviewing the generated job (only when after_creation: yes)

1. Open jobs/1_creation/<slug>/JOB.md. Read it end-to-end.
2. Confirm or correct the inferred request type, the Git options, the stage list, the gate values, the per-stage config.
3. Resolve every open question the orchestrator surfaced in its chat report. Edit JOB.md directly — you own the mandate.
4. Read jobs/1_creation/<slug>/PROGRESS.md. Check there are no unresolved blockers.
5. Re-run the orchestrator on the slug — it advances the job onward through the pipeline.

For non-standard / recovery queue moves, the promote operation agent (_processes/_operations/promote/promote.prompt.md) and a manual mv jobs/1_creation/<slug> jobs/2_ready/<slug> (plain mv, not git mv — job folders are gitignored) remain available, but they are no longer part of the normal new-job path.

Running the orchestrator

Open a coding-agent session in either supported invocation mode and send the orchestrator prompt path: _processes/02_orchestrator/orchestrator.prompt.md from workflow-internal mode, or _code_workflow/_processes/02_orchestrator/orchestrator.prompt.md from host-root mode.

Picking the slug

What the orchestrator does on every run

1. Outside workflow-modification mode, verifies app.md exists and is not the bootstrap placeholder, then reads config.json for runtime availability. Jobs launched from inside _code_workflow/ itself use the D-37 self-hosting bypass for workflow-maintenance work.
2. Moves the job to 3_ongoing/<slug>/ and writes a .lock marker (D-20).
3. Reads JOB.md and PROGRESS.md.
4. Cross-checks the three sources of truth (D-19). Stops on hard disagreements.
5. Iterates the closed stage order, skipping disabled and already-[x] stages.
6. For each pending stage: lazily creates the stage's subfolder, dispatches the matching stage prompt (_processes/02_orchestrator/stages/<NN>_<name>.prompt.md, or the brainstorm/review helper prompts) as a sub-agent (D-56), verifies the expected artifact(s) exist, parses the stage's STAGE_HANDOFF, marks PROGRESS.md → Stages [x]. A multi-phase execute is re-dispatched per phase back-to-back within the run (D-42).
7. Honours every approval gate set to yes — stops, removes .lock, reports.
8. When every enabled stage is [x], runs the git-landing step (_processes/_shared/git-landing.md, D-63) when the job's ## Git asks — one commit on the job branch (<type>/<slug>: <job title>), and on PR: yes a PR to the resolved PR target branch (blank ⇒ production), gated by before_commit / before_pr, with a remote-aware fallback on non-GitHub remotes or without gh — then moves the folder to 4_done/, removes .lock.

Handling approval gates

Approval gates are yes/no switches in JOB.md → Approval gates. Closed vocabulary:

When the orchestrator stops at a gate

1. Updates PROGRESS.md → Current state → Next action with the gate name and the artifact you should review.
2. Removes .lock.
3. Reports in chat: gate name, artifact path, the exact command to re-trigger.

To re-trigger after a gate stop: send the orchestrator prompt path again with the explicit slug (the job is in 3_ongoing/, not 2_ready/). The orchestrator detects no .lock, reads PROGRESS.md, sees which stages are [x], and continues from where it stopped.

Resuming or extending a job

A job in 4_done/ is re-openable (E-2). There are two distinct patterns for taking finished brainstorm work forward; pick by the rule below.

Pattern X — extend in place

Use when: the brainstorm and the implementation are the same intellectual project. This is the common "I just brainstormed it, now I want to ship it" case.

Send the extend prompt to a fresh coding agent session (D-31) — paste _processes/_operations/extend/extend.prompt.md in workflow-internal mode or _code_workflow/_processes/_operations/extend/extend.prompt.md in host-root mode, per Two invocation modes. The extend operation agent resolves which slug to extend, asks which stages to add, then does the JOB.md surgery and the folder move in one session:

• Brings ## Stages to current schema (lists all 8 canonical stages with [x] — date for stages PROGRESS.md shows complete, [ ] for newly enabled, (disabled) for the rest).
• Appends per-stage config blocks for the newly-enabled stages (feature-preset defaults).
• Appends Expected artifacts lines for the newly-enabled stages.
• Updates the **Status:** line.
• Moves the folder from 4_done/ (or 3_ongoing/) to 2_ready/ with plain mv (see _processes/_shared/job-folder-moves.md).

Default added stages are plan,execute,test,document,validate. The agent confirms or accepts overrides (e.g. just plan,execute).

The agent ends with a hint to send _processes/02_orchestrator/orchestrator.prompt.md to another fresh session. The orchestrator reads PROGRESS.md, sees the already-[x] stages, and starts at the next pending one. No manual PROGRESS.md edit is needed (D-8).

What extend does not touch: Type, Preset, the Mandate body, Git, and existing per-stage config blocks. It preserves existing Approval gates except explicit extend-agent gate updates the user confirms, such as before_commit / before_pr.

Pattern Y — spawn a child job

Use when: the brainstorm was a one-off thinking exercise, and the implementation is a separate project that references the prior brainstorm as input. The parent stays in 4_done/ untouched.

1. Write a new intake file in jobs/0_new/<file>.md referencing the parent's brainstorm:

   # Implement design from <parent-slug>
   
   Type: feature
   
   ## Mandate
   Implement the design produced in `jobs/4_done/<parent-slug>/02_brainstorm/consolidated.md`.
   Read its §3 (Locked design) before planning — that is the spec.

2. Run the orchestrator on the new intake — its creation/bootstrap step produces a new JOB.md with a fresh slug, feature-preset defaults, and your mandate, then drives the pipeline.
3. Run the orchestrator as normal.

Rule of thumb

If your fingers reach for "the brainstorm was the first phase of this work" → Pattern X. If they reach for "the brainstorm is a reference for new work" → Pattern Y. When in doubt, X — it's cheaper to extend than to start fresh.

When things go wrong

Stale .lock after a crash

If a previous orchestrator run crashed, .lock will be present in 3_ongoing/<slug>/ even though no run is in flight. The orchestrator never auto-removes a .lock it did not write (C-3 AC4 / R-9). Manual recovery:

rm jobs/3_ongoing/<slug>/.lock

Then re-run the orchestrator. If uncertain whether another session is running, check before deleting.

Status conflict (D-19)

If queue location, PROGRESS.md, and JOB.md disagree in a way the orchestrator cannot reconcile, it stops and records the disagreement in PROGRESS.md → Blockers. Queue is operational truth. Update PROGRESS.md or JOB.md (or move the folder back) to match, then re-run.

Missing or malformed app.md

Every prompt except init verifies app.md exists and is not the bootstrap placeholder when running against a host application. Workflow-maintenance jobs launched from inside _code_workflow/ itself use the D-37 auto-loaded-scope bypass described in CLAUDE.md / AGENTS.md. Primary fix: send _processes/00_app/app-init.prompt.md to a fresh Claude Code session at _code_workflow/. Fallback for non-Claude runtimes: follow the manual port flow in _docs/how-to-port.md, then re-run.

Unknown workflow contract version

The orchestrator and operation agents refuse to run a JOB.md whose Workflow version is not the current contract version (currently 0.14). To migrate an older JOB.md:

Migrating from 0.13 to 0.14 (current target)

The 0.14 bump is D-63: the ## Git contract becomes real end-to-end. The ## Git block gains a fifth line — - PR target branch: <branch name, or blank> — naming the branch the PR merges INTO (blank or absent reads as production; distinct from Base branch, the branch the job branch is cut FROM, default main, and from the header's Target branch, the job branch itself). Commit: yes and PR: yes are now honoured by the shared git landing (_processes/_shared/git-landing.md): pipeline jobs commit (and open the PR) in the orchestrator's §I Completion after the final validate PASS, gated by before_commit / before_pr, with a remote-aware fallback on non-GitHub remotes or without gh; action-layer jobs run the same procedure inline. The workflow never merges a PR. New validity rule: PR: yes requires Commit: yes (the creation/bootstrap step refuses an intake violating it). Later, within 0.15, D-82 grew the block to six lines — adding - Push: yes|no as its fourth line, directly after Commit — making the push a standalone landing step that runs on every remote host instead of only as a sub-step of the GitHub PR path, with PR: yes additionally requiring Push: yes, and off-GitHub PRs surfaced as credential-free PR-creation links from a host table. An absent Push: line resolves by PR (PR: yes ⇒ yes), so pre-D-82 jobs land unchanged and no version bump was required. This is a contract-only, additive migration for all jobs:

• Bump the **Workflow version:** line in JOB.md to 0.14.
• An existing 0.13 job needs only the version-line bump — an absent PR target branch line reads as blank ⇒ production, and the field only matters when PR: yes. If the job carries PR: yes with Commit: no, also fix the ## Git block (set Commit: yes, or PR: no) — the combination is now refused/blocked.
• Behavioural note: a job with Commit: yes now actually commits at landing (and PR: yes opens a PR to the resolved target). To keep the old leave-it-in-the-worktree behaviour, set Commit: no.
• Old 4_done/ jobs at 0.13 stay readable as historical records (per D-18) — do not rewrite them.

Migrating from 0.12 to 0.13

The 0.13 bump is D-61/D-62: the audit request type is reshaped from a read-only action-layer singlet into its own action-layer orchestrator (_processes/03_action/audit/audit.prompt.md, the old path retained as a tombstone), gaining an internal per-kind 3-phase matrix (current-code → global-app → best-practice/web, each Kind declaring which phases it runs), the new revalidate audit Kind (a whole-app/scoped soundness sweep across all concern-types), and an audit-scoped UpdateMode: report | report_fix (default report; report_fix is drop-and-tell — after writing its reports the audit emits one contract-valid Type: feature intake into jobs/0_new/ referencing the audit reports, then stops). Adding a new Kind enum value is a closed-vocabulary change, which is what bumps the contract. This is a contract-only, additive migration for non-audit jobs:

• Bump the **Workflow version:** line in JOB.md to 0.13.
• An existing non-audit 0.12 job needs only the version-line bump — the new revalidate Kind, the audit-orchestrator shape, and the audit UpdateMode are all opt-in. doc_upkeep's own UpdateMode (apply/report_only) is unchanged and disjoint from audit's.
• A live audit job is restructured to the action-layer orchestrator shape: still header + ## Git + ## Action + optional mandate (no ## Stages), but the audit now resolves a per-kind phase matrix and writes per-phase reports under 09_action/phases/ plus the roll-up 09_action/action-report.md. Optionally add - UpdateMode: report (or report_fix) to its ## Action block (absent reads as report); the Kind value revalidate becomes available.
• Old 4_done/ jobs at 0.12 stay readable as historical records (per D-18) — do not rewrite them.

Migrating from 0.11 to 0.12

The 0.12 bump is D-59: review moves to run immediately before validate (new canonical order clarify → brainstorm → plan → execute → test → document → review → validate; validate is the final certification gate). The per-job artifact folders are renumbered to match the new order — review writes 07_review/review-findings.md and validate writes 08_validate/validate-report.md. The review stage gains a bounded code auto-fix carve-out (modeled on validate's), and the orchestrator gains a loop-back engine (a blocked review or failed validate can re-run earlier enabled stages up to a per-job cap, default 3; D-83 later added a second, fail-closed light-fix route for small review blockers — it changes nothing about this migration). Existing finished jobs stay as-is; an active 0.11 job is only migrated if you intend to:

• Bump the **Workflow version:** line in JOB.md to 0.12.
• Reorder the ## Stages list in JOB.md (and the matching PROGRESS.md stage checklist) so review precedes validate, preserving each stage's current [x]/[ ] state.
• Update ## Expected artifacts to the new paths: 07_review/review-findings.md (review) and 08_validate/validate-report.md (validate).
• If the live job already has on-disk 07_validate/ and/or 08_review/ folders, rename/copy them to 08_validate/ and 07_review/ respectively — only for that live job.
• Optionally add a ### Loop-back → Max iterations: 3 block under ## Per-stage config (absent is read as the default cap).
• Old 4_done/ jobs at 0.11 (and earlier) stay readable as historical records (per D-18) — do not rewrite them.

Migrating from 0.10 to 0.11

The 0.11 bump is D-56: the main-flow orchestrator is re-architected from the inline-milestone model (D-40) into a pure-conductor dispatch model — it now dispatches every enabled stage to a standalone prompt under _processes/02_orchestrator/stages/ and writes only the shared job-root state. The handoff schema HELPER_HANDOFF.md is renamed back to STAGE_HANDOFF.md (widened Stage vocabulary + one optional clarify-only field). This migration is a NO-OP:

• Bump the **Workflow version:** line in JOB.md to 0.11.
• Nothing else changes — stage names, gate names, brainstorm modes, verdicts, per-stage config shape, and every per-job artifact path are byte-identical. Only the orchestrator's runtime model (inline → dispatch) changed.
• Old 4_done/ jobs at 0.10 stay readable (per D-18).

Migrating from 0.9 to 0.10

The 0.10 bump is D-48: two new documentation action-layer request types — doc_upkeep (validate + update an existing HTML docs folder against the code and the project's documentation UI kit; mandatory target folder) and doc_create (generate a section or full-app HTML docs). Both are shape: orchestrator under _processes/03_action/. (The documentation-UI-kit reference was later moved out of app.md into the committed pointer _processes/03_action/_shared/documentation-webkit.json by D-55.) This migration is additive:

• Bump the **Workflow version:** line in JOB.md to 0.10.
• No other per-job change — the existing types/stages/gates/action shapes are unchanged; the two new types are opt-in.
• Old 4_done/ jobs at 0.9 stay readable (per D-18).

Migrating from 0.8 to 0.9

The 0.9 bump is D-45: action becomes its own layer, not a stage. It is removed from the stage vocabulary (nine → eight); the request type carries a layer/shape in the new registry _processes/_shared/request-types.md; audit becomes a singlet and quick_fix its own parallel-fixer orchestrator under _processes/03_action/; 08_action.milestone.md is retired. First NON-additive migration:

• Bump the **Workflow version:** line in JOB.md to 0.9.
• Pipeline jobs (feature/bug/brainstorm): remove the - [ ] action (disabled) line from ## Stages.
• Action jobs (audit/quick_fix): restructure to the action-layer shape — drop ## Stages/## Approval gates/## Per-stage config; for audit promote ### Action to a top-level ## Action; for quick_fix keep ## Git + the mandate.
• Old 4_done/ jobs at 0.8 stay readable (per D-18).

Migrating from 0.7 to 0.8

The 0.8 bump (D-44) added the action stage. Bump the version line and add - [ ] action (disabled) to ## Stages — then apply the 0.8 → 0.9 step above (which removes it again for pipeline jobs; if migrating straight to 0.9, skip the add). Old 4_done/ jobs at 0.7 stay readable (per D-18).

Migrating from 0.5 to 0.6

The 0.6 bump is D-41: the standalone creation agent is folded into the orchestrator, and a new opt-in after_creation approval gate is added (default no). Additive:

• Bump the **Workflow version:** line in JOB.md to 0.6.
• Add - after_creation: no as the first line of ## Approval gates. Optional — an absent line is read as no.
• No other per-job change. Old 4_done/ jobs at 0.5 stay readable as historical records (per D-18).

Migrating from 0.4 to 0.5

The 0.5 bump bundles D-38 (validate gains a pickable runtime via ### Validate → Agent: claude | codex, default claude, plus an internal code review with a bounded auto-fix carve-out) and D-40 (the main pipeline runs as orchestrator-internal milestones). Mechanical and additive:

• Bump the version line to 0.5 (then to 0.6).
• If the job has validate enabled, add - Agent: claude to the ### Validate block (or rely on the reader-shim).
• The D-40 half needs no per-job migration — stage names, gate names, config shape, and artifact paths are unchanged.

Migrating from 0.3 to 0.4

The 0.4 bump is the D-35 folder-rename: job stage subfolders carry a numeric NN_ prefix matching execution order. Mechanical:

• Bump the version line to 0.4.
• Rename in-flight stage subfolders: init → 00_init, clarify → 01_clarify, brainstorm → 02_brainstorm, plan → 03_plan, execution → 04_execution, test → 05_test, document → 06_document, validate → 07_validate, review → 08_review.
• Update path references in JOB.md → ## Expected artifacts and PROGRESS.md → Handoff notes. Stage names, gate names, and prose stay un-prefixed.

Migrating from earlier versions

Apply migrations in order: 0.1 → 0.2 → 0.3 → 0.4 → 0.5 → 0.6 → 0.7 → 0.8 → 0.9 → 0.10 → 0.11 → 0.12 → 0.13 → 0.14. The 0.13 → 0.14 step (D-63) adds the PR target branch line + the shared post-validate git landing — contract-only/additive (bump the version line; an absent field reads as blank ⇒ production); see above. The 0.12 → 0.13 step (D-61/D-62) is the audit singlet → orchestrator reshape + the new revalidate Kind + the audit UpdateMode — contract-only/additive for non-audit jobs; see above. The 0.11 → 0.12 step (D-59) is the review-before-validate reorder + artifact renumber + loop-back engine — see above. The 0.10 → 0.11 step (D-56) is a NO-OP (bump the version line only). The 0.9 → 0.10 step (D-48) is additive (bump the version line; the two new doc types are opt-in). The 0.8 → 0.9 step (D-45) is the first non-additive one — see above. For 0.6 → 0.7: bump the version line; the orchestrator lazily creates note.md + key-findings.md on pickup (no manual file creation). For 0.2 → 0.3: bump the version line; if the job uses ### Brainstorm → Mode: dual_consolidate, add - Consolidator: claude. For 0.1 → 0.2: add - [ ] clarify as the first ## Stages line and - after_clarify: <yes|no> to ## Approval gates; do not add a ### Clarify config block; bump the version line.

Reading the artifacts

A jobs/<queue>/<slug>/ folder, fully populated, looks like: