Skip to content

CLAUDE.md

Latest commit

 

History

History
105 lines (78 loc) · 20.4 KB

CLAUDE.md

File metadata and controls

105 lines (78 loc) · 20.4 KB
Raw

CLAUDE.md — code-oz

This file orients Claude Code sessions working on code-oz.

What this project is

code-oz is a standalone Bun + TypeScript CLI that boots an adaptive multi-agent software-delivery runtime over a hybrid phase-graph + agentic sub-orchestration spine. Hard SDLC gates between phases (file-based, schema-validated). Cross-family adversarial review. Non-technical-user intent elicitation at the front. Provider surface (v0.21.x alpha): Claude (Claude Code CLI subprocess), Codex (Codex CLI subprocess), xAI (direct HTTPS with XAI_API_KEY), Fake (built-in deterministic) are live. Gemini is a stub for transparency only (invoke() throws provider_gemini_not_yet_supported); OpenCode and Roo Code are future adapter candidates, not v0.1 implementations. The canonical provider matrix lives at docs/contracts/PROVIDERS.md § "Provider status (v0.1)".

Status: v0.21.2-alpha.0 is the current release-prep branch; latest published release is v0.21.1-alpha.0. v0.21.0 shipped M17 brownfield AUDIT runtime; v0.21.1 added fail-closed external-operator driving for tools such as Hermes/OpenClaw while keeping code-oz the gate authority; v0.21.2 truth-syncs release-readiness docs and prepares package/plugin/GUI surfaces after the Claude Code marketplace fixes (#45-#47). The release line supports curl, npm launcher, Homebrew, root Claude Code marketplace metadata, and the private code-oz-gui Next app. CHANGELOG.md, docs/RECEIPTS.md, and docs/RELEASE_READINESS.md are the current release-readiness surfaces. Live brownfield dogfood still requires provider credentials; Windows/Scoop, signing/notarization, signed checksums, SLSA provenance, live Gemini, OpenCode/Roo adapters, and GUI standalone packaging remain future work. PE-2 demand-gated; multi-cloud deferred to v0.2.

Product north star: code-oz is a repo-native agentic SDLC runtime (market category) framed internally as an AI software company (product metaphor). The thesis lives in docs/product/AI_SOFTWARE_COMPANY_THESIS.md: provider and model bias are real, so code-oz coordinates role-specialized agents through artifacts, evidence gates, debate, verification, and cross-family review instead of trusting one model's confidence. Category and metaphor revised 2026-04-30 after Codex pressure-test (docs/research/CODEX_RESPONSE_PRODUCT_THESIS.md, thread 019de031).

Where decisions live

  • docs/design/ROADMAP.md — full milestone plan, decision matrix, day-by-day PR plan
  • docs/product/AI_SOFTWARE_COMPANY_THESIS.md: product north star, market positioning, role model, and post-M10 company-roster direction
  • docs/adr/0001-mvp-option-e.md — MVP scope decision (Option E, spine-first end-to-end)
  • docs/design/SESSION_CYCLE.md — the empirical session cycle (boot → plan → implement → review → tag → handoff). Every milestone session follows it.
  • docs/design/CODEX_BRIEFING.md and docs/design/CODEX_RESPONSE.md — debate transcripts that produced the roadmap
  • docs/comparison/<NN>-<template>/ — per-template head-to-head comparisons against the influence library, each closed with a Codex round (e.g., 09-byterover-cli/SYNTHESIS.md produced rule 22)
  • docs/comparison/05-agent-skills/synthesis.md — round-2 borrow audit verdict (2026-05-10): four landing-plan commits in this series, Skills layer deferred with sharper trigger, doubt-driven shaped as risk-triggered pre-BUILD checkpoint for an M17+ design.

Non-negotiable rules (audit-derived)

  1. File-based gate signals only. Never parse LLM text output for pass/fail. Use state/GATE_<PHASE>_PASSED.json files validated by src/state/gates.ts schemas. (maestro lesson)

Gate-file writes are produced only by orchestrator-owned primitives in src/state/gates.ts / src/state/run.ts: phase-approval primitives (writeGate, approveGate, approveReviewTaskGate) for GATE_<PHASE>_PASSED.json, and intervention/control primitives (writeNeedsInterventionGate, writePauseGate, writeStopGate, all routed through writeControlGate) for NEEDS_INTERVENTION.json / PAUSE.json / STOP.json. These intervention writers are invoked by orchestrator-owned phase modules (src/phases/*.ts, src/providers/invoke.ts, src/worktree/load-or-create-run-worktree.ts) when a phase or wrapper refuses; they are part of the orchestrator surface, not external surfaces. MCP tool calls, hook invocations, and any future external integration surfaces cannot write gate files, canonical artifacts, or events.jsonl directly; only orchestrator-owned event-emission primitives append events. If a future external surface accepts write requests from clients, those requests are recorded as advisory request files under .code-oz/state/runs/<runId>/requests/<request-id>.json (same shape as NEEDS_INTERVENTION.json, a request the next phase preflight may consider) and never bypass gate validation; external consumers may read events and submit advisory requests, but they never own gate or event-log writes. Pinned 2026-05-10 from Mimir comparison (docs/comparison/11-mimir/SYNTHESIS.md § "C-MIMIR-1"). 2. Cross-family review at REVIEW gate. REVIEW agent must be a different provider family than BUILD. Pass file paths, not curated summaries. (ARIS lesson) 3. 3-source verification before any code. Spec + reference code + library docs. PLAN cannot pass without SOURCE_CHECK.md. (maestro lesson) 4. Opus default; warn on downgrade. claude-opus-4-8 is the primary model; downgrading requires explicit config. (maestro session-55 lesson) 5. Wave-based execution + grep verification between phases catches pattern blindness. 6. Hard cap on review loops: max 4 rounds, exit on score≥6 + verdict=ready. (ARIS) 7. Artifact contracts in plain Markdown (SPEC.md, PLAN.md, SOURCE_CHECK.md, BUILD_REPORT.md, VERIFY.md, REVIEW.md, AUDIT.md) — never JSON serialization for inter-phase handoffs. 8. FakeProvider runs the full lifecycle offline. Every spine test is deterministic and network-free. 9. Permission manifest required for any executable runner. Generalized 2026-05-10 from "any .ts escape hatch" to cover any executable (.ts, .py, .sh, native binaries, etc.) per session-06 borrow B2 (Codex thread 019e12ec, docs/comparison/06-codex/SYNTHESIS.md). Required manifest fields per executable: command (argv form), interpreter (bun / node / python / sh / explicit), cwd, file_roots (read/write/none per root), network (allow/deny + allowlist when allow), env (allowlist; no inheritance), secrets (allowlist), timeout (seconds), output_caps (stdout/stderr byte caps). Subagent prompts under skills/<name>/agents/ MUST import src/prompts/universal-rules.md first and cannot relax it. Default: no execution. 10. Cost budgets are config, not vibes. maxTurns, maxProviderCalls, maxTokensEstimate, maxReviewRounds, per-phase budgets in .code-oz/config.yaml. 11. Provider failures become actionable NEEDS_INTERVENTION.json, never opaque SDK stack traces. 12. Resume is a v0.1 feature. runId, idempotent gate writes, code-oz resume. Terminal death after PLAN must not restart DEFINE. 13. Privacy by default. .code-ozignore, secret redaction, file-size caps, "files sent to provider" preview per phase. Agents receive explicit file manifests, never silent recursive repo context. 14. Brownfield AUDIT has its own artifact. Never treat existing code as a blank canvas. 15. Epistemic sidecars at phase gates. Every phase contract that produces a primary artifact must include the Scientist tail defined in docs/contracts/SCIENTIST.md; gate preflight validates HYPOTHESES.md and OPEN_QUESTIONS.md and blocks overdue open questions before writing GATE_<PHASE>_PASSED.json. (synthesis round, 2026-04-30) 16. Universal anti-slop rules ship inside every persona prompt. Every persona's system prompt imports the universal rule sheet from src/prompts/universal-rules.md (the 21-item list — 10 prohibitions + 11 affirmations — defined in docs/research/02-llm-failure-research.md). Personas may add their own rules below; they may not relax the universal ones.

Personas are hand-authored or rendered from deterministic templates only. LLM-generated persona prompts are forbidden because the universal-rules import is a mechanical text concatenation that a generation pass cannot be trusted to preserve. A deterministic template renderer that mechanically imports universal-rules.md and fills role-specific blanks is acceptable when the persona roster grows past current six; an LLM persona-generator (for example, Mimir's Agentinator pattern) is not. Pinned 2026-05-10 from Mimir comparison (docs/comparison/11-mimir/SYNTHESIS.md § "C-MIMIR-4"). 17. The maestro discipline is named and authoritative. The rule-checker role + 9-family bug map + adversarial-review skills + four-layer file-system memory are documented in docs/research/01-maestro-rule-checker.md. Personas reference it; the orchestrator implements its skills; the dossier is the spec. Updates land as commits on the dossier with a top-of-file "## Update " annotation. 18. Codebase context retrieval has its own permission scope. Agentic search is a tool_use.repo_context sub-scope on agent permissions, defined in docs/contracts/REPO_CONTEXT.md. Search results are audited via repo_context_searched events; selected paths enter the next invocation's ProviderRequest.files, never the search invocation's hidden context. The maestro's repo-search-before-write skill is the consumer; the search backend is the new piece. Network access is denied for repo_context tools. 19. Run-level budget enforcement is mandatory, not advisory. Cumulative caps live under budgets.global (single namespace): maxTurns, maxProviderCalls, maxTokensEstimate, maxWallTimeMinutes, optional priceTable for dollar telemetry. The wrapper's assertWithinBudget reads cumulative spend from events.jsonl per-call (no parallel state). Soft warnings fire at softWarnAtRatio (default 0.75); hard kills at 1.0. NEEDS_INTERVENTION carries the actionable suggestion when budget triggers a kill. 20. One new authority boundary per milestone. Each milestone may introduce exactly one new gate or capability domain. M7 = worktree-isolation + BUILD artifact authority. M8 = VERIFY evidence authority + restart-on-fail policy. M9 = cross-family REVIEW authority. M10 = Debate runtime authority (requestDebate() primitive). Post-M10 sequence (locked 2026-04-30 after thesis pressure-test, docs/research/CODEX_RESPONSE_PRODUCT_THESIS.md, thread 019de031): M11 = Provider capability contract; M12 = Company roster (shipped roles only); M13 = Role-cost policy under budgets.global; M14 = Reviewer panel v1 (first simultaneous-provider surface); M15 = Debate-policy scheduler v1 (single-opponent only). M16+ deferred (Researcher phase-tail, parallel builder candidates, multi-opponent debate) until measurable need. The rule generalizes the empirical M2-M6 cadence and prevents authority-creep that masks bugs. Empirically validated 2026-04-30 when the pre-debate M7 row bundled five authorities into one milestone (mutation testing + iterative build loop + three new phases + Scientist tails + Prompter experiment) — exactly the failure mode the cross-model peer review process is designed to prevent. (M7-M10 shape debate, thread 019ddea0, docs/research/CODEX_RESPONSE_M7_M10_SHAPE.md) 21. No new parallel-provider surface lands without a measurable risk-reduction effect. Multi-agent / multi-provider features (Reviewer panels, parallel builder candidates, multi-opponent debate, Researcher fan-out) are added only when their risk-reduction effect is measurable in events.jsonl against the single-provider baseline. The Agentless caution (https://arxiv.org/abs/2407.01489) is product policy, not just research context: simpler workflows beat complex agent systems unless complexity earns its keep. Pinned 2026-04-30 from product thesis pressure-test (docs/research/CODEX_RESPONSE_PRODUCT_THESIS.md, thread 019de031). 22. Consumer-first design and proof-first implementation. (a) Outside-In feature design. Every new code path starts from a concrete consumer (CLI subcommand, agent skill, persona prompt, runtime fire path). Define the minimal interface the consumer requires; implement the service to fulfill it; extract entities only when shared structure emerges across consumers. Reviewing or planning that defines entities, types, or store interfaces before any consumer exists is Inside-Out and must be flagged. (b) Strict TDD ordering for behavior changes. For any behavior change, the failing test is written first, run to confirm it fails for the right reason, then minimal implementation lands, then tests run again to confirm green, then refactor. If implementation lands without a prior failing test, STOP and write the test first. The detailed RED-first sequence lives in src/agents/defaults/builder.md for execution; rule 22 is the structural non-negotiable. Adopted 2026-05-10 from byterover-cli (docs/comparison/09-byterover-cli/); Codex fix-first round consolidated borrows B1+B4 into one rule to avoid rule-list bloat (thread 019e12ec). 23. The --effort flag scales budgets only, never assurance. The flag may multiply scalable budgets.global caps, budgets.global.byRole rows, and budgets.perPhase.<phase> rows. It MUST NOT change maxReviewRounds, panel slot count, mutation gate threshold, BUILD restart attempt cap, debate-policy thresholds (M15), or AUDIT strictness for brownfield runs — until an assurance-aware effort contract (deferred B1b) amends this rule with its own milestone-gated invariants. The flag emits effort_envelope_applied immediately after run_started (event order locked at position 2, between run_started and phase_entered; see docs/design/B1A_EFFORT_FLAG.md § "Event order lock"), recording both the original and the effective envelope (each shaped as CodeOzConfig['budgets']). Active-run continuations replay the recorded effectiveBudgets from this event directly (Codex R0 B1 closure — replay does NOT re-apply applyEffort to the currently-loaded config, so editing .code-oz/config.yaml mid-run cannot change the run's envelope); mismatched --effort on an active run is rejected. The rest of the run reads only from the effective envelope.

Architecture locks

  • Stack: Bun + TypeScript, native single-file binary via bun build --compile.
  • Distribution (W3+): curl installer + npm launcher + Homebrew for macOS/Linux. Windows/Scoop is future work.
  • File format: Markdown + YAML frontmatter (agent-skills schema, extended with type / phase / provider / modelPolicy / permissions). Optional sibling .ts for hooks/MCP tools/runners.
  • Phase taxonomy: DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP (greenfield) and AUDIT → PLAN → BUILD → VERIFY → REVIEW → SHIP (brownfield).
  • State model: typed FSM + state/events.jsonl event log + schema-validated gate files. No SQLite v0.1.
  • Cross-provider primitive: narrow requestReview({ reviewer, files, question }) only at REVIEW gate. Broad consult() is v0.3.

Influence library

The templates/ collection in ~/Projects/agents/templates/ is the influence library. Patterns are borrowed; no code dependencies, no submodules, no copy-paste. Audited templates and what they contributed:

Template Pattern
agent-skills Skill frontmatter format + DEFINE→SHIP phase taxonomy + Common Rationalizations table
opencode bun build --compile distribution + MCP host/client + permission system
Archon IAgentProvider interface + worktree-per-run isolation
pi-mono Streaming event model + multi-provider abstraction
maestro File-based gate signals + 3-source verification + Opus-default policy
Auto-claude-code-research-in-sleep Cross-family review + Reviewer Memory + 4-round-cap loop + plain-Markdown artifact contracts
claude-code Plugin format + hook event names + filesystem discovery
byterover-cli Consumer-first design + RED-first TDD ordering (rule 22); parentTaskId fan-out cost rollup

Working in this repo

  1. Run all commands from the repo root. bun install, bun test, bun run dev <command>, bun run build:binary.
  2. Branching is trunk-based (Option A, locked 2026-05-29). main is the protected trunk and the only long-lived branch. Every change lands via a short-lived branch -> PR -> green CI -> squash-merge -> head branch auto-deletes (merge-commit and rebase-merge are disabled). Prefixes: feat/, fix/, refactor/, test/, docs/, chore/, with a kebab-case slug after the slash, optionally issue-scoped (fix/123-worktree-reset). One branch = one PR = one squashed conventional commit = one concern; branch from latest main (git fetch origin && git switch -c feat/<slug> origin/main), never from another topic branch; never push worktree-* scratch branches. Releases are annotated SemVer tags (vX.Y.Z-alpha.N) on a green main, cut behind a chore/release-* PR. main is protected for everyone including admins (required bun test checks, linear history, no force-push or deletion, PR-before-merge). Full contract: CONTRIBUTING.md § "Branching and merge workflow".
  3. Tests must run offline. Spine tests use FakeProvider. Live-provider tests are opt-in only and gated behind env flags.
  4. No emojis in code or commit messages. No "Co-Authored-By: Claude" footers unless asked.
  5. Never push to GitHub without explicit user approval. Local commits are fine.
  6. Skills available in this repo: any skill from the user's global skill set applies. The non-negotiable rules above override anything that conflicts.

Cross-model peer review (durable rule)

This project is high-stakes. Single-model output has blind spots; cross-family review structurally mitigates them. The rule fires on every milestone:

  1. Codex debate at planning convergence. Before starting implementation of any milestone (M2, M3, ...), run a Codex debate round on the milestone scope: write a structured CODEX_BRIEFING.md (goal, constraints, acceptance, the recommended plan, debate prompts), invoke mcp__plugin_agent-codex_codex-native__codex with gpt-5.5 xhigh and sandbox: read-only, capture CODEX_RESPONSE.md, and synthesize before any code lands. The user's preference: never present "ready to proceed" without the debate.

  2. Codex review at implementation completion. Before tagging or pushing any milestone, run a Codex review on the latest commit. Codex returns one of push / fix-first / debate-required. Block-push and block-next-milestone severity findings get addressed in a follow-up commit (never amend) before the milestone is closed.

  3. Codex's verdict is data, not authority. Weigh disagreement, sanity-check agreement, push back when warranted. The point is structural review, not deference.

  4. Codex model fallback. Globally configured gpt-5.5 at xhigh effort. The gpt-5.5-codex and gpt-5.1-codex-max variants do NOT work on Ozzy's ChatGPT-account auth — fall back to gpt-5.5 if they fail. Reasoning effort xhigh is set in ~/.codex/config.toml defaults; pass {model_reasoning_effort: "xhigh"} in the config override only when overriding.

This rule was empirically validated 2026-04-29: Codex's planning-convergence debate flipped the MVP from Option C to Option E (spine-first end-to-end), and Codex's M1 implementation review caught five real issues including a doc/code lie in the scaffold (.code-oz/.gitignore promised but not written), --force semantics that were the "dangerous middle," and brownfield detection that ignored .git despite the locked rule. See docs/design/CODEX_RESPONSE.md for the original debate.

Quick references

  • Run dev CLI: bun run dev init, bun run dev run, bun run dev doctor
  • Run tests: bun test (offline, full suite) or bun test --watch
  • Build native binary: bun run build:binary → dist/code-oz
  • Type-check: bun run typecheck