The workflow is a small set of moving parts: three user-invoked role groups, five lifecycle queues plus a closed cancelled queue, eight pipeline stages with action as its own separate layer (D-45), root continuity/state files plus queue location as operational truth, and one portability bridge. Everything else is convention or shortcut.
Standalone agent roles
The workflow ships three user-invoked role groups. The orchestrator drives the per-job pipeline, including the creation/bootstrap step folded in by D-41; app-context and operation agents run outside it. Helper agents the orchestrator dispatches mid-pipeline (brainstorm writers, consolidate, review, and validate when configured for Codex) are not standalone — they are never user-invoked.
A raw intake in jobs/0_new/, or a slug in 1_creation/ / 2_ready/ / unlocked 3_ongoing/; that job's JOB.md + PROGRESS.md; matching preset, app.md
For a 0_new intake, runs its creation/bootstrap step (_processes/02_orchestrator/creation-bootstrap.md, D-41): writes jobs/1_creation/<slug>/JOB.md + PROGRESS.md, seeds note.md + key-findings.md, archives the source intake under 00_intake/<source filename> (D-28), and optionally creates a Git branch. Then, honouring the opt-in after_creation gate (default no), advances 1_creation → 2_ready → 3_ongoing, updates PROGRESS.md, dispatches each enabled stage as a sub-agent (D-56), runs the post-validate git landing when the job's ## Git asks (_processes/_shared/git-landing.md, D-63 — commit + push (D-82) + PR to the resolved PR target branch, gated by before_commit / before_pr; never merges), lands the job in 4_done/.
Why gate creation from orchestration? — The boundary 1_creation → 2_ready is the moment the user can read the mandate and approve it. Since D-41 the orchestrator owns both creation and orchestration, but the boundary survives as the opt-in after_creation gate: default no advances automatically, yes pauses in 1_creation/ for review. This is decision D-41, revising D-6.
Outside the per-job pipeline
Agent
Trigger
Purpose
Locked in
App-init _processes/00_app/app-init.prompt.md
User pastes on a fresh install
Bootstraps the workflow on a host project: inspects ../, asks targeted questions, empirically probes sub-agent runtimes, reads its template at _processes/00_app/app.template.md, validates against _processes/00_app/APP_CONTRACT.md, and writes a contract-valid app.md (host facts) and _code_workflow/config.json (workflow runtime params; gitignored). The only agent permitted to run before app.md exists in correct form.
Lifecycle / management ops on existing jobs. extend adds stages to a finished or in-flight job; promote moves a job folder between Kanban queues. Both edit JOB.md within a documented scope. Replaced the bash scripts under _tools/.
Safe-gate invariant (D-33, D-36) — Init is the workflow's safe gate: it must run before any other agent on a fresh install, and the absence of app.md is its trigger. Once init produces a valid app.md and _code_workflow/config.json, every other agent's startup guard becomes a two-line check (app.md exists and is not the bootstrap placeholder). The orchestrator additionally reads _code_workflow/config.json → runtimes at pickup (including its creation/bootstrap step) to refuse jobs whose required sub-agent runtimes are unavailable.
Kanban queues
The job's folder location is its operational state. There is no database, no metadata file holding "current queue" — moving the folder is the state change.
Automatic when the orchestrator picks up a 0_new intake. The source intake is moved into <slug>/00_intake/<source filename> on success (D-28; renamed from 00_init/ by D-36).
1_creation → 2_ready
Orchestrator (via the after_creation gate)
D-41 (revises D-6). Default after_creation: no → automatic; yes → orchestrator pauses for the user to read JOB.md, then advances on re-run. The promote operation agent remains for manual / recovery moves (D-31).
2_ready → 3_ongoing
Orchestrator
Automatic on pickup. Drops a .lock file.
3_ongoing → 4_done
Orchestrator
When every enabled stage is [x] and the git landing (D-63) is complete or skipped — a blocked landing blocks the move.
4_done → 2_ready
User via extend / promote operation agent, or manual recovery move
For follow-up runs that re-open the same job (D-8 / D-31).
Eight stages
Since 0.11 (D-56, superseding D-40) the orchestrator is a pure conductor — for each enabled stage it dispatches the matching prompt under _processes/02_orchestrator/stages/ as a sub-agent, verifies the artifact, parses its STAGE_HANDOFF, and writes only the shared job-root state; it never writes source, tests, docs, or any stage report itself. The order is fixed; which stages run is declared in JOB.md → Stages. brainstorm and review are sequencing stages whose helper sub-agents (under _processes/04_brainstorm/ and _processes/10_review/) are dispatched too.
#
Stage
Output
Default for
01
clarify
01_clarify/clarify-report.md + proposed Mandate-body rewrite for the orchestrator to apply
feature, bug, brainstorm, app_plan (off for doc_revalidate — its mandate is recipe-defined)
02
brainstorm
Dual mode: claude.md, codex.md, consolidated.md; solo mode: one per-agent file
feature, brainstorm, app_plan
03
plan
03_plan/PLAN.md
feature, bug, doc_revalidate, app_plan
04
execute
Source code + 04_execution/notes.md
feature, bug, doc_revalidate, app_plan
05
test
Test files + 05_test/notes.md
feature, bug
06
document
Doc updates + 06_document/notes.md
feature
07
review
07_review/review-findings.md
Off by default — opt-in
08
validate
08_validate/validate-report.md
feature, bug, doc_revalidate, app_plan
action is not a stage — D-45 made it its own layer. Action-layer jobs (audit, quick_fix, doc_upkeep, doc_create, codereview_fix) route outside the stage loop via _processes/_shared/request-types.md and write 09_action/action-report.md. See Stages for the layer model.
Approval gates
Gates can stop the orchestrator and wait for the user. Each is independently yes / no in JOB.md → Approval gates.
Gate
Fires
Used for
after_creation(D-41, default no)
After the creation/bootstrap step writes JOB.md into 1_creation/
Optionally review the generated job before the pipeline runs; default off.
after_clarify
Right after clarify finishes
Approve the cleaned mandate before brainstorm spends compute.
after_brainstorm
After the consolidate sub-agent
Lock approach + answer open questions before plan.
before_plan
Right before plan starts
Rare — opt-in checkpoint between brainstorm and plan.
before_execution
Right before execute starts
Rare — last chance to abort before code is written.
before_commit
Right before staging, at the post-validate git landing (D-63)
Common — review the diff before it goes into Git.
before_pr
Right before gh pr create, same landing
Common — review the PR description before it's public.
Files on disk
The folder layout
_code_workflow/
├── CLAUDE.md # agent entry shim (Claude Code)
├── AGENTS.md # agent entry shim (Codex / Aider / Cursor / generic)
├── README.md # human-glance landing
├── app.md # host-facts only — the project-specific bridge (D-21, D-36)
├── config.json # workflow runtime params (gitignored; written by init, D-36)
├── config.example.json # checked-in schema example for config.json (D-36)
├── _docs/ # documentation ABOUT the workflow
├── _processes/ # the workflow's executable definition
│ ├── 00_app/ # app-init + app-update prompts, app contract, app template
│ ├── 01_creation/ # retired tombstone (creation folded into the orchestrator, D-41)
│ ├── 02_orchestrator/ # pure-conductor runner + creation-bootstrap.md (D-41)
│ │ └── stages/ # dispatched stage prompts — the orchestrator dispatches each (D-56)
│ ├── 04_brainstorm/ # surviving brainstorm helper prompts (claude / codex / consolidate)
│ ├── 10_review/ # review helper prompt + the bounded light-fix helper (D-83)
│ ├── _operations/ # user-invoked operation agents — extend, promote (D-31)
│ └── _shared/ # presets, schemas, templates
├── interface/ # intake form + dashboard (served standalone, or by the local helper app)
├── _tools/ # app/ = optional local helper app (Docker-served form + dashboard + install.sh); build_replay_fixtures.sh
├── jobs/ # live working area, Kanban-by-folder
│ ├── 0_new/ 1_creation/ 2_ready/ 3_ongoing/ 4_done/ 5_cancelled/
└── tmp/ # scratch space, gitignored
Per-job folder layout
Stage subfolders are created lazily — only when the matching stage actually runs (D-9). A brand-new job in 2_ready/ has four root continuity/state files plus the eager 00_intake/ folder (the orchestrator creation/bootstrap step's own artifact — D-28 / D-41; renamed from 00_init/ by D-36).
jobs/3_ongoing/26-05-12-some-slug/
├── JOB.md # required: scoping contract + mandate
├── PROGRESS.md # required: live workflow state
├── note.md # required: downstream operational notes
├── key-findings.md # required: durable findings with provenance
├── .lock # present only while orchestrator is mid-run
├── 00_intake/ # eager — original intake, moved here by creation (D-28, D-36)
│ └──
├── 01_clarify/clarify-report.md # lazy
├── 02_brainstorm/ # lazy — claude.md, codex.md, consolidated.md
├── 03_plan/PLAN.md
├── 04_execution/
│ ├── notes.md
│ └── phases/ # lazy — only multi-phase plans (phase-1.md, …)
├── 05_test/notes.md
├── 06_document/notes.md
├── 07_review/review-findings.md # lazy — only when review is enabled
└── 08_validate/validate-report.md
State and continuity
Every job has four root continuity/state files: JOB.md, PROGRESS.md, note.md, and key-findings.md. Queue location remains the operational truth. Together they separate intended configuration, actual progress, downstream notes, durable findings, and lifecycle position.
JOB.md · the mandate
Answers: what is this job, what stages run, what gates fire, what does success look like?
Lifecycle: written once by the orchestrator's creation/bootstrap step (D-41). The clarify stage may propose a free-form Mandate-body rewrite; the orchestrator applies it. The user owns everything else. Dispatched stages never write it.
Lifecycle: initialised by creation. Updated by the orchestrator only, after every stage boundary and every gate stop. Every dispatched stage returns a structured chat handoff the orchestrator verifies and translates into PROGRESS.md lines (D-56).
Answers: what should later agents reuse, avoid redoing, or keep in mind?
Lifecycle: seeded by creation/bootstrap. Updated by the orchestrator only from dispatched-stage Notes for downstream handoff fields.
Template: NOTE.template.md
key-findings.md · durable findings
Answers: what sourced discoveries materially affect later work?
Lifecycle: seeded by creation/bootstrap. Updated by the orchestrator only from dispatched-stage Key findings handoff fields.
Template: KEY_FINDINGS.template.md
Single-writer rule — If both the orchestrator and dispatched helpers wrote shared job-root state, the files would collect duplicate lines, conflicting checkboxes, stale Next action text, and contradictory carry-forward notes. Single ownership eliminates the entire class of bug.
Question relay (D-29) — Dispatched stages never invoke their runtime's question facility directly. When a stage needs a user decision mid-run, it returns Completion: awaiting_user_input with a Questions for user block; the orchestrator asks the user via AskUserQuestion, captures answers, and re-dispatches the same stage with a fenced user_answers block injected (D-56). Used by clarify on ambiguity, the brainstorm consolidate helper, and the Codex review/validate helper. The relay is never a user-visible stop — only approval gates are.
Portability — app.md + config
The workflow is project-agnostic. Everything project-specific lives in one file at the folder root: app.md. To port the workflow to a new project, copy _code_workflow/ and rewrite app.md, then configure gitignored config.json for the local agent runtimes.
Every prompt under _processes/** opens with the literal directive "Read app.md first." The schema app.md must satisfy is documented in APP_CONTRACT. Sub-agent-runtime declarations were moved out to _code_workflow/config.json per D-36. The orchestrator and operation agents verify app.md exists and is not the bootstrap placeholder, then read config.json for runtime availability.
No code change to port — The standalone agent prompts, every dispatched stage prompt, and every helper prompt are app-agnostic by contract. They read app.md for project facts; init is the one structural exception, because its job is to produceapp.md on a fresh install. A new project means: run init, get a fresh app.md, same prompts.