{"id":50009230,"url":"https://github.com/fxmartin/claude-code-config","last_synced_at":"2026-06-28T08:00:50.439Z","repository":{"id":353529093,"uuid":"1175904600","full_name":"fxmartin/claude-code-config","owner":"fxmartin","description":"Opinionated Claude Code harness — idea → merged PR via a multi-agent AGILE pipeline with cmux observability, worktree-isolated parallel builds, and TDD+review gates.","archived":false,"fork":false,"pushed_at":"2026-06-27T17:04:37.000Z","size":8526,"stargazers_count":0,"open_issues_count":2,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-27T19:04:31.119Z","etag":null,"topics":["agile","ai-agents","anthropic","claude-code","cmux","developer-tools","multi-agent"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fxmartin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security-gates.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-08T10:46:57.000Z","updated_at":"2026-06-27T17:01:45.000Z","dependencies_parsed_at":null,"dependency_job_id":"7c328e1a-ed98-42e3-b3f8-e80726751361","html_url":"https://github.com/fxmartin/claude-code-config","commit_stats":null,"previous_names":["fxmartin/claude-code-config"],"tags_count":120,"template":false,"template_full_name":null,"purl":"pkg:github/fxmartin/claude-code-config","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fxmartin%2Fclaude-code-config","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fxmartin%2Fclaude-code-config/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fxmartin%2Fclaude-code-config/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fxmartin%2Fclaude-code-config/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fxmartin","download_url":"https://codeload.github.com/fxmartin/claude-code-config/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fxmartin%2Fclaude-code-config/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34881384,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agile","ai-agents","anthropic","claude-code","cmux","developer-tools","multi-agent"],"created_at":"2026-05-19T21:08:52.106Z","updated_at":"2026-06-28T08:00:50.431Z","avatar_url":"https://github.com/fxmartin.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# claude-code-config\n\n[![CI](https://github.com/fxmartin/claude-code-config/actions/workflows/ci.yml/badge.svg)](https://github.com/fxmartin/claude-code-config/actions/workflows/ci.yml)\n[![Release](https://github.com/fxmartin/claude-code-config/actions/workflows/release.yml/badge.svg)](https://github.com/fxmartin/claude-code-config/actions/workflows/release.yml)\n[![GitHub release](https://img.shields.io/github/v/release/fxmartin/claude-code-config)](https://github.com/fxmartin/claude-code-config/releases/latest)\n\nA 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**.\n\nThis 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.\n\nThe 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 \u003cname\u003e`.\n\nWe 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.\n\n---\n\n## What this harness achieves\n\n```\n idea ─▶ /project-init ─▶ git repo + GitHub remote + labels + CLAUDE.md + PROJECT-SEED.md\n         │\n         ▼\n     /brainstorm ─▶ REQUIREMENTS.md  (seed-aware: skips what /project-init already answered)\n         │\n         ▼\n     /generate-epics ─▶ STORIES.md + epic-NN-*.md + NFRs\n         │\n         ▼\n     /build-stories (parallel, autonomous)\n         │  ├─ Discovery agent → dependency cohorts\n         │  ├─ Build agents   (×5, worktree-isolated, TDD)\n         │  ├─ Coverage gate  (×5, enforces 90%+)\n         │  ├─ Review agent   (×5, senior-code-reviewer)\n         │  └─ Merge agent    (sequential, rebase-before-merge)\n         │      └─ Bugfix loop on failure (classify → fix → retry ×2)\n         ▼\n     E2E gate (Playwright, at epic boundaries)\n         │\n         ▼\n     /project-review · /coverage · /create-project-summary-stats\n```\n\nEvery phase emits structured events to the ledger and mirrors milestones to Telegram so long-running runs can be monitored away from the machine.\n\n---\n\n## The workflow, in five phases\n\n### Phase 0 — Bootstrap (`/project-init`)\n\nA 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.\n\nPre-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`.\n\nOutput:\n\n- `git init` + first commit\n- GitHub remote created via `gh repo create` (public or private per your answer)\n- **26 standard labels** applied (bug, enhancement, priority:*, epic:*, etc.) plus any project-specific ones\n- `.gitignore` tailored to the detected tech stack\n- **`CLAUDE.md`** — lightweight scaffold with placeholders for sections `/brainstorm` will fill in later (testing strategy, CI/CD, DB, deployment)\n- **`PROJECT-SEED.md`** — structured handoff file that `/brainstorm` detects and reads to skip redundant questions\n\nThe 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.\n\n### Phase 1 — Discovery (`/brainstorm`)\n\nA 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).\n\n### Phase 2 — Planning (`/generate-epics`, `/create-epic`)\n\nTransforms `REQUIREMENTS.md` into a modular AGILE structure:\n\n- `STORIES.md` — master overview\n- `docs/stories/epic-NN-\u003cname\u003e.md` — INVEST-compliant user stories in `{Epic}.{Feature}-{NNN}` format\n- `docs/stories/non-functional-requirements.md` — perf, security, reliability targets\n\n`/create-epic` lets you add more epics interactively without redoing discovery.\n\n### Phase 3 — Build\n\nTwo paths depending on how much control you want:\n\n| Mode | Command | When to use |\n|------|---------|-------------|\n| **Controlled** | `/resume-build-agents \u003cstory-id\\|epic\\|next\u003e` | One story at a time, visible agent selection, manual PR decisions |\n| **Autonomous** | `/build-stories [all\\|resume\\|epic-NN] [--sequential]` | Full batch — parses the story graph, schedules cohorts, runs until done |\n| **Issue-driven** | `/fix-issue \u003cN\\|url\\|next\\|all\u003e` | 11-phase pipeline: investigate → build → coverage → review → E2E → merge → summary, with auto-classified bugfix retries |\n\n##### Harness support: cross-harness vs Claude-only\n\n`/build-stories` runs through the controller's dispatch seam, so its roles can be\nrouted to any registered harness (`--harness build=claude,review=codex,…`).\n`/fix-issue` and `/resume-build-agents` spawn their sub-agents **in-process** with\nthe Claude Code `Agent` tool (`subagent_type` / `isolation=\"worktree\"`), which has\nno CLI-harness equivalent — they stay **Claude-only** by design. The boundary is\ndocumented in [`docs/controller-architecture.md`](docs/controller-architecture.md#the-in-process-agent-boundary-story-206-002) and enforced by `sdlc/portability.py`.\n\n| Skill | Dispatch mechanism | Harness support |\n|-------|--------------------|-----------------|\n| `build-stories` | controller dispatch seam | **Any registry harness** |\n| `fix-issue` | in-process `Agent` tool | **Claude only** |\n| `resume-build-agents` | in-process `Agent` tool | **Claude only** |\n\n#### The autonomous path: how `/build-stories` actually runs\n\nThe 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.\n\n1. **Discovery agent** parses every epic file, resolves the dependency graph, topologically sorts it, and returns a `QUEUE_JSON` build queue.\n2. **Cohort scheduler** groups stories whose dependencies are all complete into parallel cohorts (Cohort 1 = no deps; Cohort N = deps all in prior cohorts).\n3. Each cohort runs through **4 stages**:\n\n   ```\n   Cohort N:\n     Stage 1: [build A, B, C, D, E]     ← parallel, each in own git worktree (TDD)\n     Stage 2: [coverage A, B, C, D, E]  ← parallel, adds tests to hit 90%+\n     Stage 3: [review A, B, C, D, E]    ← parallel, senior-code-reviewer\n     Stage 4: [merge A → B → C → D → E] ← sequential, rebase-before-merge\n   ```\n\n   ![Parallel build workflow](docs/ParallelBuild.jpg)\n\n4. **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.\n5. **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.\n6. **E2E gate** at epic boundaries runs Playwright tests — blocking, warning, or off per flag.\n7. **Summary agent** emits the run's metrics and a merged-PR manifest.\n\nProgress 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.\n\n### The `sdlc` controller (Epic-07)\n\nThe `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.\n\n#### Install\n\n```bash\n# From the repo root — bootstraps uv if needed, then installs the CLI:\n./scripts/install-controller.sh\n\n# Or directly if you already have uv:\ncd controller \u0026\u0026 uv tool install .\n```\n\n#### Key subcommands\n\n| Command | Purpose |\n|---------|---------|\n| `sdlc build [scope] [--dry-run] [--auto] [--skip-coverage] [--limit=N]` | Run the full build-stories orchestration |\n| `sdlc resume` | Resume an interrupted build from the ledger state |\n| `sdlc status` | Show current run status and stage progress |\n| `sdlc state` | Inspect the persisted state machine for a run |\n| `sdlc validate \u003cagent-type\u003e \u003cfile\u003e` | Validate an agent response against its JSON schema |\n| `sdlc rollback` | Roll a run back to a prior ledger checkpoint |\n| `sdlc sync-check \u003csrc\u003e \u003cdst\u003e` | Verify shared-skills parity between repos |\n\n`sdlc build` accepts the same arguments as `/build-stories` — the skill simply shells out to it. Migration is invisible to end users.\n\n#### Agent I/O contracts\n\nEvery agent the orchestrator dispatches must return a JSON object fenced with `\u003c\u003c\u003cRESULT_JSON\u003e\u003e\u003e` ... `\u003c\u003c\u003cEND_RESULT\u003e\u003e\u003e` 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).\n\nSee [`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).\n\n---\n\n### Phase 4 — Quality \u0026 Intelligence\n\nAfter build, the harness can audit itself:\n\n| Command | Purpose |\n|---------|---------|\n| `/coverage` | Fill coverage gaps to 100% |\n| `/design-e2e` | Generate Playwright E2E tests from acceptance criteria |\n| `/execute-e2e-tests` | Run the E2E suite |\n| `/project-review` | Full quality audit with scoring |\n| `/create-project-summary-stats` | Metrics, retrospective, velocity |\n| `/update-estimated-time-spent` | Dev velocity tracking |\n| `/create-user-documentation` | Production-ready end-user docs |\n| `/update-progress` · `/sync-progress` | Reconcile story status across files |\n\nFor 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.\n\nThe full workflow is documented end-to-end in [`WORKFLOW-v2.md`](WORKFLOW-v2.md).\n\n---\n\n## Observability — the live dashboard\n\nAutonomous 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.\n\n![The Autonomous SDLC live dashboard](screenshot/dashboard.jpg)\n\n```bash\nsdlc dashboard --open          # serve, and open it in the browser\n```\n\nIt binds to **http://127.0.0.1:8787** by default (localhost-only).\n\n**What it shows**\n\n- **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.\n- **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.\n- **GitHub repo-health panel** — open/closed issues, open/closed PRs, and the latest CI status on `main`, refreshed every 30 seconds.\n- **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.\n- **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.\n- **Events log** — the run's ledger events (errors, warnings, milestones) in chronological order.\n\n**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 \u003cpath\u003e` to scope it to one repo.\n\n**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.\n\n| Flag | Effect |\n|------|--------|\n| `--open` | Open the dashboard in a browser on start |\n| `--port N` | Bind port (default `8787`) |\n| `--host H` | Bind host (default `127.0.0.1`, localhost-only) |\n| `--run \u003cid\u003e` | Focus a specific run (default: the most recent) |\n| `--db \u003cpath\u003e` | Single-ledger mode (default: host registry, all repos) |\n| `--restart` / `--stop` | Restart, or stop, a dashboard already running on this host:port |\n\n---\n\n## Why it works\n\n- **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.\n- **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.\n- **Mandatory senior-code-reviewer** — every PR flows through an architecture/security review before merge. Not a nice-to-have, not optional.\n- **TDD-first** — tests are written before implementation; the coverage gate fails the story if the final suite doesn't hit the threshold (default 90%).\n- **Worktree isolation** — five agents can genuinely run in parallel without clobbering each other's files, because each has its own checkout.\n- **Sequential merge with rebase** — Stage 4 serializes merges with rebase-before-merge, preventing the race conditions that kill naive parallel-merge setups.\n- **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.\n- **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.\n\n---\n\n## Telegram notifications\n\nLong-running autonomous runs mirror lifecycle milestones to Telegram so you can monitor them away from the machine:\n\n- **Skills** call [`hooks/notify-telegram.sh`](hooks/notify-telegram.sh) `\"\u003ctitle\u003e\" \"\u003cbody\u003e\"` at milestones (fix-issue started/complete, requirements/stories/epic created).\n- **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.\n\nBoth 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.\n\n---\n\n## Hardware envelope\n\n`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**.\n\nEach concurrent agent runs:\n\n- Its own Claude Code process and agentic tool-use loop\n- Its own git worktree (a full checkout of the repo on disk)\n- Its own MCP server subprocesses (Playwright, context7, etc. as needed)\n- Live language servers (tsc, pyright) spun up by the typescript/pyright plugins\n\nAt 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, drop the cap with `--sequential` or run narrower cohorts via `--limit=N`. This is the practical constraint that shapes the whole cohort model — not algorithm elegance, but RAM.\n\n---\n\n## What's in the repo\n\n| Path | Description | Count |\n|------|-------------|-------|\n| `CLAUDE.md` | Global instructions loaded into every Claude Code session | 1 |\n| `.claude-plugin/marketplace.json` | Local Claude Code marketplace manifest (registers the `autonomous-sdlc` plugin under the `fx-claude-config` marketplace) | 1 |\n| `controller/` | **`sdlc` CLI** — Python controller that owns the build-stories state machine (Epic-07). Install via `./scripts/install-controller.sh`. See [`controller/README.md`](controller/README.md). | 1 package |\n| `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 |\n| `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 |\n| `skills/` | Loose user-level Claude skills not part of the SDLC plugin (generators, e2e, claude-docs, telegram, demo) | 9 |\n| `commands/` | Namespaced slash commands (`dev/`, `devops/`, `issues/`, `project/`, `quality/`, `research/`) | 17 |\n| `agents/` | Specialist agent definitions (flat) | 12 |\n| `hooks/` | Telegram notifier, worktree bootstrap, PR-merge docs hook, orphan-worktree sweeper, worktree GC, SQLite ledger emitter | 6 scripts |\n| `scripts/` | Standalone scripts run by CI (`validate-agent-registry.sh`), the release workflow (`compute-release.sh`, `release-guard.sh`), and controller bootstrap (`install-controller.sh`) + shared-skills sync (`sync-shared-skills.sh`) | 5 |\n| `tests/` | bats test suite for hooks, install smoke tests, the controller, and release gates (notify-telegram, install dry-run, agent-registry, sweep-orphan-worktrees, sdlc-state, release-guard) | 30 bats |\n| `templates/` | Shared scaffolding used by generator skills | 3 |\n| `reference-docs/` | Language/tooling references loaded via `@` imports | 3 |\n| `docs/` | User-facing docs (CLAUDE.md guide, Python/container/DB/testing best practices, generators, controller architecture, ADRs, contracts) | — |\n| `settings.json` | Hooks config, statusline, enabled plugins, marketplaces | — |\n| `statusline-command.sh` | Statusline renderer | — |\n| `keybindings.json` | Keybindings override | — |\n| `mcp/config.template.json` | MCP server template (env-var substituted at install) | — |\n| `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 |\n\n### Mirror plugins — `autonomous-sdlc` on both runtimes\n\nThe 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.\n\n**Claude Code plugin** — `plugins/autonomous-sdlc/` in this repo (8 skills):\n\n| Skill | Invocation |\n|---|---|\n| `project-init` | `/project-init [name]` |\n| `brainstorm` | `/brainstorm [idea]` |\n| `generate-epics` | `/generate-epics` |\n| `create-epic` | `/create-epic \u003cNN\u003e [topic]` |\n| `create-story` | `/create-story \u003cNN\u003e \u003cdescription\u003e` |\n| `build-stories` | `/build-stories [story-id\\|all]` |\n| `fix-issue` | `/fix-issue [issue\\|all\\|next]` |\n| `resume-build-agents` | `/resume-build-agents` |\n\n**Codex plugin** — `plugins/autonomous-sdlc/` in the sibling [`nix-install`](https://github.com/fxmartin/nix-install) repo (15 skills):\n\n- All 8 Claude skills above (same names, same purpose)\n- Plus 7 Codex-only utilities: `check-releases`, `coverage`, `create-issue`, `create-project-summary-stats`, `plan-release-update`, `project-review`, `roast`\n- 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.\n\nThe 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.\n\n#### Shared-skills sync workflow\n\n`claude-code-config` (this repo) is the source of truth; the `nix-install` Codex mirror consumes `shared-skills/` as a git submodule.\n\n- **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.\n- **Pull** the latest into a consumer repo with one command:\n\n  ```bash\n  git submodule update --remote          # or: ./scripts/sync-shared-skills.sh update\n  ```\n\n- **Verify** byte-for-byte parity after pulling:\n\n  ```bash\n  sdlc sync-check \u003csource\u003e/shared-skills \u003cconsumer\u003e/shared-skills\n  # or: ./scripts/sync-shared-skills.sh verify \u003csource\u003e/shared-skills \u003cconsumer\u003e/shared-skills\n  ```\n\n  Exits 0 in sync, 1 on drift (naming the offending skill), 2 if a directory is missing.\n\n### Agent roster\n\nThe 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.\n\n#### SDLC plugin agents\n\n| Agent | Specialization |\n|-------|---------------|\n| `backend-typescript-architect` | Bun runtime, advanced TypeScript, microservices |\n| `python-backend-engineer` | FastAPI, uv, SQLAlchemy, async Python |\n| `ui-engineer` | Modern frontend, component architecture, responsive design |\n| `bash-zsh-macos-engineer` | macOS shell scripting, automation, CI/CD |\n| `podman-container-architect` | OCI containers, multi-stage builds, rootless Podman |\n| `qa-engineer` | Test strategy, quality metrics, defect management |\n| `senior-code-reviewer` | Architecture validation, security audits, best practices |\n| `meta-agent` | Generates new agent definitions |\n\n#### Personal extras\n\n| Agent | Specialization |\n|-------|---------------|\n| `crypto-coin-analyzer`, `crypto-market-agent` | Crypto market/ticker analysis |\n| `executive-summary-generator`, `professional-profile-researcher` | Research workflows |\n\n---\n\n## Install\n\n\u003e **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.\n\u003e\n\u003e **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.\n\n### Portable (any macOS / Linux)\n\n```bash\ngit clone git@github.com:fxmartin/claude-code-config.git\ncd claude-code-config\ncp .env.example .env          # Machine-specific values (e.g., BROWSER_PATH)\n./install.sh --core           # Default: just the symlinks; opt in to the rest.\n```\n\nThe 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).\n\n```bash\n./install.sh --core              # Symlink config into ~/.claude (default)\n./install.sh --core --mcp        # Combine modes — order does not matter\n./install.sh --all               # core + tools + mcp + shell\n./install.sh --all --dry-run     # Preview every action across every mode\n./install.sh --uninstall         # Remove core symlinks (other modes are untouched)\n```\n\n#### What this script does to your machine\n\nEach mode is **opt-in**, **idempotent**, and supports `--dry-run` for an exact preview of every action before any change lands.\n\n| Mode | Touches | Files added | Files modified |\n|------|---------|-------------|----------------|\n| `--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 |\n| `--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) |\n| `--mcp` | `~/.claude.json` | merges `mcp/config.template.json` into existing JSON via `jq` | only the `mcpServers` key |\n| `--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\"` |\n\n##### Deprecated flags (still supported, removed in next MAJOR)\n\n| Old flag | New equivalent |\n|----------|----------------|\n| `./install.sh --skip-mcp` | `./install.sh --core --tools --shell` |\n| `./install.sh --skip-tools` | `./install.sh --core --mcp --shell` |\n\nBoth legacy flags emit a deprecation warning pointing at the new modes.\n\n#### Windows install via WSL2\n\nThe installer auto-detects WSL2 (via `/proc/version`) and switches package\nmanager + shellrc accordingly: `--tools` prefers `apt` (override with\n`--prefer-brew`), `--mcp` validates `BROWSER_PATH` against the `/mnt/c/`\nmount, and `--shell` appends to `~/.bashrc` when zsh is not the default\n(installing a `dev()` stub since cmux is macOS-only).\n\n### Windows\n\nSee [docs/install-windows.md](docs/install-windows.md) for the WSL2-based install guide.\n\n### As a submodule (Nix-managed machines)\n\nConsumed at `config/claude-code-config/`. The Nix activation script handles symlinks and MCP config generation — run the installer with `--skip-mcp`.\n\n### Claude Code plugin install\n\nTwo paths — pick one.\n\n#### Option A — Install directly from GitHub (recommended for users)\n\nNo local clone needed. Inside any Claude Code session:\n\n```text\n/plugin marketplace add fxmartin/claude-code-config\n/plugin install autonomous-sdlc@fx-claude-config\n```\n\nClaude 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:\n\n```text\n/plugin marketplace update fx-claude-config\n```\n\n#### Option B — Local clone + symlink (dev workflow)\n\nUse this if you're authoring or iterating on the plugin's skills — edits to `plugins/autonomous-sdlc/skills/\u003cname\u003e/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:\n\n```text\n/plugin marketplace add fx-claude-config\n/plugin install autonomous-sdlc@fx-claude-config\n```\n\n#### Verify either path\n\n```bash\njq '.plugins | keys' ~/.claude/plugins/installed_plugins.json\n# expect: includes \"autonomous-sdlc@fx-claude-config\"\n```\n\nA 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.\n\n### Codex plugin install\n\nThe 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:\n\n```bash\ncodex plugin marketplace add \"$HOME\"\n```\n\nThe home-rooted marketplace file lives at:\n\n```text\n~/.agents/plugins/marketplace.json\n```\n\nand resolves:\n\n```text\n./plugins/autonomous-sdlc -\u003e ~/plugins/autonomous-sdlc\n```\n\nIf `~/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.\n\n---\n\n## Environment variables\n\nCopy `.env.example` to `.env` and fill in:\n\n| Variable | Purpose |\n|----------|---------|\n| `BROWSER_PATH` | Absolute path to a Chromium-based browser for the Playwright MCP server |\n| `TELEGRAM_BOT_TOKEN` | Optional — enables Telegram notifications via `hooks/notify-telegram.sh` and the `/telegram` skill |\n| `TELEGRAM_CHAT_ID` | Optional — target chat for Telegram notifications |\n\n---\n\n## MCP servers\n\nThe portable install runs MCP servers via `npx`:\n\n- **context7** — up-to-date library documentation\n- **playwright** — browser automation (E2E tests, UI verification)\n\nOn 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.\n\n---\n\n## Generator skills\n\nThree skills for scaffolding new Claude Code components from within Claude Code:\n\n```bash\n/create-command \"generate changelog entries\"    # Create a slash command\n/create-agent                                   # Interactive agent generator\n/create-skill --scaffold \"lint fixer\"           # Skill scaffold with TODO placeholders\n```\n\nEach 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.\n\nSee [`docs/generators.md`](docs/generators.md).\n\n---\n\n## Reference material\n\n- [`CLAUDE.md`](CLAUDE.md) — global instructions loaded into every session (core principles, coding standards, CLI tool preferences, GitHub workflow)\n- [`WORKFLOW-v2.md`](WORKFLOW-v2.md) — end-to-end workflow walkthrough\n- [`docs/claude-md-guide.md`](docs/claude-md-guide.md) — deep dive on CLAUDE.md structure, guardrails, and maintenance\n- [`docs/generators.md`](docs/generators.md) — generator skills documentation\n- [`docs/controller-architecture.md`](docs/controller-architecture.md) — `sdlc` controller module map, state-machine, and retry semantics (Epic-07)\n- [`docs/contracts.md`](docs/contracts.md) — agent I/O JSON-schema contracts reference\n- [`docs/harness-adapters.md`](docs/harness-adapters.md) — add a new agent harness (config + wrapper, no Python) and the generic CLI adapter template (Epic-20)\n- [`docs/adr/001-controller-runtime.md`](docs/adr/001-controller-runtime.md) · [`docs/adr/002-codex-mirror-sync.md`](docs/adr/002-codex-mirror-sync.md) — architecture decision records\n- [`docs/python-best-practices.md`](docs/python-best-practices.md) · [`docs/testing-best-practices.md`](docs/testing-best-practices.md) · [`docs/container-best-practices.md`](docs/container-best-practices.md) · [`docs/database-best-practices.md`](docs/database-best-practices.md)\n\n---\n\n## Contributing\n\nThis 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.\n\nEvery 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.\n\n---\n\n## Acknowledgements\n\nTwo external sources shaped this harness:\n\n- **[forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills)** (MIT) — the *Surgical Changes* sub-rules, *Complexity check* heuristic, and *Verifiable Goals* plan template in [`CLAUDE.md`](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.\n- **[anthropics/skills](https://github.com/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).\n\n---\n\n## License\n\nMIT — see [`LICENSE`](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffxmartin%2Fclaude-code-config","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffxmartin%2Fclaude-code-config","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffxmartin%2Fclaude-code-config/lists"}