Create Project Summary Stats

claude-code-config

[](https://github.com/fxmartin/claude-code-config/actions/workflows/ci.yml) [](https://github.com/fxmartin/claude-code-config/actions/workflows/release.yml) [](https://github.com/fxmartin/claude-code-config/releases/latest)

**In one sentence:** give it a plain-English idea, and it plans, builds, tests, reviews, and merges working software for you — running a whole AI development team end-to-end, with a human stepping in only for the calls that matter.

**What it does, in plain terms.** Shipping software normally means a team moving an idea through a sequence of stages: nail down the requirements, break the work into tasks, write the code, write the tests, check coverage, review each other's work, and only then merge. This project automates that entire sequence. You describe what you want; it runs each stage and refuses to let work advance until it clears the same quality bars a good team insists on — tests green, coverage met, an independent code review passed.

**Why "a harness of harnesses".** It doesn't write the code itself — it *directs* AI coding agents, and those agents are swappable: the same pipeline runs on Anthropic's **Claude** or OpenAI's **Codex** (or a mix, one engine per stage). The framework is the conductor; the AI agents are the musicians. That's the harness of harnesses — one control layer driving interchangeable AI engines through the full lifecycle, so you're never locked to a single vendor.

**What keeps it trustworthy.** Autonomy without controls is just a fast way to make a mess. So every handoff between stages is validated against a strict contract, every run is checkpointed step-by-step (a crash or a closed laptop resumes cleanly), risky changes — CI, install scripts, security-sensitive files — are held for explicit human approval (enforced on GitHub; not yet on GitLab), and long runs ping you on Telegram. The point isn't "AI writes code" — it's a **controlled, auditable, autonomous SDLC** you can leave running and trust the result.

**Where it stands.** As of **2.x** the team workflow is live on **both forges**. Every story is mirrored to a shared issue board — GitHub or GitLab — as the single source of truth, with a portfolio dashboard showing status and owner across the whole backlog (Epic-22). The build pipeline itself runs against GitLab company repos too: it opens Merge Requests, gates the merge on GitLab CI, reviews via `glab mr diff`, and the live dashboard is forge-agnostic (Epic-23) — though the high-risk approval gate is enforced only on GitHub so far; its GitLab port is still open. Several developers, and their autonomous runs, work the same backlog **in parallel and jointly** instead of in separate silos. Still ahead: continuous ready-queue scheduling that retires the cohort barrier (Epic-24) and data-driven token/performance optimization (Epic-27).

---

A complete, opinionated Claude Code configuration: agents, skills, slash commands, MCP servers, hooks, and observability — engineered to take an idea from **one-line concept to merged PR without a human in the loop**.

This is the harness behind a multi-agent AGILE pipeline with parallel worktree execution, automatic bug triage, and Telegram notifications for monitoring long-running runs away from the machine.

The harness ships as **two mirror plugins** — `autonomous-sdlc` for Claude Code (in this repo at `plugins/autonomous-sdlc/`) and `autonomous-sdlc` for Codex (in the sibling [`nix-install`](https://github.com/fxmartin/nix-install) repo). Same plugin name, same pipeline shape, same skill IDs — so the SDLC workflow is portable across both runtimes. On Claude Code the plugin's skills surface as bare slash-commands (`/brainstorm`, `/create-story`, etc.) labelled `(autonomous-sdlc)` in the autocomplete; on Codex they're invoked as `Use autonomous-sdlc `.

We also use the Codex mirror as an automated adversarial review layer for Claude Code work. Claude Code remains the primary builder in this harness; Codex runs the same `autonomous-sdlc` plugin from the sibling repo to inspect Claude-produced changes, file high-signal issues, and challenge implementation quality from an independent runtime before work is considered done. Beyond review, Codex can now run the **build pipeline itself** — the controller dispatches each stage to a pluggable *agent harness*, so a repo can build entirely on Codex (or any mix). See [Cross-harness builds](#cross-harness-builds--run-the-pipeline-on-claude-or-codex-epic-2021).

**Contents:** [What it achieves](#what-this-harness-achieves) · [The workflow](#the-workflow-in-five-phases) · [The `sdlc` controller](#the-sdlc-controller-epic-07) · [Cross-harness builds](#cross-harness-builds--run-the-pipeline-on-claude-or-codex-epic-2021) · [Dashboard](#observability--the-live-dashboard) · [Why it works](#why-it-works) · [The gate stack](#the-gate-stack) · [Telegram](#telegram-notifications) · [Hardware envelope](#hardware-envelope) · [What's in the repo](#whats-in-the-repo) · [Install](#install) · [Reference](#reference-material)

---

What this harness achieves

 idea ─▶ /project-init ─▶ git repo + GitHub remote + labels + CLAUDE.md + PROJECT-SEED.md
         │
         ▼
     /brainstorm ─▶ REQUIREMENTS.md  (seed-aware: skips what /project-init already answered)
         │
         ▼
     /generate-epics ─▶ STORIES.md + epic-NN-*.md + NFRs
         │
         ▼
     /build-stories (parallel, autonomous)
         │  ├─ Discovery agent → dependency cohorts
         │  ├─ Build agents   (×5, worktree-isolated, TDD)
         │  ├─ Coverage gate  (×5, enforces 90%+)
         │  ├─ Review agent   (×5, senior-code-reviewer)
         │  └─ Merge agent    (sequential, rebase-before-merge)
         │      └─ Bugfix loop on failure (classify → fix → retry ×2)
         ▼
     /design-e2e · /execute-e2e-tests (Playwright, run at epic boundaries)
         │
         ▼
     /project-review · /coverage · /create-project-summary-stats

Every phase emits structured events to the ledger and mirrors milestones to Telegram so long-running runs can be monitored away from the machine. The pipeline is forge-agnostic: on GitHub it opens PRs and gates on `gh pr checks`; on GitLab it opens MRs and gates on the GitLab CI pipeline (see [`docs/gitlab-adoption.md`](docs/gitlab-adoption.md)).

---

The workflow, in five phases

Phase 0 — Bootstrap (`/project-init`)

A lightweight bootstrapper for a brand-new repo. Turns an empty directory into a project the rest of the pipeline can consume — no more, no less.

Pre-flight checks gate the run: empty directory (dotfiles allowed), `gh` authenticated, no existing `.git/`. Then a **5-question interactive discovery** (objective, tech stack, architecture style, repo visibility, catch-all) — deliberately narrow. Database, testing, CI/CD, and deployment questions are **not** asked here; those belong to `/brainstorm`.

Output:

• git init + first commit
• GitHub remote created via gh repo create (public or private per your answer)
• 26 standard labels applied (bug, enhancement, priority:, epic:, etc.) plus any project-specific ones
• .gitignore tailored to the detected tech stack
• CLAUDE.md — lightweight scaffold with placeholders for sections /brainstorm will fill in later (testing strategy, CI/CD, DB, deployment)
• PROJECT-SEED.md — structured handoff file that /brainstorm detects and reads to skip redundant questions

The skill closes by suggesting `/brainstorm` as the next step. If you already have a repo, skip Phase 0 — `/brainstorm` runs fine without a seed, just asks the full 8-question set from scratch.

Phase 1 — Discovery (`/brainstorm`)

A Senior PM persona conducts a structured 8-question interview covering problem space, personas, success metrics, capabilities, scope boundaries, technical constraints, priority, and acceptance criteria. Output: `REQUIREMENTS.md`. If `PROJECT-SEED.md` exists (from `/project-init`), the interview skips questions already answered (objective, stack, architecture) and drills deeper into product/market fit — requirements, user problems, competitive landscape, success metrics. After the interview, `CLAUDE.md` is updated with any newly determined sections (testing, CI/CD, database, deployment).

Phase 2 — Planning (`/generate-epics`, `/create-epic`)

Transforms `REQUIREMENTS.md` into a modular AGILE structure:

• STORIES.md — master overview
• docs/stories/epic-NN-.md — INVEST-compliant user stories in {Epic}.{Feature}-{NNN} format
• docs/stories/non-functional-requirements.md — perf, security, reliability targets

`/create-epic` lets you add more epics interactively without redoing discovery.

Phase 3 — Build

Two paths depending on how much control you want:

Mode	Command	When to use
Controlled	/resume-build-agents	One story at a time, visible agent selection, manual PR decisions
Autonomous	/build-stories [all|resume|epic-NN] [--sequential]	Full batch — parses the story graph, schedules cohorts, runs until done
Issue-driven	/fix-issue	Controller-backed (sdlc fix): investigate → build → coverage → review → optional E2E warn-gate → merge → summary (+ batch doc-update), with auto-classified bugfix retries

Harness support: cross-harness vs Claude-only

`/build-stories` and `/fix-issue` are both **thin wrappers** that shell out to the `sdlc` controller (issue #436 migrated `/fix-issue` off in-process orchestration), so their roles run through the controller's dispatch seam. `/build-stories` roles can be routed to any registered harness (`--harness build=claude,review=codex,…`). `/fix-issue` stays **Claude-only** by policy — `sdlc fix` exposes no `--harness` flag yet — and `/resume-build-agents` stays Claude-only because it still spawns its sub-agents **in-process** with the Claude Code `Agent` tool (`subagent_type` / `isolation="worktree"`), which has no CLI-harness equivalent. The boundary is documented in [`docs/controller-architecture.md`](docs/controller-architecture.md#the-in-process-agent-boundary-story-206-002) and enforced by `sdlc/portability.py`.

Skill	Dispatch mechanism	Harness support
build-stories	controller dispatch seam	Any registry harness
fix-issue	controller dispatch seam (sdlc fix)	Claude only (by policy)
resume-build-agents	in-process Agent tool	Claude only

The autonomous path: how `/build-stories` actually runs

The skill is a **thin dispatcher** — argument parsing, control flow, and structured-result parsing only. All heavy lifting is delegated to sub-agents, which preserves the orchestrator's context across 20+ story builds.

1. **Discovery agent** parses every epic file, resolves the dependency graph, topologically sorts it, and returns a `QUEUE_JSON` build queue.

2. **Cohort scheduler** groups stories whose dependencies are all complete into parallel cohorts (Cohort 1 = no deps; Cohort N = deps all in prior cohorts).

3. Each cohort runs through **4 stages**:

   Cohort N:
     Stage 1: [build A, B, C, D, E]     ← parallel, each in own git worktree (TDD)
     Stage 2: [coverage A, B, C, D, E]  ← parallel, adds tests to hit 90%+
     Stage 3: [review A, B, C, D, E]    ← parallel, senior-code-reviewer
     Stage 4: [merge A → B → C → D → E] ← sequential, rebase-before-merge

4. **Worktree isolation** (via the Agent tool's `isolation: "worktree"` flag) gives each concurrent agent a full, isolated checkout. No file-conflict races between agents working on overlapping areas of the codebase.

5. **Bugfix loop** — if any stage fails, a Bugfix Agent classifies the failure as `CODE_BUG` / `TEST_BUG` / `ENV_ISSUE`, files a GitHub issue, auto-fixes, and retries (max 2 attempts). Failed stories are marked `FAILED`; their dependents become `BLOCKED` in subsequent cohorts.

6. **E2E gate** at epic boundaries runs Playwright tests — part of the legacy skill pipeline; the `sdlc` controller does not dispatch an E2E stage yet, so run `/execute-e2e-tests` separately.

7. **Summary agent** emits the run's metrics and a merged-PR manifest.

Progress is persisted in a **SQLite state ledger** (`.sdlc-state.db`) with a human-readable markdown view generated on demand. Legacy `docs/stories/.build-progress.md` is kept as a fallback view. Status values: `DONE` / `IN_PROGRESS` / `FAILED` / `SKIPPED` / `PENDING`. Any run is resumable from the last completed stage.

The `sdlc` controller (Epic-07)

The `build-stories` skill is now a **thin wrapper** — all orchestration logic lives in a deterministic Python CLI (`sdlc`) rather than in an LLM interpreting a markdown playbook. The controller owns the state machine, validates every agent return against a JSON-schema contract, and surfaces malformed responses as actionable errors before the next stage runs.

Install

# Deploy both artifacts after a `git pull` — controller CLI + plugin, one version:
./scripts/deploy.sh

# Controller only — bootstraps uv if needed, then installs the CLI:
./scripts/install-controller.sh

# Or directly if you already have uv:
cd controller && uv tool install .

The controller CLI and the `autonomous-sdlc` plugin ship from this repo on the same version, but install through separate mechanisms (`uv tool install` and `claude plugin update`) — a `git pull` moves **neither** pointer. Updating only one leaves the plugin's skills silently driving a controller they no longer match, so prefer `./scripts/deploy.sh`, which converges both (and aborts in preflight if `claude` isn't on `PATH`; pass `--controller-only` on a box without Claude Code). The plugin half needs a Claude Code restart to take effect.

Key subcommands

Command	Purpose
sdlc build [scope] [--dry-run] [--auto] [--harness role=name] [--concurrency=N]	Run the full build-stories orchestration
sdlc resume	Resume an interrupted build from the ledger state
sdlc status · sdlc state	Run status and stage progress · inspect the persisted state machine
sdlc dashboard --open	Live multi-run browser dashboard (see Observability)
sdlc issues init · sdlc issues assign	Backfill the GitHub/GitLab issue board (one issue per story) · assign a story or epic to a host user. During a build, each story's issue updates live (a status: label + comment as it moves building → in-review → merging) and auto-closes on merge via its Closes #N link
sdlc doctor [--gitlab]	Health-check install, ledger, config, and forge prerequisites
sdlc clean · sdlc repair · sdlc rollback · sdlc reconcile	Workspace GC · ledger repair · checkpoint unwind · terminal-status reconciliation vs origin/main
sdlc usage-reconcile [--all]	Backfill per-stage token/cost usage from the session logs and score ledger-vs-logs agreement (sdlc doctor reports the rate)
sdlc model-backfill [--all]	Backfill per-stage model attribution (stages.model) from the session logs; unrecoverable rows are counted, never coerced (sdlc doctor reports the coverage)
sdlc predict-quality [run] [--json]	Score the per-story predictions sdlc build --predict recorded against their reconciled actuals — median absolute token error + rework calibration, each with its sample size
sdlc sast · sdlc depscan · sdlc supplychain	Classify SAST/dependency scan reports · scan hooks/skills/MCP/settings for dangerous patterns — all exit non-zero on BLOCK for CI gating
sdlc typecheck	Gate a mypy report against controller/.mypy-baseline.json — new type violations BLOCK, the known backlog does not. Driven by scripts/run-type-check.sh; ladder documented in `docs/python-best-practices.md`
sdlc eval · sdlc eval-compare · sdlc eval-baseline	Agent-output evaluation harness (A/B, regression baselines)
sdlc validate	Validate an agent response against its JSON schema
sdlc sync-check	Verify shared-skills parity between repos

`sdlc build` accepts the same arguments as `/build-stories` — the skill simply shells out to it. Migration is invisible to end users.

Agent I/O contracts

Every agent the orchestrator dispatches must return a JSON object fenced with `<<>>` ... `<<>>` markers matching one of five published schemas (build, coverage, review, merge, bugfix). A response that fails schema validation is treated as a build failure and routed to the bugfix loop — it never silently propagates bad data downstream. Full schema reference: [`docs/contracts.md`](docs/contracts.md).

See [`docs/controller-architecture.md`](docs/controller-architecture.md) for the module map, state-machine diagram, and retry semantics. The runtime decision is recorded in [`docs/adr/001-controller-runtime.md`](docs/adr/001-controller-runtime.md) (Python + uv + Typer + Pydantic).

---

Cross-harness builds — run the pipeline on Claude *or* Codex (Epic-20/21)

The build is split into two **independent** layers, so either can be Claude or Codex:

• Driver — what launches a run: the Claude /build-stories skill, the Codex build-stories skill, or the sdlc CLI directly. All three call the same controller — there is no runtime-specific orchestration, only one engine.
• Agent harness — the agent CLI the controller dispatches each pipeline stage (build, coverage, review, merge) to: claude (claude -p, the default) or codex (codex exec, via scripts/codex-build-adapter.sh). A harness is a config + wrapper entry in `controller/src/sdlc/config/harnesses.yaml` — adding one is a config change, never a Python change.

The two axes are orthogonal: you can drive from Claude while the *workers* run on Codex, or any other combination. The controller ships its harness registry **inside the installed wheel**, so routing works from the PATH-installed `sdlc` in any repo — no source checkout required.

**Activating a harness** — three layers, highest precedence first:

How	Scope	Notes
sdlc build … --harness build=codex,review=codex	one run	per-role; qa aliases coverage
.sdlc-harness.yaml at the repo root	per repo	recommended — survives controller redeploys
default: in harnesses.yaml	the installed controller	a uv tool install --force overwrites it back to the shipped default, so use the repo file for a durable switch

Precedence is **flag > repo file > registry `default:` > built-in `claude`**. A minimal Codex-only repo:

# /.sdlc-harness.yaml
harness:
  default: codex          # every role → codex; omit it to keep claude and remap only some roles

**Codex prerequisites** (one-time):

codex login                                              # workers run headless — no mid-run login
./install.sh --core                                      # symlinks the codex/qwen adapters onto PATH
export HARNESS_AGENT_CMD="codex exec --dangerously-bypass-approvals-and-sandbox"

Run on the **host path** — do *not* combine with the controller's `--sandbox` flag (that runs a Claude-only, no-egress container; a Codex worker needs the network for its `gh` push/PR calls). Codex declares no parallelism, so a Codex-routed cohort runs serially with a logged warning rather than failing. Full guide — capability flags, output parsers, per-stage model routing, and how to add a new harness (Qwen, OpenCode, Gemini…): [`docs/harness-adapters.md`](docs/harness-adapters.md).

---

Phase 4 — Quality & Intelligence

After build, the harness can audit itself:

Command	Purpose
/coverage	Fill coverage gaps to 100%
/design-e2e	Generate Playwright E2E tests from acceptance criteria
/execute-e2e-tests	Run the E2E suite
/project-review	Full quality audit with scoring
/create-project-summary-stats	Metrics, retrospective, velocity
/update-estimated-time-spent	Dev velocity tracking
/create-user-documentation	Production-ready end-user docs
/update-progress · /sync-progress	Reconcile story status across files

For adversarial review of Claude Code output, run the Codex mirror against the same repository after Claude finishes a build or fix. The preferred path is the Codex `autonomous-sdlc` plugin's review-oriented skills (`project-review`, `roast`, `coverage`, or `create-issue`) so findings come back as actionable issues rather than vague commentary.

The full workflow is documented end-to-end in [`WORKFLOW-v2.md`](WORKFLOW-v2.md).

---

Observability — the live dashboard

Autonomous runs are no longer a black box. `sdlc dashboard` serves a single browser pane that watches every run as it happens — across every repo on the machine — with no manual reload.

sdlc dashboard --open          # serve, and open it in the browser

It binds to **http://127.0.0.1:8787** by default (localhost-only).

**What it shows**

• Multi-run sidebar — every live and past run, each with its status, scope, done/total story count, duration, tokens, and cost. Click any run to focus it.
• Run header — run id, status, scope and mode (e.g. epic-17 · parallel), elapsed time, the preflight/QA-gate/coverage config, and live token (in / out / cache) and cost accounting.
• Repo-health panel — open/closed issues, open/closed PRs (or GitLab MRs), and the latest default-branch CI/pipeline status, refreshed every 30 seconds. Forge-agnostic: a GitHub run shows GitHub health via gh, a GitLab run shows GitLab health via glab.
• Dependency DAG — the cohort plan as wave columns, so you can see at a glance which stories are scheduled to run in parallel and what blocks what.
• Per-story stage table — a row per story across the four stages (build · QA · review · merge) plus PR number, tokens, and duration. Each story exposes a "view session" link that opens its full agent transcript in a modal.
• Events log — the run's ledger events (errors, warnings, milestones) in chronological order.

**One pane, every repo.** Launched without `--db`, the dashboard reads the host-level run registry (`~/.sdlc/registry.json`) and discovers runs across all your repos; each is still backed by its own per-repo ledger, so there is no cross-run data bleed. Point it at a single run's ledger with `--db ` to scope it to one repo.

**Live, not polled-by-hand.** Updates stream over Server-Sent Events driven by a ~1 s ledger change-token, with a 2.5 s polling fallback if the browser can't hold an SSE connection; the elapsed timer ticks every second so an in-flight run always reads true.

Flag	Effect
--open	Open the dashboard in a browser on start
--port N	Bind port (default 8787)
--host H	Bind host (default 127.0.0.1, localhost-only)
--run	Focus a specific run (default: the most recent)
--db	Single-ledger mode (default: host registry, all repos)
--restart / --stop	Restart, or stop, a dashboard already running on this host:port

---

Why it works

• Thin-dispatcher orchestrators — skills like /build-stories and /fix-issue carry only control flow; heavy I/O and reasoning are delegated to sub-agents so the orchestrator's context window stays lean across tens of stories.
• Specialist agents per story type — the Build stage picks the right agent from the roster (backend-typescript-architect, python-backend-engineer, ui-engineer, bash-zsh-macos-engineer, podman-container-architect, qa-engineer) based on the story's tech stack.
• Mandatory senior-code-reviewer — every PR flows through an architecture/security review before merge. Not a nice-to-have, not optional.
• TDD-first — tests are written before implementation; the coverage gate fails the story when the coverage agent reports the suite below the threshold (default 90%).
• Worktree isolation — five agents can genuinely run in parallel without clobbering each other's files, because each has its own checkout.
• Sequential merge with rebase — Stage 4 serializes merges with rebase-before-merge, preventing the race conditions that kill naive parallel-merge setups.
• Bugfix loop is a peer, not a god — classifies failures, creates a GitHub issue (so there's an audit trail), fixes, retries. Two strikes and the story is marked FAILED rather than loop forever.
• Verifiable goals — every skill enforces strong success criteria per step (test green, coverage ≥ N, review approved, merge clean), which is what makes unattended loops safe.
• Process discipline inside each agent's turn — bugfix agents must state a root cause before fixing (schema-enforced in the bugfix contract), review findings are verified and disputable claims rather than orders, reviewers treat the implementer's self-report as unverified, and red/green pressure-tests prove these discipline prompts actually change agent behavior (Epic-26, patterns adapted from obra/superpowers).

---

The gate stack

Coverage alone is not a quality bar — a 90%-covered diff can still ship an injection bug or a needlessly clever abstraction. What follows is the honest map of what actually blocks a story in a default `sdlc build` today, versus what ships as an opt-in or standalone mechanism.

**Enforced on every story by the controller:**

Check	How it's enforced	Docs
Build	The story fails unless the build agent's schema-validated response reports SUCCESS; failures route to the bugfix loop (root-cause-first, max 2 retries)	`docs/contracts.md`
Coverage	A dedicated agent fills gaps against the run's threshold (default 90%, --coverage-threshold=N); the story fails on a reported FAIL. Agent-reported — opt out with --skip-coverage	—
Senior code review	The story does not advance unless the reviewer returns APPROVED; the reviewer is instructed to treat the implementer's self-report as unverified claims (Epic-26)	—
CI gate at merge	Before merging, the controller polls the PR/MR's CI status and refuses to merge on failure (skipped when the repo has no CI mapped). This repo's CI carries the security jobs: gitleaks secret detection (fails on any finding) and a supply-chain scan	`docs/security-gates.md`
High-risk approval	Enforced on GitHub only — a PR touching auth, payments, migrations, infrastructure, secrets, or destructive shell fails the risk-gate CI check (a GitHub Actions workflow); the merge CI gate refuses to merge over a red check and the merge agent is forbidden to force past it, so the PR cannot land without human approval. The run parks the story AWAITING_APPROVAL: recognition is deterministic (Epic-25) — on any merge failure the controller re-checks the PR's labels and check rollup, so a merge blocked solely by the gate parks on both build and resume instead of misreading as FAILED, while a non-gate failure still routes to the bugfix loop. On GitLab there is no enforced high-risk gate: nothing detects high-risk paths, and even a maintainer-applied risk:high label fails no pipeline job and triggers no approval rule — it is honored only as a best-effort instruction to the merge agent	`docs/high-risk-gate.md`

**Shipped, but opt-in or not yet wired into the build loop** — worth knowing before you rely on them:

Mechanism	Status today	Docs
Adversarial review slot	Vendor-agnostic second-reviewer interface with an any_block_majority consensus rule (Codex reference implementation: scripts/codex-adversarial-review.sh). Runs standalone — the build loop never dispatches it. Note that --harness review=codex is a different thing: it routes the ordinary review stage to a single Codex reviewer, not this slot	`docs/adversarial-review.md`
SAST / dependency scans	sdlc sast / sdlc depscan classify an externally produced scan report (exit non-zero on BLOCK) — they do not run the scanners, and no CI job currently runs semgrep or osv-scanner: GitHub CI runs gitleaks + the supply-chain pattern scan, the GitLab template runs gitleaks only	`docs/security-gates.md`
Over-engineering lens	A structured delete-list review of a diff ("would a senior engineer call this overcomplicated?"), dispatched after a successful review stage — disabled by default (enabled: false), advisory-only when opted in: findings are logged as a ledger event and never fail the stage or block the merge	`docs/overengineering-lens.md`
E2E	Playwright suites via the /design-e2e and /execute-e2e-tests skills; the epic-boundary E2E gate belongs to the legacy skill pipeline and is not yet a controller stage	—

Alongside the merge checks, two run-level control planes: **cost governance** (a per-run token budget gate that pauses resumably, per-task model routing by complexity and risk, rate-limit awareness with auto-resume — Epic-14), and an **evaluation harness** that scores agent output (LOC, tokens, cost, quality) across real tickets with variant A/B and regression baselines, so prompt/model/skill changes are measured rather than guessed — see [`docs/evaluation.md`](docs/evaluation.md).

---

Telegram notifications

Long-running autonomous runs mirror lifecycle milestones to Telegram so you can monitor them away from the machine:

• Skills call `hooks/notify-telegram.sh` "" "" at milestones (fix-issue started/complete, requirements/stories/epic created).
• The controller (sdlc build/resume) emits run-lifecycle notifications directly via notify.py (run started / finished / rate-limited / first story failure) — gated to one-per-run for failures so your phone doesn't buzz 47 times during a bad run.

Both paths are best-effort and Telegram-only: credentials come from `$TELEGRAM_BOT_TOKEN` / `$TELEGRAM_CHAT_ID` (env first, then `~/.claude/config/.env`), and every call is a silent no-op when unconfigured.

---

Hardware envelope

`build-stories --parallel` caps at **5 concurrent agents per stage**. That number isn't arbitrary — it's the ceiling on a **MacBook Pro M3 Max with 48 GB of unified memory**.

Each concurrent agent runs:

• Its own Claude Code process and agentic tool-use loop
• Its own git worktree (a full checkout of the repo on disk)
• Its own MCP server subprocesses (Playwright, context7, etc. as needed)
• Live language servers (tsc, pyright) spun up by the typescript/pyright plugins

At 5 agents × (Claude Code + MCP fleet + LSP + worktree I/O) the machine is sitting near memory pressure. Six would start swapping; seven would thrash. If you're running on less than 48 GB, lower the worker count with `--concurrency=N`, drop to `--sequential`, or run narrower cohorts via `--limit=N`. This is the practical constraint that shapes the whole cohort model — not algorithm elegance, but RAM.

---

What's in the repo

Path	Description	Count
CLAUDE.md	Global instructions loaded into every Claude Code session	1
.claude-plugin/marketplace.json	Local Claude Code marketplace manifest (registers the autonomous-sdlc plugin under the fx-claude-config marketplace)	1
controller/	sdlc CLI — Python controller that owns the build-stories state machine (Epic-07). Install via ./scripts/install-controller.sh. See `controller/README.md`.	1 package
shared-skills/	Single source of truth for the 7 skills shared between the Claude Code and Codex plugins (check-releases, coverage, create-issue, etc.) — consumed as a git submodule by the nix-install Codex mirror	7 skills
plugins/autonomous-sdlc/	Claude Code plugin — SDLC skills surfaced as bare slash-commands labelled (autonomous-sdlc) (mirror of the Codex autonomous-sdlc plugin in nix-install)	1 plugin / 8 skills
skills/	Loose user-level Claude skills not part of the SDLC plugin (generators, e2e, claude-docs, model-shelf, telegram, demo)	10
commands/	Namespaced slash commands (dev/, project/, research/, plus top-level)	16
agents/	Specialist agent definitions (8 SDLC + 4 personal extras)	12
hooks/	Telegram notifier, worktree bootstrap, PR-merge docs hook, orphan-worktree sweeper, worktree GC, SQLite ledger emitter, hook profiles, session context	8 scripts
scripts/	CI validators, release gates (compute-release.sh, release-guard.sh), deploy + controller bootstrap, harness adapters (codex-build-adapter.sh, qwen-build-adapter.sh), security scans (SAST, OSV, supply-chain), shared-skills sync, smoke test	21
tests/	bats test suite for hooks, install smoke tests, the controller, harness adapters, and release gates	39 bats
templates/	Shared scaffolding used by generator skills	5
reference-docs/	Language/tooling references loaded via @ imports	3
docs/	User-facing docs (CLAUDE.md guide, Python/container/DB/testing best practices, generators, controller architecture, ADRs, contracts)	—
settings.json	Hooks config, statusline, enabled plugins, marketplaces	—
statusline-command.sh	Statusline renderer	—
keybindings.json	Keybindings override	—
mcp/config.template.json	MCP server template (env-var substituted at install)	—
install.sh + install/	Modal installer (--core, --tools, --mcp, --shell, --all, --dry-run, --uninstall). Dispatcher in install.sh, per-mode logic in install/{core,tools,mcp,shell}.sh.	1 + 5

Mirror plugins — `autonomous-sdlc` on both runtimes

The same plugin name ships on both platforms with overlapping but not identical skill sets. The shared core covers the user-facing SDLC chain (`project-init → brainstorm → generate-epics → create-epic → create-story → build-stories`); each side adds runtime-specific extras.

**Claude Code plugin** — `plugins/autonomous-sdlc/` in this repo (8 skills):

Skill	Invocation
project-init	/project-init [name]
brainstorm	/brainstorm [idea]
generate-epics	/generate-epics
create-epic	/create-epic [topic]
create-story	/create-story
build-stories	/build-stories [story-id|all]
fix-issue	/fix-issue [issue|all|next]
resume-build-agents	/resume-build-agents

**Codex plugin** — `plugins/autonomous-sdlc/` in the sibling [`nix-install`](https://github.com/fxmartin/nix-install) repo (15 skills):

• All 8 Claude skills above (same names, same purpose)
• Plus 7 Codex-only utilities: check-releases, coverage, create-issue, create-project-summary-stats, plan-release-update, project-review, roast
• Used as the adversarial review counterpart for Claude Code work: Codex can run project-review, roast, coverage, and create-issue against Claude-produced changes to catch bugs, missing tests, brittle assumptions, and integration regressions before merge.

The 7 Codex extras live in a single source of truth at `shared-skills/` in this repo — there is exactly one copy, so the Claude and Codex sides cannot drift (see [ADR-002](docs/adr/002-codex-mirror-sync.md)). On the Claude side, `install.sh --core` symlinks each one in as a bare top-level slash command (`/check-releases`, `/coverage`, `/create-issue`, `/create-project-summary-stats`, `/plan-release-update`, `/project-review`, `/roast`) — the symlinks keep the single copy, so there is still no duplication.

Shared-skills sync workflow

`claude-code-config` (this repo) is the source of truth; the `nix-install` Codex mirror consumes `shared-skills/` as a git submodule.

• **Edit** a shared skill here, in `shared-skills/`. Commit and release as usual — each `vX.Y.Z` tag is the versioned shared-skills artifact a consumer pins to.

• **Pull** the latest into a consumer repo with one command:

  git submodule update --remote          # or: ./scripts/sync-shared-skills.sh update

• **Verify** byte-for-byte parity after pulling:

  sdlc sync-check /shared-skills /shared-skills
  # or: ./scripts/sync-shared-skills.sh verify /shared-skills /shared-skills

  Exits 0 in sync, 1 on drift (naming the offending skill), 2 if a directory is missing.

Agent roster

The roster is split into two scopes (Story 6.2-001). **SDLC plugin agents** live directly under `agents/` and are the public surface used by the `autonomous-sdlc` plugin's workflows. **Personal extras** live under `agents/personal/` — they ship with `--core` install (the `agents/` directory is symlinked as a unit) but are not part of the plugin's documented surface and can be ignored by LTM colleagues who only want the SDLC workflows.

SDLC plugin agents

Agent	Specialization
backend-typescript-architect	Bun runtime, advanced TypeScript, microservices
python-backend-engineer	FastAPI, uv, SQLAlchemy, async Python
ui-engineer	Modern frontend, component architecture, responsive design
bash-zsh-macos-engineer	macOS shell scripting, automation, CI/CD
podman-container-architect	OCI containers, multi-stage builds, rootless Podman
qa-engineer	Test strategy, quality metrics, defect management
senior-code-reviewer	Architecture validation, security audits, best practices
meta-agent	Generates new agent definitions

All code agents above (except `meta-agent`) pin `model: sonnet` in their frontmatter so Agent-tool dispatches don't inherit the session default (typically Opus). An orchestrator can still escalate by passing an explicit `model` at dispatch, which overrides the frontmatter — see `WORKFLOW-v2.md`.

Personal extras

Agent	Specialization
crypto-coin-analyzer, crypto-market-agent	Crypto market/ticker analysis
executive-summary-generator, professional-profile-researcher	Research workflows

---

Install

**First time here?** Read [docs/onboarding.md](docs/onboarding.md) — a 15-minute walkthrough from blank machine to first autonomous build, written for the LTM colleague pilot.

**Piloting the framework?** Start at [docs/pilot-kit/README.md](docs/pilot-kit/README.md) — the five-colleague smoke-test kit (Story 6.3-001): what's expected of a pilot, the feedback form, and the environment-capture helper.

Portable (any macOS / Linux)

git clone git@github.com:fxmartin/claude-code-config.git
cd claude-code-config
cp .env.example .env          # Machine-specific values (e.g., BROWSER_PATH)
./install.sh --core           # Default: just the symlinks; opt in to the rest.

The installer is now **modal** — pick one or more of `--core`, `--tools`, `--mcp`, `--shell`, or use `--all` to run every mode. The default when no mode flag is passed is `--core` (conservative, additive).

./install.sh --core              # Symlink config into ~/.claude (default)
./install.sh --core --mcp        # Combine modes — order does not matter
./install.sh --all               # core + tools + mcp + shell
./install.sh --all --dry-run     # Preview every action across every mode
./install.sh --uninstall         # Remove core symlinks (other modes are untouched)

What this script does to your machine

Each mode is **opt-in**, **idempotent**, and supports `--dry-run` for an exact preview of every action before any change lands.

Mode	Touches	Files added	Files modified
--core	~/.claude/	symlinks for CLAUDE.md, agents/, commands/, skills/, hooks/, settings.json, statusline-command.sh, keybindings.json, reference-docs/, docs/, plugins/marketplaces/fx-claude-config	none
--tools	/opt/homebrew/ (macOS) or apt (WSL2; --prefer-brew opts back into brew)	yazi, bat, fd, rg, fzf, zoxide, ffmpeg, imagemagick, poppler, sevenzip, jq, optional Nerd Font; on WSL2 yazi falls back to cargo install --locked yazi-fm	~/.config/yazi/yazi.toml, ~/.config/yazi/init.lua (created if absent)
--mcp	~/.claude.json	merges mcp/config.template.json into existing JSON via jq	only the mcpServers key
--shell	~/.zshrc (macOS / zsh) or ~/.bashrc (WSL2 with non-zsh default)	nothing	appends dev() and y() shell functions if absent; on WSL2 dev() is a stub that prints "cmux is macOS-only; this command is a no-op on WSL2"

Deprecated flags (still supported, removed in next MAJOR)

Old flag	New equivalent
./install.sh --skip-mcp	./install.sh --core --tools --shell
./install.sh --skip-tools	./install.sh --core --mcp --shell

Both legacy flags emit a deprecation warning pointing at the new modes.

Windows install via WSL2

The installer auto-detects WSL2 (via `/proc/version`) and switches package manager + shellrc accordingly: `--tools` prefers `apt` (override with `--prefer-brew`), `--mcp` validates `BROWSER_PATH` against the `/mnt/c/` mount, and `--shell` appends to `~/.bashrc` when zsh is not the default (installing a `dev()` stub since cmux is macOS-only).

Windows

See [docs/install-windows.md](docs/install-windows.md) for the WSL2-based install guide.

As a submodule (Nix-managed machines)

Consumed at `config/claude-code-config/`. The Nix activation script handles symlinks and MCP config generation — run the installer with `--skip-mcp`.

Claude Code plugin install

Two paths — pick one.

Option A — Install directly from GitHub (recommended for users)

No local clone needed. Inside any Claude Code session:

/plugin marketplace add fxmartin/claude-code-config
/plugin install autonomous-sdlc@fx-claude-config

Claude Code clones the repo into `~/.claude/plugins/marketplaces/fx-claude-config/`, reads `.claude-plugin/marketplace.json`, and installs the `autonomous-sdlc` plugin from `./plugins/autonomous-sdlc`. Pull updates later with:

/plugin marketplace update fx-claude-config

Option B — Local clone + symlink (dev workflow)

Use this if you're authoring or iterating on the plugin's skills — edits to `plugins/autonomous-sdlc/skills//SKILL.md` land live in Claude Code without re-installing. `./install.sh` symlinks `~/.claude/plugins/marketplaces/fx-claude-config/` → this checkout. After it runs once:

/plugin marketplace add fx-claude-config
/plugin install autonomous-sdlc@fx-claude-config

Verify either path

jq '.plugins | keys' ~/.claude/plugins/installed_plugins.json
# expect: includes "autonomous-sdlc@fx-claude-config"

A new Claude Code session then surfaces the plugin's 8 skills as bare slash-commands (`/brainstorm`, `/create-story`, etc.) — typing `/auto` in the prompt also matches them via the `(autonomous-sdlc)` annotation.

Codex plugin install

The Codex mirror lives in the sibling [`nix-install`](https://github.com/fxmartin/nix-install) repo at `plugins/autonomous-sdlc/`. For a home-level Codex install, register the local marketplace rooted at your home directory:

codex plugin marketplace add "$HOME"

The home-rooted marketplace file lives at:

~/.agents/plugins/marketplace.json

and resolves:

./plugins/autonomous-sdlc -> ~/plugins/autonomous-sdlc

If `~/plugins/autonomous-sdlc` is symlinked to the `nix-install` repo's plugin directory, Codex sessions will pick up future skill changes after a restart. If automatic install is not honored by the current Codex build, install the plugin once from `/plugins` inside Codex and keep using the shared plugin path on disk.

---

Environment variables

Copy `.env.example` to `.env` and fill in:

Variable	Purpose
BROWSER_PATH	Absolute path to a Chromium-based browser for the Playwright MCP server
TELEGRAM_BOT_TOKEN	Optional — enables Telegram notifications via hooks/notify-telegram.sh and the /telegram skill
TELEGRAM_CHAT_ID	Optional — target chat for Telegram notifications

---

MCP servers

The portable install runs MCP servers via `npx`:

• context7 — up-to-date library documentation
• playwright — browser automation (E2E tests, UI verification)

On Nix machines, MCP servers use Nix-installed binaries instead of `npx`. Additional servers (Gamma, Gmail, Google Calendar/Drive) are configured separately and not part of this repo.

---

Generator skills

Three skills for scaffolding new Claude Code components from within Claude Code:

/create-command "generate changelog entries"    # Create a slash command
/create-agent                                   # Interactive agent generator
/create-skill --scaffold "lint fixer"           # Skill scaffold with TODO placeholders

Each generator supports **interactive** (ask one question at a time), **direct** (generate from a description), and **scaffold** (minimal template with TODOs) modes. All three ask whether to install globally (this config repo) or locally (current project's `.claude/`), and include a review-before-write cycle.

See [`docs/generators.md`](docs/generators.md).

---

Reference material

• `CLAUDE.md` — global instructions loaded into every session (core principles, coding standards, CLI tool preferences, GitHub workflow)
• `WORKFLOW-v2.md` — end-to-end workflow walkthrough
• `docs/claude-md-guide.md` — deep dive on CLAUDE.md structure, guardrails, and maintenance
• `docs/generators.md` — generator skills documentation
• `docs/controller-architecture.md` — sdlc controller module map, state-machine, and retry semantics (Epic-07)
• `docs/contracts.md` — agent I/O JSON-schema contracts reference
• `docs/harness-adapters.md` — add a new agent harness (config + wrapper, no Python) and the generic CLI adapter template (Epic-20)
• `docs/gitlab-adoption.md` — take a company GitLab repo from zero to its first green sdlc build MR (Epic-23)
• `docs/issue-host-adapters.md` — the gh/glab code-host adapter contract behind sdlc issues (Epic-22)
• `docs/security-gates.md` · `docs/high-risk-gate.md` · `docs/adversarial-review.md` · `docs/overengineering-lens.md` — the gate stack
• `docs/evaluation.md` — the agent-output evaluation harness (Epic-18)
• `docs/hook-profiles.md` — tune hook strictness and SessionStart context from the environment (Epic-15)
• `docs/onboarding.md` — 15-minute walkthrough from blank machine to first autonomous build
• `docs/adr/001-controller-runtime.md` · `docs/adr/002-codex-mirror-sync.md` — architecture decision records
• `docs/python-best-practices.md` · `docs/testing-best-practices.md` · `docs/container-best-practices.md` · `docs/database-best-practices.md`

---

Contributing

This repo enforces [Conventional Commits](https://www.conventionalcommits.org/). A `commit-format` CI job runs `commitlint` against every PR and will fail if any commit in the range violates the rules. Allowed types: `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `ci`, `perf`, `build`, `revert`. Subject must start lowercase, no trailing period, max 72 chars.

Every push to `main` that contains a `feat:` or `fix:` commit (or better) triggers the release workflow: it bumps semver, creates a `vX.Y.Z` tag, updates `plugin.json` and `marketplace.json`, appends a CHANGELOG entry, and opens a GitHub Release with auto-generated notes. `chore:`/`docs:`-only pushes produce no release.

---

Acknowledgements

Three external sources shaped this harness:

• forrestchang/andrej-karpathy-skills (MIT) — the Surgical Changes sub-rules, Complexity check heuristic, and Verifiable Goals plan template in `CLAUDE.md` are adapted from this repo, which itself derives from Andrej Karpathy's observations on LLM coding pitfalls. Absorbed as prose rather than installed as a plugin, for single-source ownership.
• obra/superpowers (MIT, Jesse Vincent) — the agent-discipline patterns in Epic-26 (root-cause-first bugfix, review findings as disputable claims, red/green pressure-tests) are adapted from this project's prompt-level process rules and re-implemented as schema-enforced contracts in the deterministic controller.
• anthropics/skills — Anthropic's official example-skills marketplace, wired in via settings.json. Provides the example-skills plugin bundle (web-artifacts-builder, webapp-testing, frontend-design, canvas-design, algorithmic-art, skill-creator, claude-api, theme-factory, mcp-builder, docx/xlsx/pptx/pdf, brand-guidelines, internal-comms, doc-coauthoring, slack-gif-creator).

---

License

MIT — see [`LICENSE`](LICENSE).