@smartmemory/compose 0.1.2-beta → 0.1.4-beta

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +47 -994
  2. package/bin/compose.js +4 -4
  3. package/lib/pipeline-cli.js +29 -28
  4. package/package.json +1 -1
  5. package/pipelines/new.stratum.yaml +182 -0
package/README.md CHANGED
@@ -1,1025 +1,78 @@
1
1
  # Compose
2
2
 
3
- AI-powered product lifecycle orchestrator. Compose takes a product idea from intent to shipped code through structured, agent-driven pipelines with human gates at every critical decision point.
3
+ Compose is a CLI that drives a product idea from intent to shipped code. It runs YAML-defined multi-step pipelines on top of [Stratum](https://github.com/smartmemory/stratum), dispatching each step to an AI agent (Claude or Codex), checking postconditions, and pausing at human gates between phases. Output: a feature folder with design, blueprint, plan, code, tests, review trail, and an updated `ROADMAP.md` — auditable end-to-end.
4
4
 
5
- Compose coordinates multiple AI agents (Claude, Codex) through YAML-defined workflows powered by [Stratum](https://github.com/smartmemory/stratum), enforcing postconditions, retrying on failure, and producing auditable execution traces.
6
-
7
- ## Table of Contents
8
-
9
- - [How It Works](#how-it-works)
10
- - [Installation and Setup](#installation-and-setup)
11
- - [CLI Commands](#cli-commands)
12
- - [Web UI — Cockpit Shell](#web-ui--cockpit-shell)
13
- - [The Kickoff Pipeline (new)](#the-kickoff-pipeline)
14
- - [The Build Pipeline (build)](#the-build-pipeline)
15
- - [Agent Connectors](#agent-connectors)
16
- - [Questionnaire System](#questionnaire-system)
17
- - [Gate System](#gate-system)
18
- - [Validation System](#validation-system)
19
- - [Pipeline CLI](#pipeline-cli)
20
- - [Recovery Logic](#recovery-logic)
21
- - [Progress Logging](#progress-logging)
22
- - [Result Normalization and JSON Extraction](#result-normalization-and-json-extraction)
23
- - [Vision Writer Integration](#vision-writer-integration)
24
- - [Configuration Files](#configuration-files)
25
- - [MCP Server](#mcp-server)
26
- - [Pipeline Specs](#pipeline-specs)
27
- - [Examples and Workflows](#examples-and-workflows)
28
-
29
- ---
5
+ ![Compose Cockpit Shell](Screenshot.png)
30
6
 
31
- ## How It Works
7
+ ## Pitch
32
8
 
33
- Compose is a CLI that orchestrates AI agents through multi-step workflows defined in `.stratum.yaml` pipeline specs. Each step dispatches a prompt to an agent (Claude or Codex), collects the result, validates postconditions, and advances to the next step. Human gates pause the pipeline for approve/revise/kill decisions. If postconditions fail, Compose runs a fix pass with a different agent and retries.
9
+ - **Gates everywhere** — every phase transition (design, plan, ship) is approve/revise/kill. Human or Codex review at any point.
10
+ - **Stratum-backed** — pipelines are declarative `.stratum.yaml` specs with typed contracts, `ensure` postconditions, and retry/`on_fail` routing. Specs are editable.
11
+ - **Multi-agent** — Claude (via the Anthropic Agent SDK) and Codex (via the OpenAI CLI) plug in through a uniform connector interface; reviews can run on a different model than implementation.
34
12
 
35
- ![Compose Cockpit Shell](Screenshot.png)
13
+ ## 30-second example
36
14
 
37
- ```
38
- compose new "REST API for todo lists"
15
+ ```bash
16
+ compose new "REST API for managing team todo lists"
39
17
  -> questionnaire (interactive)
40
- -> research (claude)
41
- -> brainstorm (claude)
42
- -> [human gate] approve/revise/kill
43
- -> roadmap (claude)
44
- -> [human gate]
45
- -> scaffold (claude)
18
+ -> research (claude) -> brainstorm (claude)
19
+ -> [gate] approve / revise / kill
20
+ -> roadmap (claude) -> [gate] -> scaffold (claude)
46
21
  -> done: feature folders + ROADMAP.md ready
47
22
 
48
- compose build FEAT-1
49
- -> explore & design (claude)
50
- -> [human gate]
51
- -> blueprint (claude)
52
- -> verification (claude)
53
- -> plan (claude)
54
- -> [human gate]
55
- -> decompose + parallel execute (claude, worktree isolation)
56
- -> parallel review (claude lenses: diff-quality, contract, security, framework)
57
- -> codex review (codex) + fix loop
58
- -> coverage sweep (claude) + fix loop
59
- -> docs update (claude)
60
- -> ship (claude)
61
- -> [human gate]
23
+ compose build TODO-1
24
+ -> design (claude) -> [gate]
25
+ -> blueprint (claude) -> verification (claude)
26
+ -> plan (claude) -> [gate]
27
+ -> decompose + parallel execute (worktree isolation)
28
+ -> claude review lenses + codex review + coverage sweep
29
+ -> docs + ship -> [gate]
62
30
  -> done: feature implemented, reviewed, tested, documented
63
31
  ```
64
32
 
65
- ---
66
-
67
- ## Installation and Setup
68
-
69
- ### Prerequisites
33
+ ## Quick install
70
34
 
71
- - Node.js 18+
72
- - `stratum-mcp` on PATH (`pip install stratum`)
73
- - For Codex steps: the official OpenAI `codex` CLI (`npm i -g @openai/codex` or `brew install codex`), authenticated via `codex login` (ChatGPT OAuth) or `OPENAI_API_KEY`. Optional: install the Claude Code plugin for interactive slash commands: `/plugin marketplace add openai/codex-plugin-cc` then `/plugin install codex@openai-codex`.
74
-
75
- ### Install Compose
35
+ Prerequisites: Node.js 18+ and `stratum-mcp` on PATH (`pip install stratum`). Codex steps additionally need the OpenAI `codex` CLI. Full prereqs in [docs/install.md](docs/install.md).
76
36
 
77
37
  ```bash
78
- git clone https://github.com/smartmemory/compose.git
79
- cd compose
80
- npm install
38
+ git clone https://github.com/smartmemory/compose.git && cd compose && npm install
39
+ npx compose setup # global skill + stratum-mcp registration
40
+ ln -s "$(pwd)/bin/compose.js" ~/bin/compose && chmod +x ~/bin/compose # optional: bare `compose` command
81
41
  ```
82
42
 
83
- ### Project-local setup (`compose init`)
84
-
85
- Run from inside your project directory:
43
+ Then in your project:
86
44
 
87
45
  ```bash
88
46
  cd /path/to/your/project
89
- npx compose init
90
- ```
91
-
92
- This:
93
- 1. Creates `.compose/` directory with `compose.json` config
94
- 2. Creates `.compose/data/` for vision state
95
- 3. Detects installed agents (Claude, Codex, Gemini)
96
- 4. Registers `compose-mcp` in `.mcp.json`
97
- 5. Scaffolds `ROADMAP.md` from template (if absent)
98
- 6. Copies default pipeline specs to `pipelines/`
99
- 7. Installs the Stratum skill to detected agents
100
-
101
- Flags:
102
- - `--no-stratum` -- disable Stratum integration
103
- - `--no-lifecycle` -- disable lifecycle tracking
104
-
105
- ### Global setup (`compose setup`)
106
-
107
- Installs the `/compose` skill globally and registers `stratum-mcp`:
108
-
109
- ```bash
110
- npx compose setup
111
- ```
112
-
113
- This:
114
- 1. Copies the `/compose` skill to `~/.claude/skills/compose/`
115
- 2. Installs the Stratum skill to all detected agents
116
- 3. Registers `stratum-mcp` with Claude Code (if available)
117
-
118
- ### Global CLI via ~/bin
119
-
120
- To use `compose` as a global command:
121
-
122
- ```bash
123
- ln -s /path/to/compose/bin/compose.js ~/bin/compose
124
- chmod +x ~/bin/compose
125
- ```
126
-
127
- ### Backwards compatibility
128
-
129
- `compose install` runs both `init` and `setup` in sequence.
130
-
131
- ---
132
-
133
- ## CLI Commands
134
-
135
- ### `compose new`
136
-
137
- Kickoff a new product. Runs the full kickoff pipeline: research, brainstorm, roadmap, and scaffold.
138
-
139
- ```bash
140
- compose new "Structured log analyzer CLI for JSON-lines files"
141
- compose new "REST API for managing team todo lists" --auto
142
- compose new "OAuth2 provider library" --ask
143
- ```
144
-
145
- **Arguments:**
146
- - First argument: product description (quoted string)
147
- - `--auto` -- skip the questionnaire entirely
148
- - `--ask` -- re-run the questionnaire (uses previous answers as defaults)
149
-
150
- Auto-initializes the project if `.compose/` doesn't exist. Reads existing context from `README.md`, `package.json`, `pyproject.toml`, `Cargo.toml`, and any prior `project-analysis.md` from `compose import`.
151
-
152
- ### `compose import`
153
-
154
- Scan an existing project and generate a structured analysis at `docs/discovery/project-analysis.md`.
155
-
156
- ```bash
157
- cd existing-project
158
- compose import
159
- ```
160
-
161
- Walks the file tree (max depth 4, ignoring `node_modules`, `.git`, etc.), reads key files (`README.md`, `package.json`, config files, top-level source files), and dispatches Claude to produce:
162
- - Project overview (what it does, language, maturity)
163
- - Architecture map
164
- - Feature inventory with suggested codes
165
- - Patterns and conventions
166
- - Gaps and opportunities
167
- - Suggested roadmap
168
-
169
- The generated analysis is automatically consumed by `compose new` and `compose build` as context.
170
-
171
- ### `compose feature`
172
-
173
- Add a single feature to the project with a folder structure, seed design doc, and ROADMAP entry.
174
-
175
- ```bash
176
- compose feature LOG-1 "CLI tool for parsing JSON-lines log files"
177
- compose feature AUTH-2 "Add OAuth2 login flow with PKCE"
178
- ```
179
-
180
- Creates:
181
- - `docs/features/<CODE>/design.md` -- seed design doc with status, date, intent
182
- - Appends a row to `ROADMAP.md` with the feature code and PLANNED status
183
- - Updates the project description in ROADMAP if still placeholder
184
-
185
- ### `compose build`
186
-
187
- Run a feature through the headless build lifecycle. This is the main execution command.
188
-
189
- ```bash
190
- compose build FEAT-1
191
- compose build --abort # abort the active build
192
- compose build FEAT-1 --abort # abort a specific feature's build
193
- ```
194
-
195
- Loads `pipelines/build.stratum.yaml`, starts a Stratum flow, and dispatches each step to the appropriate agent. Tracks active build state in `.compose/data/active-build.json` for resume/abort support. Only one build can be active at a time.
196
-
197
- ### `compose pipeline`
198
-
199
- View and edit the build pipeline spec (`pipelines/build.stratum.yaml`).
200
-
201
- ```bash
202
- compose pipeline show
203
- compose pipeline set <step> --agent codex
204
- compose pipeline set <step> --mode gate
205
- compose pipeline set <step> --mode review
206
- compose pipeline set <step> --retries 5
207
- compose pipeline add --id lint --after execute --agent claude --intent "Run linter"
208
- compose pipeline remove <step>
209
- compose pipeline enable <step> [step...]
210
- compose pipeline disable <step> [step...]
211
- ```
212
-
213
- See [Pipeline CLI](#pipeline-cli) for full details.
214
-
215
- ### `compose init`
216
-
217
- Project-local initialization. Creates `.compose/`, detects agents, registers MCP server, scaffolds ROADMAP and pipeline specs.
218
-
219
- ```bash
220
- compose init
221
- compose init --no-stratum
222
- compose init --no-lifecycle
223
- ```
224
-
225
- ### `compose setup`
226
-
227
- Global skill and MCP registration. Installs the `/compose` skill and Stratum skill to all detected agents. At the end, runs an external-dependency check (see `compose doctor`) and prints actionable install hints for any missing external skills or commands.
228
-
229
- ```bash
230
- compose setup
231
- ```
232
-
233
- ### `compose doctor`
234
-
235
- Verifies that the external skills and commands the lifecycle relies on (e.g. `superpowers:*`, `interface-design:*`, `codex:review`, `refactor`, `update-docs`) are installed locally. The authoritative dep list lives in `.compose-deps.json` at the package root.
236
-
237
- ```bash
238
- compose doctor # human-readable report
239
- compose doctor --json # machine-readable, full dep records (id, required_for, install, fallback, optional)
240
- compose doctor --strict # exit 1 on any missing required dep (use in CI)
241
- compose doctor --verbose # also list the filesystem paths scanned
242
- ```
243
-
244
- ### `compose start`
245
-
246
- Start the Compose app (supervisor with web UI, terminal, and API server).
247
-
248
- ```bash
249
- compose start
250
- COMPOSE_TARGET=/path/to/project compose start
251
- ```
252
-
253
- ---
254
-
255
- ## Web UI — Cockpit Shell
256
-
257
- `compose start` opens a browser-based cockpit at `http://localhost:3001`. The layout is organized around three zoom levels: Graph (macro), Tree (meso), and Detail (micro).
258
-
259
- ```
260
- ┌──────────────────────────────────────────────────────────────┐
261
- │ Header │ [Graph | Tree | Docs | Gates | Pipeline | Sessions] │
262
- ├─────────┬──────────────────────────┬─────────────────────────┤
263
- │ │ │ │
264
- │ Sidebar │ MAIN AREA │ CONTEXT PANEL │
265
- │ (~200px)│ (graph / tree / docs) │ (resizable, ~420px) │
266
- │ │ │ │
267
- ├─────────┴──────────────────────────┴─────────────────────────┤
268
- │ OPS STRIP (active builds · pending gates · errors) │
269
- ├──────────────────────────────────────────────────────────────┤
270
- │ AGENT BAR (collapsed | expanded | maximized) │
271
- ├──────────────────────────────────────────────────────────────┤
272
- │ GATE NOTIFICATION BAR (hidden when no pending gates) │
273
- └──────────────────────────────────────────────────────────────┘
274
- ```
275
-
276
- ### Zones
277
-
278
- | Zone | Component | Description |
279
- |------|-----------|-------------|
280
- | **Header** | `ViewTabs` | Tab switcher for Graph, Tree, Docs, Gates, Pipeline, Sessions. Font/theme controls. |
281
- | **Sidebar** | `AttentionQueueSidebar` | Build status, attention queue (blocked/gate items), search, group filters by feature code prefix. |
282
- | **Main Area** | driven by active tab | Graph (fcose layout with compound grouping), Tree (search + filters), Docs (file browser + preview), and ops views. |
283
- | **Context Panel** | `ContextPanel` | Resizable right panel with tabbed detail: Overview, Pipeline dots, Sessions, Errors, Files. Project summary when nothing selected. |
284
- | **Ops Strip** | `OpsStrip` | Persistent 36px bar with scrollable pills for active builds, pending gates (inline approve), and recent errors. Hidden in Docs view. |
285
- | **Agent Bar** | `AgentBar` | Always-present bottom panel for the agent stream. Collapsed/expanded/maximized. |
286
- | **Gate Notification** | `GateNotificationBar` | Carousel of pending gates with Approve/Revise/Kill. |
287
-
288
- ### Graph View
289
-
290
- Uses `cytoscape-fcose` (force-directed with compound node support):
291
-
292
- - **Compound grouping** by feature code prefix (COMP-UX, STRAT-ENG, etc.). Groups sorted by active item count.
293
- - **Status filters**: All, Active (default), Done, Blocked.
294
- - **Group filters** in sidebar — click to hide/show per feature group.
295
- - **Build state overlays**: building (blue pulse), gate-pending (amber), blocked-downstream (dimmed 35%), error (red).
296
- - **Badge overlays**: gate badge with approve/revise/kill popover, error badge, agent badge.
297
- - **Selection**: click to highlight dependency chain. Cross-view navigation via context panel links.
298
-
299
- ### Context Panel
300
-
301
- Tabbed detail surface (5 tabs: Overview, Pipeline, Sessions, Errors, Files). Resizable via drag handle (min 280px, max 60% viewport), persisted in `localStorage`. Shows project summary when nothing selected.
302
-
303
- ### Ops Strip
304
-
305
- Persistent 36px bar with three entry types (blue build pills, amber gate pills with inline approve, red error pills). Completed builds flash green 2s. Hidden in Docs view.
306
-
307
- ### Sidebar
308
-
309
- Build status, attention queue (blocked + pending gates), search, and group filters (feature code prefix groups sorted by active count, click to toggle).
310
-
311
- ### Agent Bar
312
-
313
- Three states: collapsed (~36px status line), expanded (message stream + chat), maximized (fills main area). Sending a message with a feature code auto-selects that feature.
314
-
315
- ### Cross-View Navigation
316
-
317
- Selection persists across view switches. Graph pans to selected node, Tree scrolls to selected row. "View in Graph" / "View in Tree" links in context panel. File click opens DocsView with back button.
318
-
319
- ### State Persistence
320
-
321
- | `localStorage` key | Default |
322
- |--------------------|---------|
323
- | `compose:activeView` | `'graph'` |
324
- | `compose:agentBarState` | `'collapsed'` |
325
- | `compose:contextPanel` | `'open'` |
326
- | `compose:contextWidthPx` | `420` |
327
- | `compose:fontSize` | `13` |
328
- | `compose:theme` | system |
329
-
330
- ### Error Boundaries
331
-
332
- `SafeModeBoundary` wraps the full shell. Each zone has a `PanelErrorBoundary` — a crash in one zone does not take down the rest.
333
-
334
- ---
335
-
336
- ## The Kickoff Pipeline
337
-
338
- Defined in `pipelines/new.stratum.yaml`. Orchestrates product creation from intent to scaffolded feature folders.
339
-
340
- ### Steps
341
-
342
- | # | Step | Agent | What It Does |
343
- |---|------|-------|-------------|
344
- | 1 | `research` | claude | Searches for prior art, existing tools, architectural patterns, risks. Writes to `docs/discovery/research.md`. Validated against criteria (>= 2 prior art entries, patterns, risks). |
345
- | 2 | `brainstorm` | claude | Generates feature list with codes, user stories, 2-3 architecture options with trade-offs. Writes to `docs/discovery/brainstorm.md`. Validated (>= 3 features, user stories, architecture options). |
346
- | 3 | `review_gate` | human | Gate: approve brainstorm, revise (loop back to brainstorm), or kill. Displays the brainstorm artifact for review. Timeout: 2 hours. |
347
- | 4 | `roadmap` | claude | Structures brainstorm into phased ROADMAP.md with feature table. Validated (markdown table, phased features, PLANNED status). |
348
- | 5 | `roadmap_gate` | human | Gate: approve roadmap, revise, or kill. Timeout: 1 hour. |
349
- | 6 | `scaffold` | claude | Creates `docs/features/<CODE>/design.md` for each ROADMAP feature with seed content. |
350
-
351
- ### Contracts
352
-
353
- - `ResearchResult`: `{ priorArt, patterns, risks, summary }`
354
- - `BrainstormResult`: `{ features, userStories, archOptions, summary }`
355
- - `RoadmapResult`: `{ phases, features, summary, artifact }`
356
- - `ScaffoldResult`: `{ created, summary }`
357
-
358
- ### Skipping Research
359
-
360
- The questionnaire can disable research. When skipped, the `research` step gets `skip_if: "true"` injected into the spec before planning.
361
-
362
- ---
363
-
364
- ## The Build Pipeline
365
-
366
- Defined in `pipelines/build.stratum.yaml`. Executes a feature through the full development lifecycle.
367
-
368
- ### Steps
369
-
370
- | # | Step | Agent | What It Does |
371
- |---|------|-------|-------------|
372
- | 1 | `explore_design` | claude | Explores codebase, writes design doc to `docs/features/{code}/design.md` |
373
- | 2 | `scope` | claude | Scope the feature, identify boundaries |
374
- | 3 | `design_gate` | human | Approve design, revise (loop to explore_design), or kill |
375
- | 4 | `prd` | claude | Write PRD. **Skipped by default** -- enable via `compose pipeline enable prd` |
376
- | 5 | `architecture` | claude | Architecture doc with competing proposals. **Skipped by default** |
377
- | 6 | `blueprint` | claude | Implementation blueprint with file:line references. Retries: 3 |
378
- | 7 | `verification` | claude | Verify all blueprint references against actual code. `on_fail: blueprint` loops back if stale |
379
- | 8 | `plan_gate` | human | Approve plan, revise (loop to plan), or kill |
380
- | 9 | `decompose` | claude | Decompose plan into independent subtasks with `files_owned`/`files_read` |
381
- | 10 | `execute` | claude | Parallel dispatch: TDD implementation in isolated git worktrees per subtask |
382
- | 11 | `review` | claude (sub-flow) | Parallel multi-lens review: triage → 2-4 specialized lenses → merge/dedup. Retries: 5 |
383
- | 12 | `codex_review` | codex (sub-flow) | Independent cross-model review after Claude lenses + fixes. Retries: 3 |
384
- | 13 | `coverage` | claude (sub-flow) | Run tests, fix failures, re-run. Retries: 15 |
385
- | 14 | `report` | claude | Post-implementation report. **Skipped by default** |
386
- | 15 | `docs` | claude | Update CHANGELOG, ROADMAP, README, CLAUDE.md, and public docs |
387
- | 16 | `ship` | claude | Run tests, run build, verify docs, stage, commit, push |
388
- | 17 | `ship_gate` | human | Final approval |
389
-
390
- ### Sub-flows
391
-
392
- **`parallel_review`** (STRAT-REV): Multi-lens review with three steps:
393
- 1. **triage** (claude) — reads file list, activates relevant lenses (always: diff-quality + contract-compliance; conditional: security, framework). On retry, reads `.compose/prior_dirty_lenses.json` for selective re-review.
394
- 2. **review_lenses** (parallel_dispatch, isolation: none) — fans out 2-4 lens agents concurrently. Each lens returns `LensFinding[]` with severity, file, line, confidence. Confidence gates and false-positive exclusion lists reduce noise.
395
- 3. **merge** (claude) — deduplicates findings by file+issue, assigns severity (must-fix/should-fix/nit), classifies as auto-fix vs ask.
396
-
397
- **`review_check`** (fallback): Single-step codex review. Returns `{ clean, summary, findings }`. Retries until `clean == true` (max 5). Cross-agent fix: claude fixes, codex re-reviews. Used by `codex_review` step.
398
-
399
- **`coverage_check`**: Single-step test runner. Returns `{ passing, summary, failures }`. Retries until `passing == true` (max 15). Fix pass dispatched on failure.
400
-
401
- ### Contracts
402
-
403
- - `PhaseResult`: `{ phase, artifact, outcome, summary }` -- `outcome` is one of `complete`, `skipped`, `failed`
404
- - `ReviewResult`: `{ clean, summary, findings }`
405
- - `TestResult`: `{ passing, summary, failures }`
406
- - `LensFinding`: `{ lens, file, line, severity, finding, confidence }` -- per-finding from a review lens
407
- - `LensTask`: `{ id, lens_name, lens_focus, confidence_gate, exclusions }` -- triage output for lens dispatch
408
- - `LensResult`: `{ clean, findings[] }` -- single lens output
409
- - `TriageResult`: `{ tasks[] }` -- triage step output
410
- - `MergedReviewResult`: `{ clean, summary, findings[], lenses_run[], auto_fixes[], asks[] }` -- merged review output
411
- - `TaskGraph`: `{ tasks[] }` -- decompose output for parallel dispatch
412
-
413
- ### on_fail Routing
414
-
415
- The `verification` step has `on_fail: blueprint` -- when retries are exhausted without valid references, the pipeline routes back to the blueprint step for a rewrite.
416
-
417
- ---
418
-
419
- ## Agent Connectors
420
-
421
- Compose dispatches work to AI agents through a connector abstraction. All connectors implement the same async generator interface yielding typed message envelopes.
422
-
423
- ### Message Envelope
424
-
425
- ```js
426
- { type: 'system', subtype: 'init' | 'complete', agent: string, model?: string }
427
- { type: 'assistant', content: string }
428
- { type: 'tool_use', tool: string, input: object }
429
- { type: 'tool_use_summary', summary: string }
430
- { type: 'tool_progress', tool: string, elapsed: number }
431
- { type: 'result', content: string }
432
- { type: 'error', message: string }
433
- ```
434
-
435
- ### ClaudeSDKConnector
436
-
437
- Wraps `@anthropic-ai/claude-agent-sdk`'s `query()` function. Default model: `claude-sonnet-4-6` (override via `CLAUDE_MODEL` env var). Runs in `acceptEdits` permission mode with full `claude_code` tool access.
438
-
439
- Key behaviors:
440
- - Strips `CLAUDECODE` env var to allow spawning nested Claude Code sessions
441
- - Normalizes SDK messages (assistant content blocks, tool_use, deltas) into the shared envelope
442
- - Supports `interrupt()` to abort the active query
443
- - Schema injection via `injectSchema()` for structured output
444
-
445
- ### CodexConnector
446
-
447
- Spawns the official OpenAI `codex` CLI (`codex exec --json --skip-git-repo-check --sandbox read-only`), locked to OpenAI Codex models. Install via `npm i -g @openai/codex` (or `brew install codex`). Auth via `codex login` (ChatGPT OAuth) or `OPENAI_API_KEY` env var. Reasoning effort is passed via `-c model_reasoning_effort=<effort>` when the model ID carries a `/low|medium|high|xhigh` suffix.
448
-
449
- Supported models: `gpt-5.4`, `gpt-5.2-codex`, `gpt-5.1-codex-max`, `gpt-5.1-codex`, `gpt-5.1-codex-mini` (with `/low`, `/medium`, `/high`, `/xhigh` effort suffixes). Default: `gpt-5.4` (override via `CODEX_MODEL` env var).
450
-
451
- ### OpencodeConnector
452
-
453
- Model-agnostic base for any non-Anthropic agent running through the OpenCode SDK. Manages a singleton `opencode serve` subprocess (one per process, shared across instances). Creates sessions, sends prompts, and streams SSE events.
454
-
455
- ### AgentConnector (base class)
456
-
457
- Abstract base with `run()`, `interrupt()`, and `isRunning`. Subclasses must implement `run()` as an async generator. Also exports `injectSchema(prompt, schema)` which appends JSON Schema instructions to prompts.
458
-
459
- ### Agent Registry
460
-
461
- The build runner maps agent names to connector factories:
462
-
463
- ```
464
- claude -> ClaudeSDKConnector
465
- codex -> CodexConnector
466
- ```
467
-
468
- The connector factory is injectable for testing via `opts.connectorFactory`.
469
-
470
- ---
471
-
472
- ## Questionnaire System
473
-
474
- Interactive pre-flight for `compose new`. Runs automatically on first invocation, then only with `--ask`. Skip entirely with `--auto`.
475
-
476
- ### Questions Asked
477
-
478
- 1. **Refine description** -- text input with previous answer as default
479
- 2. **Project type** -- CLI tool, Web API, Library/SDK, Full-stack app, Other
480
- 3. **Language/runtime** -- Node.js (JS), Node.js (TS), Python, Go, Rust, Other
481
- 4. **Scope** -- Small (1-3 features), Medium (3-8), Large (8+)
482
- 5. **Research** -- yes/no: research prior art before brainstorming?
483
- 6. **Additional context** -- multiline free-form notes
484
- 7. **Review agent** -- Human (gate prompt), Codex (automated review), Skip review
485
- 8. **Confirm** -- summary + launch confirmation
486
-
487
- ### Answer Persistence
488
-
489
- Answers are saved to `.compose/questionnaire.json`. On subsequent runs:
490
- - Without `--ask`: saved answers are loaded silently to enrich the intent
491
- - With `--ask`: saved answers appear as defaults (press Enter to keep)
492
-
493
- ### Pipeline Customization
494
-
495
- The review agent choice modifies the pipeline:
496
- - "Codex (automated review)" sets the `review_gate` to `--mode review`
497
- - "Skip review" disables the `review_gate` step
498
-
499
- ### Enriched Intent
500
-
501
- The questionnaire output is an enriched intent string combining:
502
- - Refined description
503
- - Project constraints (type, language, scope)
504
- - Additional context notes
505
- - Any existing project context (README, package.json, project-analysis.md)
506
-
507
- ---
508
-
509
- ## Gate System
510
-
511
- Gates pause the pipeline for human decisions. Three outcomes:
512
-
513
- | Key | Outcome | Effect |
514
- |-----|---------|--------|
515
- | `a` | **approve** | Proceed to `on_approve` step |
516
- | `r` | **revise** | Loop back to `on_revise` step |
517
- | `k` | **kill** | Terminate the flow |
518
-
519
- ### Conversation Mode
520
-
521
- If the user types anything other than `a`/`r`/`k`, it's collected as a note/question. The user can ask questions or provide feedback before making their decision. Notes are included in the rationale sent to Stratum.
522
-
523
- ```
524
- Gate: review_gate
525
- [a]pprove -> roadmap
526
- [r]evise -> brainstorm
527
- [k]ill -> (terminate)
528
- Or type a question/comment to discuss before deciding.
529
-
530
- > What about error handling for edge cases?
531
- (noted -- enter a/r/k when ready to decide)
532
- > The feature list looks comprehensive
533
- (noted -- enter a/r/k when ready to decide)
534
- > a
535
- Notes collected: 2
536
- Additional rationale (or Enter to use notes):
47
+ npx compose init # writes .compose/, registers MCP, scaffolds ROADMAP and pipeline specs
48
+ npx compose new "what you want to build"
537
49
  ```
538
50
 
539
- ### Rationale
540
-
541
- A rationale is always required. If notes were collected during conversation mode, they serve as the rationale. Otherwise, the user is prompted explicitly.
542
-
543
- ### Gate Definitions in Specs
544
-
545
- ```yaml
546
- functions:
547
- design_gate:
548
- mode: gate
549
- timeout: 3600 # seconds
550
-
551
- steps:
552
- - id: design_gate
553
- function: design_gate
554
- on_approve: plan # proceed to this step
555
- on_revise: explore_design # loop back
556
- on_kill: null # null = terminate flow
557
- ```
558
-
559
- ### Artifact Display
560
-
561
- Before gate prompts in the `new` pipeline, the artifact produced by the prior step is displayed so the user can make an informed decision. For short documents (<= 80 lines), the full content is shown; for longer ones, the first 60 lines plus a truncation notice.
562
-
563
- ---
564
-
565
- ## Validation System
566
-
567
- Agent-as-validator: after a step writes its artifact, a separate lightweight agent call reads the artifact and checks it against criteria defined in the pipeline spec.
568
-
569
- ### How It Works
570
-
571
- 1. The pipeline spec defines `validate` on a step:
572
- ```yaml
573
- - id: brainstorm
574
- validate:
575
- artifact: docs/discovery/brainstorm.md
576
- criteria:
577
- - "Contains at least 3 features with short codes"
578
- - "Contains user stories in 'As a...' format"
579
- - "Contains at least 2 architecture options"
580
- ```
581
- 2. After the step completes, the validator dispatches a fresh Claude call with a prompt asking it to read the artifact and check each criterion.
582
- 3. The validator returns `{ valid: boolean, issues: string[] }`.
583
- 4. If `valid` is false, a fix agent (claude) is dispatched to fix all issues, then the pipeline continues.
584
- 5. If the validator can't extract structured JSON, it optimistically assumes valid (no crash).
585
-
586
- ### Criteria
587
-
588
- Criteria are human-readable strings. The validator agent interprets them and returns a boolean judgment per criterion. This means validation is semantic, not syntactic -- "Contains at least 3 features" is checked by an agent reading the document, not by a regex.
589
-
590
- ---
591
-
592
- ## Pipeline CLI
593
-
594
- `compose pipeline` provides full control over `pipelines/build.stratum.yaml`.
595
-
596
- ### `show`
597
-
598
- Pretty-prints the pipeline with color-coded step types:
599
- - Green: agent steps (with ensure count, retries, on_fail)
600
- - Yellow: gate steps (with timeout)
601
- - Cyan: flow steps (sub-flow name, inner steps, agent)
602
- - Gray: skipped steps (with reason)
603
-
604
- Also shows sub-flow details and contracts.
605
-
606
- ### `set`
607
-
608
- Modify step properties:
609
-
610
- ```bash
611
- # Change which agent executes a step
612
- compose pipeline set execute --agent codex
613
-
614
- # Convert a step to a human gate
615
- compose pipeline set review --mode gate
616
-
617
- # Convert a step to a codex review sub-flow
618
- compose pipeline set review --mode review
619
- # Creates a review_check sub-flow with codex agent, ReviewResult contract,
620
- # ensure "result.clean == True", retries 10
621
-
622
- # Convert back to a regular agent step
623
- compose pipeline set review --mode agent
624
-
625
- # Set retry count
626
- compose pipeline set blueprint --retries 5
627
- ```
628
-
629
- ### `add`
630
-
631
- Insert a new step after an existing one:
632
-
633
- ```bash
634
- compose pipeline add --id lint --after execute --agent claude --intent "Run linter and fix issues"
635
- ```
636
-
637
- Creates a step with default `PhaseResult` output contract, 2 retries, and `depends_on: [<after>]`. Rewires the next step's dependencies.
638
-
639
- ### `remove`
640
-
641
- Remove a step and rewire dependencies:
642
-
643
- ```bash
644
- compose pipeline remove prd
645
- ```
646
-
647
- Steps that depended on the removed step inherit its dependencies. Gate references (`on_approve`, `on_revise`, `on_fail`) are also rewired.
648
-
649
- ### `enable` / `disable`
51
+ Add an isolated feature to an existing project:
650
52
 
651
53
  ```bash
652
- compose pipeline enable prd architecture report # remove skip_if
653
- compose pipeline disable prd # set skip_if: "true"
54
+ npx compose feature AUTH-1 "JWT middleware with refresh tokens"
55
+ npx compose build AUTH-1
654
56
  ```
655
57
 
656
- ---
657
-
658
- ## Recovery Logic
659
-
660
- When a step's postconditions fail (`ensure_failed` or `schema_failed`), Compose runs a two-phase recovery:
661
-
662
- ### 1. Fix Pass
663
-
664
- A fix agent is dispatched with the violations:
665
-
666
- ```
667
- Fix step "review" -- postconditions failed:
668
- - result.clean == True
669
- Fix every issue. Do not skip any.
670
- ```
671
-
672
- For codex steps, the fix pass goes to **claude** (cross-agent fix). For claude steps, the fix is same-agent but with a distinct prompt focused on fixing.
673
-
674
- ### 2. Retry
675
-
676
- After the fix pass, the original step is retried with a retry prompt that includes both the original intent and the violations:
677
-
678
- ```
679
- RETRY -- Previous attempt failed postconditions:
680
- - result.clean == True
681
- Fix these issues and try again.
682
- [original step prompt]
683
- ```
684
-
685
- ### Retry Limits
686
-
687
- Each step has a `retries` count (set in the pipeline spec). The review sub-flow defaults to 10 retries; coverage defaults to 15. When retries are exhausted, `on_fail` routing kicks in (if configured), or the step fails.
688
-
689
- ### on_fail Routing
690
-
691
- Steps can specify `on_fail: <step-id>` to route to a different step when retries are exhausted. The `verification` step uses `on_fail: blueprint` to loop back for a blueprint rewrite.
692
-
693
- ---
694
-
695
- ## Progress Logging
696
-
697
- During agent execution, Compose renders a live progress display to stderr with two modes:
698
-
699
- **Collapsed (default):** Shows the last 5 tool events, a status line with elapsed time and tool count, and a key hints bar. Redraws in-place every 5 seconds (heartbeat).
700
-
701
- ```
702
- ● explore ─ ● scope ─ ◉ blueprint ─ ○ plan ─ ○ execute ─ ○ review ─ ○ codex
703
- [3/17] blueprint...
704
- ↳ Read: lib/build.js
705
- ↳ Grep: pattern match in server/
706
- ↳ Read: docs/features/FEAT-1/design.md
707
- ↳ Edit: src/App.jsx
708
- ↳ Bash: npm test
709
- blueprint · 45s · 5 calls
710
- keys: t=toggle s=skip r=retry Ctrl+C=abort
711
- ```
712
-
713
- **Expanded:** Shows all tool events as they arrive, plus elapsed time heartbeat every 5 seconds.
714
-
715
- ### Key commands during build
716
-
717
- | Key | Action |
718
- |-----|--------|
719
- | `t` | Toggle between collapsed and expanded view |
720
- | `s` | Skip the current step (interrupts agent, moves to next) |
721
- | `r` | Retry the current step (interrupts agent, re-runs same step) |
722
- | `Ctrl+C` | Abort the build |
723
-
724
- ### Pipeline bar
725
-
726
- The pipeline bar shows all build steps with status indicators:
727
- - `●` (green) — completed steps
728
- - `◉` (cyan, bold) — current active step
729
- - `○` (dim) — pending steps
730
-
731
- Adapts to terminal width with a sliding window for narrow terminals.
732
-
733
- ### Findings table
734
-
735
- When the review step returns violations, they're rendered as a formatted table with severity coloring (must-fix=red, should-fix=yellow, nit=gray).
736
-
737
- ### Gate panel
738
-
739
- Gate prompts render as a boxed panel showing the artifact path, phase transition, and color-coded action options instead of raw readline text.
740
-
741
- Enable verbose event logging with `COMPOSE_DEBUG=1`.
742
-
743
- ---
744
-
745
- ## Result Normalization and JSON Extraction
746
-
747
- The result normalizer (`lib/result-normalizer.js`) bridges the gap between streaming agent text and structured step results.
748
-
749
- ### Schema Injection
750
-
751
- When a step has `output_fields`, the normalizer:
752
- 1. Converts Stratum's flat type map (`{ clean: "boolean", findings: "array" }`) to JSON Schema
753
- 2. Injects schema instructions into the prompt via `injectSchema()`
754
- 3. The agent sees: "include a JSON code block at the very end of your response matching this schema"
755
-
756
- ### JSON Extraction
757
-
758
- After the agent completes, the normalizer tries three extraction strategies in order:
58
+ ## Documentation
759
59
 
760
- 1. **Full text parse** -- the entire output is valid JSON
761
- 2. **Fenced block** -- extract from ` ```json ... ``` `
762
- 3. **Balanced braces** -- find the first `{` and its matching `}`, parse the substring
60
+ Topic-scoped reference:
763
61
 
764
- If all strategies fail, a warning is logged and a fallback `{ summary: "..." }` is returned (first 200 chars of output). The pipeline does not crash.
765
-
766
- ### Error Handling
767
-
768
- - `AgentError` -- thrown when the agent yields an error event
769
- - `ResultParseError` -- thrown when JSON extraction fails (includes raw text for debugging)
770
-
771
- ---
772
-
773
- ## Vision Writer Integration
774
-
775
- The `VisionWriter` (`lib/vision-writer.js`) maintains `.compose/data/vision-state.json` with atomic read-modify-write operations (POSIX rename).
776
-
777
- ### What It Tracks
778
-
779
- - **Feature items**: Each feature gets a vision item with id, type, title, status, phase, featureCode, slug, confidence, timestamps
780
- - **Phase updates**: As each step executes, the item's `lifecycle.currentPhase` is updated
781
- - **Gate entries**: Each gate creates a record with flowId, stepId, itemId, status, timestamps
782
- - **Gate resolutions**: Outcome (approve/revise/kill) and resolution timestamp
783
-
784
- ### Lookup Conventions
785
-
786
- Supports both `feature:CODE` (seed convention) and `lifecycle.featureCode` (lifecycle-manager convention) for feature item lookup.
787
-
788
- ### Status Transitions
789
-
790
- ```
791
- planned -> in_progress -> complete
792
- planned -> in_progress -> killed
793
- ```
794
-
795
- ---
796
-
797
- ## Configuration Files
798
-
799
- ### `.compose/compose.json`
800
-
801
- Project-level configuration. Created by `compose init`.
802
-
803
- ```json
804
- {
805
- "version": 2,
806
- "capabilities": {
807
- "stratum": true,
808
- "lifecycle": true
809
- },
810
- "agents": {
811
- "claude": { "detected": true, "skillInstalled": true },
812
- "codex": { "detected": true, "skillInstalled": true },
813
- "gemini": { "detected": false }
814
- },
815
- "paths": {
816
- "docs": "docs",
817
- "features": "docs/features",
818
- "journal": "docs/journal"
819
- }
820
- }
821
- ```
822
-
823
- ### `.compose/questionnaire.json`
824
-
825
- Saved questionnaire answers (enriched intent, project type, language, scope, research preference, notes, review agent choice).
826
-
827
- ### `.compose/data/vision-state.json`
828
-
829
- Vision tracker state: items, connections, gates. Managed by `VisionWriter`. Atomic writes via temp file + rename.
830
-
831
- ### `.compose/data/active-build.json`
832
-
833
- Active build state for resume/abort:
834
-
835
- ```json
836
- {
837
- "featureCode": "FEAT-1",
838
- "flowId": "uuid",
839
- "startedAt": "2026-03-11T...",
840
- "currentStepId": "blueprint",
841
- "specPath": "pipelines/build.stratum.yaml"
842
- }
843
- ```
844
-
845
- ### `pipelines/build.stratum.yaml`
846
-
847
- The build pipeline spec. Editable via `compose pipeline` or by hand. See [The Build Pipeline](#the-build-pipeline).
848
-
849
- ### `pipelines/new.stratum.yaml`
850
-
851
- The kickoff pipeline spec. See [The Kickoff Pipeline](#the-kickoff-pipeline).
852
-
853
- ### `.mcp.json`
854
-
855
- MCP server registration. `compose init` adds:
856
-
857
- ```json
858
- {
859
- "mcpServers": {
860
- "compose": {
861
- "command": "node",
862
- "args": ["<compose-root>/server/compose-mcp.js"]
863
- }
864
- }
865
- }
866
- ```
867
-
868
- ### `ROADMAP.md`
869
-
870
- Scaffolded from `templates/ROADMAP.md` with project name, date, and placeholder phases. Updated by `compose feature` and the build pipeline.
871
-
872
- ---
873
-
874
- ## MCP Server
875
-
876
- Compose exposes project state as MCP tools via `server/compose-mcp.js` (stdio transport). Registered in `.mcp.json` by `compose init`. Available tools:
877
-
878
- | Tool | Description |
879
- |------|-------------|
880
- | `get_vision_items` | Query items by phase, status, type, keyword |
881
- | `get_item_detail` | Full item detail with connections |
882
- | `get_phase_summary` | Status/type distribution per phase |
883
- | `get_blocked_items` | Items blocked by non-complete dependencies |
884
- | `get_current_session` | Active session context (tool count, items touched) |
885
- | `bind_session` | Bind agent session to a lifecycle feature |
886
- | `get_feature_lifecycle` | Feature lifecycle state, phase history, artifacts |
887
- | `kill_feature` | Kill a feature with reason |
888
- | `complete_feature` | Mark feature complete (ship phase only) |
889
- | `assess_feature_artifacts` | Quality signals for feature artifacts |
890
- | `scaffold_feature` | Create feature folder with template stubs |
891
- | `approve_gate` | Resolve a pending gate (approved/revised/killed) |
892
- | `get_pending_gates` | List pending gates |
893
- | `agent_run` | Run a prompt against an AI agent (claude or codex) with optional JSON schema |
894
- | `start_iteration_loop` | Start an iteration loop on a feature |
895
- | `report_iteration_result` | Report iteration outcome (clean/dirty/max_reached) |
896
- | `abort_iteration_loop` | Abort an active iteration loop |
897
-
898
- ---
899
-
900
- ## Pipeline Specs
901
-
902
- Compose ships with five pipeline specs in `pipelines/`:
903
-
904
- | Spec | Flow | Purpose |
905
- |------|------|---------|
906
- | `new.stratum.yaml` | `new` | Product kickoff: research, brainstorm, roadmap, scaffold |
907
- | `build.stratum.yaml` | `build` | Feature lifecycle: design through ship |
908
- | `review-fix.stratum.yaml` | `review_fix` | Two-phase loop: implement then review/fix until clean |
909
- | `coverage-sweep.stratum.yaml` | `coverage_sweep` | Test loop: run tests, fix failures until passing |
910
- | `compose_feature.stratum.yaml` | `compose_feature` | Legacy function-based lifecycle spec |
911
-
912
- ### Stratum IR v0.3
913
-
914
- Specs use Stratum IR v0.3 format (backward-compatible superset of v0.2). All existing v0.2 specs run unchanged. Specs that use v0.3 features declare `ir_version: "0.3"` at the top level.
915
-
916
- **v0.2 primitives (all retained):**
917
- - **contracts**: Output shape definitions with typed fields
918
- - **functions**: Reusable compute/gate definitions with retries and postconditions
919
- - **flows**: Step graphs with dependencies, routing, sub-flows
920
- - **ensure expressions**: Python-like postconditions (`result.clean == True`, `file_exists(path)`)
921
- - **input expressions**: Data flow between steps (`$.input.x`, `$.steps.prev.output.y`)
922
- - **skip_if / skip_reason**: Conditional step skipping
923
-
924
- **v0.3 additions (STRAT-PAR, STRAT-REV):**
925
- - **`decompose` step type**: the agent emits a **TaskGraph** — an array of tasks, each with `files_owned` (write set), `files_read` (read set), and `depends_on` (dependency list). Used to break a sequential step into independent subtasks before parallel execution.
926
- - **`parallel_dispatch` step type**: consumes a TaskGraph and coordinates concurrent agent runs. Fields: `source` (JSON pointer to task array, e.g. `$.steps.decompose.output.tasks`), `max_concurrent` (concurrency cap, default 3), `isolation` (`worktree` for write isolation, `branch`, or `none` for read-only tasks), `merge` (`sequential_apply` | `manual`), `require` (`all` | `any` | integer N), and `intent_template` (per-task prompt template with `{field}` interpolation).
927
- - **`no_file_conflicts` ensure**: validates that no two independent tasks share `files_owned` entries.
928
- - **`isolation: none`**: allows read-only parallel tasks (e.g. review lenses) to run without git worktree overhead.
929
-
930
- ---
931
-
932
- ## Examples and Workflows
933
-
934
- ### Start a new project from scratch
935
-
936
- ```bash
937
- mkdir my-cli-tool && cd my-cli-tool
938
- compose new "CLI tool that converts CSV files to JSON with filtering and validation"
939
- # Answer questionnaire questions
940
- # Approve brainstorm at gate
941
- # Approve roadmap at gate
942
- # Feature folders scaffolded
943
-
944
- compose build CSV-1 # build the first feature
945
- ```
946
-
947
- ### Add a feature to an existing project
948
-
949
- ```bash
950
- cd existing-project
951
- compose import # scan and analyze
952
- compose feature AUTH-1 "JWT auth middleware with refresh tokens"
953
- compose build AUTH-1
954
- ```
955
-
956
- ### Customize the pipeline before building
957
-
958
- ```bash
959
- compose init
960
- compose pipeline show # see default pipeline
961
- compose pipeline enable prd architecture # enable optional phases
962
- compose pipeline set review --agent codex --retries 5
963
- compose pipeline add --id lint --after execute --agent claude --intent "Run ESLint and fix issues"
964
- compose build FEAT-1
965
- ```
966
-
967
- ### Skip research for a well-understood project
968
-
969
- ```bash
970
- compose new "Internal admin dashboard for existing API" --ask
971
- # At "Research prior art?" question, answer: n
972
- ```
973
-
974
- ### Use automated review instead of human gates
975
-
976
- ```bash
977
- compose new "microservice template" --ask
978
- # At "Who should review?" question, choose: Codex (automated review)
979
- ```
980
-
981
- ### Abort a stuck build
982
-
983
- ```bash
984
- compose build --abort
985
- ```
986
-
987
- ### View pipeline state
988
-
989
- ```bash
990
- compose pipeline show
991
- ```
992
-
993
- Output:
994
- ```
995
- Pipeline: build (17 steps)
996
-
997
- 1. explore_design agent agent: claude [2 ensures] (retries: 2)
998
- 2. scope agent agent: claude (retries: 2)
999
- 3. design_gate gate human gate (timeout: 3600s)
1000
- 4. prd skip PRD skipped by default
1001
- 5. architecture skip Architecture skipped by default
1002
- 6. blueprint agent agent: claude [2 ensures] (retries: 3)
1003
- 7. verification agent agent: claude [1 ensures] (retries: 2) -> on_fail: blueprint
1004
- 8. plan_gate gate human gate (timeout: 3600s)
1005
- 9. decompose agent agent: claude [2 ensures] (retries: 2)
1006
- 10. execute par parallel_dispatch (worktree isolation)
1007
- 11. review flow parallel_review: triage → lenses → merge (retries: 5)
1008
- 12. codex_review flow review_check: review (agent: codex, retries: 3)
1009
- 13. coverage flow coverage_check: run_tests (agent: claude, retries: 15)
1010
- 14. report skip Report skipped by default
1011
- 15. docs agent agent: claude (retries: 2)
1012
- 16. ship agent agent: claude (retries: 2)
1013
- 17. ship_gate gate human gate (timeout: 1800s)
1014
- ```
62
+ - [docs/install.md](docs/install.md) — prerequisites, `compose init`, `compose setup`, `~/bin` symlink, `compose install` compatibility shim.
63
+ - [docs/cli.md](docs/cli.md) — every subcommand (`new`, `import`, `feature`, `build`, `pipeline`, `init`, `setup`, `doctor`, `start`).
64
+ - [docs/cockpit.md](docs/cockpit.md) — web UI shell: zones, graph view, context panel, ops strip, agent bar, persistence.
65
+ - [docs/pipelines.md](docs/pipelines.md) — kickoff and build pipelines, sub-flows, contracts, `on_fail` routing, Stratum IR v0.3.
66
+ - [docs/agents.md](docs/agents.md) — agent connectors, message envelope, Claude/Codex/Opencode connectors, registry.
67
+ - [docs/lifecycle.md](docs/lifecycle.md) — questionnaire, gate system, validation, recovery, progress logging, vision tracker, result normalization.
68
+ - [docs/configuration.md](docs/configuration.md) — `.compose/*.json`, pipeline specs, `.mcp.json`, `ROADMAP.md`, environment variables.
69
+ - [docs/mcp.md](docs/mcp.md) — MCP server tool list (vision, lifecycle, gates, iteration loops).
70
+ - [docs/examples.md](docs/examples.md) — worked workflows and the full `compose pipeline` editing reference.
1015
71
 
1016
- ### Environment Variables
72
+ ### Specs and design
1017
73
 
1018
- | Variable | Default | Purpose |
1019
- |----------|---------|---------|
1020
- | `CLAUDE_MODEL` | `claude-sonnet-4-6` | Default model for ClaudeSDKConnector |
1021
- | `CODEX_MODEL` | `gpt-5.4` | Default model for CodexConnector |
1022
- | `COMPOSE_DEBUG` | (unset) | Enable verbose event logging to stderr |
1023
- | `COMPOSE_TARGET` | (unset) | Override project root for `compose start` |
1024
- | `COMPOSE_SERVER_DISPATCH` | unset | Set to `1` to route `parallel_dispatch` steps through Stratum's server-side executor. Covers `isolation: "none"` unconditionally, and `isolation: "worktree"` steps that declare `capture_diff: true` (Compose consumes diffs from poll response and merges them client-side). When the step also declares `defer_advance: true`, Compose reports merge_status back via `stratum_parallel_advance` — client-side merge conflicts surface as `{status: 'complete', output: {merge_status: 'conflict'}}` and Compose sets `buildStatus='failed'` (non-zero CI exit). Worktree steps without `defer_advance` use the legacy throw-on-conflict path. |
1025
- | `COMPOSE_SERVER_DISPATCH_POLL_MS` | `500` | Poll interval (ms) against `stratum_parallel_poll`. Lower = faster task-transition event propagation; higher = less MCP load. |
74
+ - [docs/PRD.md](docs/PRD.md)
75
+ - [docs/PRODUCT-SPEC.md](docs/PRODUCT-SPEC.md)
76
+ - [docs/ROADMAP.md](docs/ROADMAP.md)
77
+ - [docs/taxonomy.md](docs/taxonomy.md)
78
+ - [docs/compose-one-pager.md](docs/compose-one-pager.md)