>>> orchestrator:recent-changes >>>

• 048-graph-core-migration: Orchestrator v2 graph core and migration (M047): unify the file-based knowledge

<<< orchestrator:recent-changes <<<

CLAUDE.md — orchestrator

What This Is

A standalone autonomous multi-phase orchestrator. This repo holds the orchestrator itself — its commands, scripts, templates, reference docs, and packaging installers. It uses its own orchestration workflow (orchestrator:* commands) to develop itself.

Project Status

v0.9.3 (2026-05-01). 14 commands, 80+ scripts, 24+ templates, 15 reference docs, 6 user guides, packaging/ layer, runtime + format + backend adapter tree. Launch event shipped 2026-05-09 (M035, packaging & distribution). Closed: M011 (spec management), M012 (spec wiki, 2026-04-21), M013 (GitHub native integration), M014 extended (spec management + comment→workflow, 2026-04-25), M015 (standalone cutover), M016 (autonomous hardening), M018 (context compression layer, 2026-04-28), M019 Tier 1+2+3 (observability emitter + cost rollup), M020 (knowledge layer maturation, 2026-04-25), M021 (autonomous hardening v2), M024 (universal intake & routing), M025 (installer coexistence, 2026-04-23), M026 (conversus-OSS migration, 2026-04-25), M027 (cost+quality observability surfaces, 2026-04-27), M028 (autonomous hardening v3, 2026-04-29), M030 (adaptive model selection, 2026-05-01), M031 (right-sized entry, 2026-05-01), M032 (wiki distribution + init integration, 2026-05-05), M033 (project onboarding experience, 2026-05-04 — closed under US-8 AS-5 signed-attestation fallback; friendly-tester pass pending under revised 2026-05-19 deadline per launch-sequencing-amendment Q1, revised 2026-05-11), M029 (roadmap visibility & CLI UX, 2026-05-06), M037 (wiki team-feedback-ready, 2026-05-07), M036 (reference-corpus ingest, M036a scope P00–P07, milestone-grain closure ceremony reconciled 2026-05-11 per Option A of .orchestrator/proposals/papercut-m036b-deferred-state-vs-find-active.md; M036b P08+P09 scope deferred to a future demand-driven milestone), M035 (packaging & distribution — launch event, closed 2026-05-09 — validate-milestone.sh 185/185 PASS; acceptance battery pass=174 fail=0 skip=2; npm + homebrew + curl-pipe-bash publishing pipelines + GH release automation + install-script integrity + orchestrator:update first-class command all on disk; MOS-3/MOS-4/MOS-5 deferred to first v* tag publication; T06 task-grain bookkeeping reconciled 2026-05-11 via fix(M035): reconcile T06 roadmap-vs-disk drift via Path A), M041 (orchestrator:detective — issue-triage-to-GitHub command, closed 2026-05-25 — 6 phases P01–P06; M041-VALIDATED + M041-SUMMARY.md on disk; acceptance battery SC-1..SC-7 pass=7 skip=0 fail=0; per-phase suites all green; conversus-gated spec with 3 P0 amendments; FR-8 cross-command hooks (doctor/auto mechanical + verify/dispatch LLM-guidance) + FR-9 confirmation gate + P06 config-driven repo/threshold + #Q-1 corpus-validation harness shipped). In progress: none. Next up: post-launch fast-follow queue (all demand-driven): M009 (multi-runtime parity audit — when first non-CC users arrive) → M023 (design layer) → M034 + M038 + M040 (paired demand-driven slot) → M036b (reference-corpus post-launch slice, P08–P09 wiki projection + operator-facing scale UX) → wiki-ux-deep + external-tool-adapters → M010 (Managed Agents + Codex Cloud). Pre-launch operational follow-up: M033 friendly-tester pass against the four init branches (protocol at tests/m033-acceptance/friendly-tester-pass/protocol.md) — pending under revised 2026-05-19 deadline (deadline pushed 2026-05-11 per operator authorization); runs as a human-recruitment task, not autonomously.

Forward Roadmap (revised 2026-05-11 — post-launch posture)

Launch event shipped 2026-05-09 (M035, packaging & distribution). The pre-launch milestone queue is fully drained: M028 closed 2026-04-29, M030 closed 2026-05-01, M031 closed 2026-05-01, M036 closed 2026-05-02 (M036a scope P00–P07; milestone-grain closure ceremony reconciled 2026-05-11), M033 closed 2026-05-04 (under signed-attestation fallback; friendly-tester pass pending under revised 2026-05-19 deadline), M032 closed 2026-05-05, M029 closed 2026-05-06, M037 closed 2026-05-07, M035 closed 2026-05-09. All risk-ranked per the 2026-05-03 launch sequencing amendment (.orchestrator/proposals/launch-sequencing-amendment-2026-05-03.md).

Launch-event posture: CC-only. Codex CLI / Cursor / Managed Agents are aspirational fast-follows; we shipped CC-exclusive and broaden the runtime story when real users arrive with non-CC projects.

Resolved 2026-05-11: the M036b deferred-state paper-cut (.orchestrator/proposals/papercut-m036b-deferred-state-vs-find-active.md) — M036 now carries M036-VALIDATED + M036-SUMMARY.md + milestone-grain unit_close JSONL for the M036a P00–P07 scope; M036b P08+P09 deferred to a future demand-driven milestone via Option A. find-active-milestone.sh .orchestrator now returns NONE.

Pre-launch operational follow-up still open: M033 friendly-tester pass against the four init branches (greenfield-empty / greenfield-with-materials / existing-codebase / migrating). Protocol at tests/m033-acceptance/friendly-tester-pass/protocol.md — requires a human tester not familiar with orchestrator (maintainers and contributors explicitly excluded). Revised deadline 2026-05-19 (pushed 2026-05-11 per operator authorization; original 2026-05-12 lapsed without recruited tester).

Retired 2026-05-07: M036a P03 live-LLM smoke (commit c03efcc4). Real claude -p invocation through extract_tier_2_dispatch live mode against a synthetic representative-of-PBJ fixture; gate stubbed PASS; cost $0.24; 8/8 verifications green. Wiring at scripts/knowledge/lib/extract-tier-2-llm.sh live branch (CON-3 default-closed via ORCHESTRATOR_TIER2_LIVE=1) + harness tools/m036-p03-live-smoke.sh. Evidence under .orchestrator/milestones/M036/M036-ACCEPTANCE-EVIDENCE.md Addendum 2026-05-07 + p03-live-smoke-evidence/.

Post-launch fast-follows (in priority order, demand-driven): M009 (multi-runtime parity audit) → M023 (design layer) → M034 (interactive review gates) + M038 (living documents) + M040 (ambient feedback loop — daily/weekly brief + decision contradiction gate + frictionless capture inbox) [grouped demand-driven slot — strong primitive overlap among the three; M040's feedback/brief composes with M038 living-docs, and M040's contradiction gate emits M034 decision-packet shape; absorption / sibling decision deferred to queue-entry time] → M036b (reference-corpus post-launch slice — wiki projection + operator-facing scale UX, P08–P09) → ~~M043 (Cloudflare Pages + Access wiki-deploy target — fixes the private-Pages footgun)~~ closed 2026-06-05 (5 phases P00–P04; validate-milestone.sh M043 PASS 62/62; M043-VALIDATED + M043-SUMMARY.md on disk; closed at shippable scope US-1..US-3 with the US-4 live pass forward-pointed under the signed deferred-validation note tests/m043-acceptance/live-deploy/evidence/2026-06-04-deferred-validation.md per FR-13/SC-9; demand-driven by a live pbj-central incident 2026-06-04; brief at .orchestrator/proposals/M043-wiki-cloudflare-access-deploy-target.md) → wiki-ux-deep + external-tool-adapters (knowledge-graph viewer & multi-tool sync, see .orchestrator/proposals/post-launch-wiki-ux-and-adapters.md — narrowed by M037 absorbing F3/F5/F1.2 readability scope) → M010 (Managed Agents + Codex Cloud).

Near-term D021-style hotfixes — all 19 items shipped or queued for deferred milestones as of the paper-cut sweep (papercut-sweep/pre-M030 branch, see .orchestrator/proposals/papercut-sweep-pre-M030.md). Two layer-2 follow-ups remain queued:

• M032 spec-side invariant for staged-dirs collision — Finding A invariant ("project-owned paths must not collide with staged dirs"). Text-only amendment deferred until M032 enters planning. The runtime fix (planner-template default → tools/verify/) shipped in commit 8bcba64 and is already live.
• M034 boundary-translation decision packet (Layer-2 of plan-time SQL column drift) — folds into the boundary_translation decision-packet type per Finding E in .orchestrator/proposals/M034-interactive-review-gates.md. Layer-1 (real-DB verifier or "real-app smoke test pending" callout) shipped in commands/plan-phase.md Plan-Time Discipline rule 5.

The historical hotfix list (with patch shapes inline) is preserved verbatim in the paper-cut sweep PR's first commit (.orchestrator/proposals/papercut-sweep-pre-M030.md) so future authors can audit the shipped shapes and the original dogfood-incident context.

Launch posture: CC-only. Codex CLI / Cursor / Managed Agents are aspirational fast-follows; we ship CC-exclusive and broaden the runtime story when real users arrive with non-CC projects.

Proposal briefs for M032, M033, M035, M037, M038 are at .orchestrator/proposals/ (each is an input for orchestrator:specify when that milestone enters the queue; M029's brief lives there for historical reference). Brief summaries:

• M037 (wiki team-feedback-ready) — closed 2026-05-07. Three phases (P01 + P02 + P03), validate-milestone.sh M037 reports 71/71 PASS; acceptance battery pass=11 skip=0 fail=0; wiki-strict-build PASS; M037-VALIDATED + M037-SUMMARY.md + M037-ACCEPTANCE-EVIDENCE.md + phase-grain + milestone-grain unit_close all on disk. P01 closed 2026-05-06 ship-it minimum (homepage card grid + wiki.landing_cards: config schema + version: → nav title + DR-### heading-shape pivot + navigation.tabs + toc_depth: 2 + content.action.edit + install-template config.yml clobber fix). P02 closed 2026-05-07 publishing-robustness paper-cut bundle (FR-18..FR-22 / US-10..US-14 / SC-13..SC-17). P03 closed 2026-05-07 PBJ-feedback polish series — round-3.5 (8 fixes: pymdownx.emoji + orphan-card pre-filter + wiki-init final-step regen + glossary include-wrapper + version-in-metadata + file→repo_url metadata projection + [unknown] suffix drop + breadcrumb shim + file-feedback affordance) + round-3.5-sync + round-4 (framework-managed wiki/overrides/ refresh) + round-5 (drop navigation.sections for collapsible-drawer left-nav). PBJ-central live-dogfood satisfaction signal received after round-5. FR-12..FR-17 (formal P03 scope) deferred post-launch via .orchestrator/proposals/M037-fr-12-17-deferred-scope.md; absorbed by post-launch-wiki-ux-and-adapters.md. yaml-merge list-element preservation gap surfaced at round-5 — deferred post-launch follow-up. See .orchestrator/milestones/M037/M037-SUMMARY.md.
• M031 (right-sized entry) — closed 2026-05-01. 5 phases (P00–P04), 14 success criteria verified via the M031 acceptance battery (tests/m031-acceptance/run-acceptance-battery.sh → BATTERY: pass=15 fail=0); M031-VALIDATED marker + M031-SUMMARY.md + milestone-grain unit_close all on disk; validate-milestone.sh reports 117/117 PASS. Shipped surfaces: build-context.sh --profile=quick|standard|full + --meta-out JSON sidecar; FR-4 collapse of commands/dispatch.md:21 Skip-payload-assembly branch; Tier A+ middle flow under .orchestrator/tier-a-plus/<slug>/; commands/do.md universal-entry skill + scripts/intake/do-entry.sh driver; auto_proceed: true default flip + AD-9 compound-change banner via run-doctor.sh; QUICK_BUDGET_DRIFT informational warning in efficiency-footer.sh. See .orchestrator/milestones/M031/M031-SUMMARY.md.
• M028 (autonomous hardening v3) — closed 2026-04-29. Hook portability + 5 shape classes (AP-010..AP-014) + investigation-pattern wrappers + M025 hook-shim follow-up shipped. See milestones/M028/M028-SUMMARY.md.
• M030 (adaptive model selection) — closed 2026-05-01. 8 phases (P00–P07), 14 SCs verified via M030 acceptance battery (BATTERY: pass=22 fail=0); shadow-mode default, FR-9 programmatic flip-gate enforces shadow-corpus threshold before live routing; CON-3 symbolic-tier closure preserved end-to-end. See .orchestrator/milestones/M030/M030-SUMMARY.md.
• M032 (wiki distribution + init integration) — closed 2026-05-05. 4 phases (P01–P04), 14 success criteria + acceptance battery (tests/m032-acceptance/run-acceptance-battery.sh → BATTERY: pass=10 skip=1 fail=0); M032-VALIDATED marker + M032-SUMMARY.md + M032-ACCEPTANCE-EVIDENCE.md + milestone-grain unit_close all on disk; validate-milestone.sh M032 reports 122/122 PASS. SC-5 fixture-completeness skip documented as Deferred-Validation Acknowledgment block (operator follow-up: extend wiki-init.sh --deploy to bundle-stage wiki-deploy.sh from $REPO_ROOT if missing in $PROJECT_DIR; recommended fix-during-M035 packaging closure). See .orchestrator/milestones/M032/M032-SUMMARY.md.
• M033 (project onboarding experience) — closed 2026-05-04 under US-8 AS-5 signed-attestation fallback. 5 phases (P01–P05), M033-VALIDATED marker + M033-SUMMARY.md on disk. Friendly-tester pass against the four init branches (greenfield-empty / greenfield-with-materials / existing-codebase / migrating) deferred to ≤ 2026-05-19 deadline per .orchestrator/proposals/launch-sequencing-amendment-2026-05-03.md Q1 (pushed 2026-05-11 from original 2026-05-12 per operator authorization); protocol at tests/m033-acceptance/friendly-tester-pass/protocol.md. Not blocking M029 entry.
• M029 (roadmap visibility & CLI UX) — closed 2026-05-06. Three phases (P01–P03), 14 success criteria verified via the M029 acceptance battery (tests/m029-acceptance/run-acceptance-battery.sh → BATTERY: pass=14 fail=0); M029-VALIDATED marker + M029-SUMMARY.md + milestone-grain unit_close all on disk; validate-milestone.sh reports 101/101 PASS. Shipped surfaces: scripts/state/detect-invocation-context.sh (AD-1 single-resolve env block) + scripts/diagnostics/render-status-json.sh (FR-3 --format=json with AD-2 unconditional ANSI strip + AD-7 schema_version: "1.0") + commands/status.md headline block (FR-2) + commands/context.md (FR-4 read-only single-screen runtime profile) + scripts/diagnostics/render-position.sh at-rest tree renderer engine (FR-5 four-glyph alphabet) + commands/where.md skill (renderer-engine + LLM-instruction-skill split) + references/cross-milestone-feature-shape.md (AD-6 contract) + scripts/diagnostics/summarize-milestone.sh (AD-4 SC-8 oracle wrapper) + --live mode (FR-7, ▽ saved Nk canonical compact-form FR-8/#Q-G8 gated by AD-5 display_thresholds.compression_savings_pct: 5.0 config knob) + commands/auto.md ## Preflight Summary (FR-9, AD-3 four-priority non-interactive policy) + commands/start.md --auto-chain (FR-10, #Q-3 leave-marker-absent failure semantics, AUTO_CHAIN_STAGE_STUB fixture-only escape hatch). Scope tightened 2026-05-05 to wiki-is-the-view: FR-11 GitHub fold-in + FR-12 --refresh-github cut, deferred to demand-driven post-launch external-tool-adapters. See .orchestrator/milestones/M029/M029-SUMMARY.md.
• M035 (packaging & distribution) — last pre-launch milestone, two-layer scope: P00 + P01 ship pre-launch (--mode=symlink install for dogfooding velocity + orchestrator:status version-drift warning) and unblock multi-consumer-project freshness today; P02–P06 ARE the launch event (npm + homebrew + curl-pipe-bash publishing pipelines, GH release automation, install-script integrity, orchestrator:update first-class command). Captured 2026-04-28 after the roadmap gap surfaced.

Post-launch fast-follows:

• M009 (multi-runtime parity audit, deferred post-launch) — runtime-parity audit consuming references/RUNTIME-ASSUMPTIONS.md (foundation seeded by M018/P07's compression-tier parity work). Ships when first users arrive with Codex CLI or Cursor projects. Pre-launch dogfooding stays CC-only. Cursor brief authored 2026-06-06 at .orchestrator/proposals/M009-cursor-support.md — a capability audit of current (mid-2026) Cursor found the codebase's Cursor assumptions ~a year stale: Cursor now has headless cursor-agent dispatch (≈ the Codex codex run backend), Hooks v1.7 (beforeShellExecution ≈ CC PreToolUse shape-guard), and MCP elicitation + .cursor/commands/. Brief splits a Tier-A "honest degraded support" slice (~1–2 wk: real dispatch backend + hook port + command/rules split + fallbacks) from Tier-B full parity (~4–6 wk: MCP review gates + cost + byte-parity audit). Tier-A SHIPPED 2026-06-06 on branch m009-cursor-tier-a (9 commits; FR-1 dispatch backend + FR-2 JSON parse + FR-3 beforeShellExecution shape-guard + FR-4 commands/rules surface + FR-5 git pre-commit gate + FR-9 RUNTIME-ASSUMPTIONS rows; Q1 elicitation crux resolved live; suites 29/29 + 24/24 + 15/15 green). Record at .orchestrator/milestones/M009/M009-PROBE-FINDINGS-2026-06-06.md; build-status addendum in the brief. Tier-B remains demand-driven — promote via orchestrator:specify when a real Cursor user arrives.
• M023 (design layer, deferred post-launch) — orchestrator:design spawns N design-personality agents in parallel via conversus, each producing a DESIGN.md draft + working coded prototype; user picks side-by-side; renderer adapter shaped as MCP clients (runtime-agnostic). Originally slotted pre-launch because this repo has no internal UI to dogfood against; revised 2026-04-28 — better as a fast-follow once real users arrive with real UI projects, since pre-launch dogfooding would only exercise synthetic fixtures.
• M034 (interactive review gates, deferred post-launch) — first-class interactive-review stage between artifact authoring and SIGNOFF.md population. Decision-packet schema (P01) + interactive walkthrough consuming it (P02). Inherits commands/comments.md review-queue convention + CON-5/SC-5 invariant. auto-mode parity via defer / accept-with-audit / block policies declared in plan frontmatter. Demand-signal-driven — ships when a second downstream consumer hits the friction lakeledger M066/P01 surfaced 2026-04-28. Brief at .orchestrator/proposals/M034-interactive-review-gates.md.
• M036 (reference-corpus ingest, split 2026-05-01 into M036a pre-launch + M036b post-launch) — extends the knowledge layer with a reference/ chunk family for non-spec materials (regulatory, training, glossary), three new edge types (cites / derived_from / applies_to_field), [source:...] tag namespace, dispatch injection under a token-budget governor, and orchestrator-owned tiered extraction (Tier 0 manifest + binary preservation, Tier 1 deterministic shell adapters for PDF/DOCX/XLSX/MD, Tier 2 LLM-driven structured Markdown via M030 routing under conversus fidelity gate). Spec authored 2026-04-30, amended 2026-05-01 when PBJ Analyzer clarified it has no path-B extractor — extraction-ownership flip required (NG-3/4/5 inverted/narrowed); tier model added as core architecture; DOCX added; #Q-3 (versioning → supersede chain) and #Q-5 (fidelity gate → tiered) resolved at amendment. Roadmap restructured 2026-05-01 from 7 phases → 10 phases under M036a/M036b split.
  • M036a (pre-launch urgent, P00–P07, 8 phases) — closed 2026-05-02. Full pipeline live: Tier 0 manifest + binary preservation, Tier 1 PDF/DOCX/XLSX/MD adapters, Tier 2 LLM extraction via M030 routing under conversus fidelity gate, ingest+classifier, graph schema extension (cites/derived_from/applies_to_field + [source:*] tag namespace), dispatch injection with token-budget governor (SC-3/SC-7), idempotent re-extract+re-ingest with supersede chain mechanism (SC-5/SC-6/SC-13). Cross-phase regression spread P02 selective + P03/P04/P05/P06/P07 full pass-through. One follow-up before pilot: live-LLM smoke test against a real PBJ fixture (P03 has only been exercised against stubs).
  • M036b (post-launch fast-follow, P08–P09) — wiki projection (P08, blocked by M032 closure) + operator-facing scale UX (P09: REVIEW queue, change-over-time queries, supersede chain at scale). Demand-driven; ships when validator-pilot feedback surfaces concrete operator pain.
  • Brief at .orchestrator/proposals/M036-reference-corpus-ingest.md; roadmap at .orchestrator/milestones/M036/M036-ROADMAP.md; spec at specs/033-reference-corpus-ingest/spec.md. NO hard dependency on M013/M014 — those gates fire on spec-shape, not reference content. Hard dependencies for M036a P03: M030 (closed 2026-05-01) for Tier 2 model routing; conversus adapter (M011/P07, shipped) for Tier 2 fidelity gate.
• M010 (Managed Agents + Codex Cloud, deferred post-launch) — adds Anthropic Managed Agents as a hosted dispatch backend + Codex Cloud stub (proves abstraction). Net-new capability, not launch readiness; revised 2026-04-28 — explicitly aspirational, demand-driven.
• M038 (living documents, deferred post-launch) — framework-owned primitive for evolving rule docs / decision logs / audit docs that bind to code anchors with section-level granularity (LakeLedger MATT-RULES-AUDIT.md pattern, currently hand-rolled per-project as CON-2: audit-doc-same-change-set + per-phase verifier scripts). Scope: detection → registration → section-level binding (sidecar bindings file + optional inline HTML markers) → knowledge-graph integration (new living-doc/section node type + 4 edge types) → planner injection → verifier auto-generation → wiki review surface. Strong primitive overlap with M034 (decision-packet ↔ section-binding) and M040 (feedback/brief is a built-in living-doc type per M038 §9.8); paired demand-driven slot, absorption decision (M038 absorbs M034 / M034 absorbs M038 / sibling milestones with shared schema) deferred to queue-entry time. Smallest viable cut (~1 week): declare + sidecar + planner injection + audit CLI. Demand-signal-driven — ships when LakeLedger or a second downstream consumer signals concrete need. Brief at .orchestrator/proposals/M038-living-documents.md.
• M040 (ambient feedback loop, deferred post-launch) — three cohesive surfaces that turn the knowledge graph from query-only into ambient: (1) /orchestrator-brief scheduled daily/weekly synthesis (connections / drift signal / one question) reading execution-log + KNOWLEDGE.md + DECISIONS.md + active phase plans + inbox; (2) decision contradiction gate on every DECISIONS.md write via two-agent conversus pass (PASS / FLAG / BLOCK; BLOCKs route through commands/comments.md human-gated apply queue); (3) /orchestrator-capture friction-free inbox at .orchestrator/inbox/ with explicit promotion (/orchestrator-promote --to=mem|decision|task). Captured 2026-05-10 from README audit + ext'l knowledge-system adoption article ("a knowledge system without a return path is a graveyard with good folders"). Strong composition with M034 (decision-packet shape) + M038 (brief as living-doc type) + M039 (wiki rendering surface). Brief at .orchestrator/proposals/M040-ambient-feedback-loop.md.

Sequencing rationale (amended 2026-05-03 — see .orchestrator/proposals/launch-sequencing-amendment-2026-05-03.md for the full risk-ranking): M028 stabilizes autonomous runs (load-bearing for everything after); M030 makes runs cheap; M031 restores the knowledge-graph promise + lowers small-task adoption friction; M032 + M033 ship as a paired unit (M033/P05 calls into M032's --with-wiki gate, so build them with the integration live the whole time rather than sequentially); M033 includes a friendly-tester pass on the four init branches before lock (cold-start UX only resolves with warm bodies); M029 is launch polish; M035 is launch readiness (P00+P01 pre-launch dev-ergonomics, P02–P06 constitute the launch event — package-manager publishing in lockstep). Risk concentrates in M035-publishing blast radius and M033 cold-start UX, not in dependency order. M036a (closed 2026-05-02) is no longer a parallel workstream — only the pre-pilot live-LLM smoke test remains. Runtime expansion (M009/M010), design-layer work (M023), and M036b (post-launch wiki + scale UX) defer until post-launch when real-user signal informs prioritization.

Standalone constitution amendment (any time, single PR, no dependencies): inclusion-criteria gate for new principles + CONSTITUTION-LOG.md governance log + Principle XVI (Distribution Surface Integrity) + Principle I clarification (minimize total task tokens via efficient context delivery, not payload bytes). Brief at .orchestrator/proposals/constitution-amendment-inclusion-criteria.md.

Conversus integration stays as the M011/P07 reusable adapter — invoked from M030/M031 at opt-in gate points. See .orchestrator/proposals/README.md for full sequencing rationale, .orchestrator/DECISIONS.md D004–D016 for the historical D016 ordering, and .orchestrator/milestone-summary.md for milestone history.

Standalone Mode

The orchestrator operates standalone on Claude Code at launch, with Codex CLI / Cursor as aspirational fast-follows (M009 multi-runtime parity audit ships demand-driven post-launch when non-CC users arrive). M018/P07 has already proven runtime parity for the compression-tier zero-LLM path (CC / Codex CLI / Cursor byte-equality + T3 routing parity, see references/RUNTIME-ASSUMPTIONS.md); broader parity audit is M009's job. Auto-calibrated process intensity (Quick / Standard / Full) applies regardless of runtime. Key entry points:

• orchestrator:init (commands/init.md, scripts/lifecycle/init-project.sh) — first-run setup: detects project, probes capabilities, generates config + runtime-appropriate instruction file, installs skills. Completes in ~1s.
• scripts/engine/intensity-recommend.sh — given a task description + capability profile, recommends Quick/Standard/Full.
• scripts/dispatch/dispatch-interface.sh — uniform backend-agnostic dispatch (filename-routed to scripts/dispatch/adapters/backend/*.sh).
• scripts/state/resolve-root.sh — 4-rule state root resolver (ORCHESTRATOR_ROOT env → config → .orchestrator/ → default).
• packaging/bundle/ — installable unit consumed by packaging/install/install-{claude-code,codex,cursor}.sh.

All orchestrator runtime state lives at .orchestrator/ in this repo. The constitution lives at .orchestrator/memory/constitution.md.

Key Files

• commands/ — orchestrator command definitions (14 agent instruction documents)
• scripts/ — helper scripts organized by concern (state, dispatch, engine, verify, knowledge, lifecycle, migrate, diagnostics)
• templates/ — 24+ output templates + 1 config default
• references/ — 15 reference docs (architecture, engine, events, errors, hooks, recipes, routing, file formats, state machine, verification ladder, tier definitions, installation, provider convention, constitution walkthrough)
• docs/ — 5 user guides (getting started, recipe authoring, hook development, knowledge management, migrating from spec-kit)
• packaging/ — installable bundle + per-runtime installers
• tests/ — 7 test suites (334+ assertions)
• specs/001-orchestrator/spec.md — original feature specification
• .orchestrator/memory/constitution.md — 7 governing principles
• .orchestrator/KNOWLEDGE.md — consolidated patterns, decisions, lessons
• .orchestrator/milestone-summary.md — build summary + extension guide
• CHANGELOG.md — version history and audit remediation tracking

Architecture

This is a standalone orchestrator delivered as a runtime-specific skill bundle (Claude Code / Codex CLI / Cursor). It registers commands via packaging/install/install-<runtime>.sh, stores state at .orchestrator/, and operates with no runtime dependency on spec-kit.

Constitution Principles (governs all decisions)

1. Context Minimization
2. Evidence Before Claims
3. Design Before Code
4. Plans Assume Zero Context
5. Fresh Context Per Unit
6. State On Disk Is Truth
7. Knowledge Compounds

Read .orchestrator/memory/constitution.md for full definitions.

SDD Workflow

This project uses its own orchestrator workflow for development:

orchestrator:evaluate → orchestrator:discuss (Tier C) → orchestrator:roadmap → orchestrator:plan-phase → orchestrator:auto / orchestrator:dispatch → orchestrator:verify → orchestrator:consolidate.

See commands/ for each command's definition.

Commit Message Authoring

For multi-line commit messages, prefer git commit -F <message-file> with a message file authored via the Write tool. Do not use the inline-HEREDOC form git commit -m "$(cat <<'EOF' ... EOF)": the active M021 PreToolUse Bash shape-guard rejects it under AP-008 (heredoc-with-expansion) because the inline $(...) containing a heredoc is itself a compound substitution. The system-prompt-staged commit guidance recommends the inline-HEREDOC form, but it does not pass through the shape-guard; -F is the form that survives every dispatch path. Single-line messages can use -m "..." directly.

Active Technologies

• Markdown (command format) + Bash 3.2+ / POSIX sh (helper scripts), git (version control, worktree isolation), jq (optional, JSON parsing in scripts) (001-speckit-orchestrator)
• File-based state machine — YAML frontmatter + markdown body files, JSONL append-only logs, JSON lock files. All state at .orchestrator/ (001-speckit-orchestrator)