{"id":51167127,"url":"https://github.com/zd87pl/cc-loop-boilerplate","last_synced_at":"2026-06-26T20:30:36.768Z","repository":{"id":367137446,"uuid":"1279373904","full_name":"zd87pl/cc-loop-boilerplate","owner":"zd87pl","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-24T19:01:35.000Z","size":146,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-24T19:07:59.743Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zd87pl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-24T16:17:28.000Z","updated_at":"2026-06-24T19:01:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zd87pl/cc-loop-boilerplate","commit_stats":null,"previous_names":["zd87pl/cc-loop-boilerplate"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/zd87pl/cc-loop-boilerplate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zd87pl%2Fcc-loop-boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zd87pl%2Fcc-loop-boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zd87pl%2Fcc-loop-boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zd87pl%2Fcc-loop-boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zd87pl","download_url":"https://codeload.github.com/zd87pl/cc-loop-boilerplate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zd87pl%2Fcc-loop-boilerplate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34832916,"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-26T02:00:06.560Z","response_time":106,"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":[],"created_at":"2026-06-26T20:30:32.934Z","updated_at":"2026-06-26T20:30:36.762Z","avatar_url":"https://github.com/zd87pl.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Spec-Driven Engineering Loop (Claude Code boilerplate)\n\nTurn a **SPEC + PRD + ADR** set into reviewed, tested implementation through a\nclosed verification loop — then stop at a human sign-off and open a PR. Never\nauto-merges. Polyglot, portable, and minimal to configure.\n\n```\nSPEC + PRD + ADR\n      │\n      ▼\n ① SPECIFY ─► ② PLAN ─► ③ TASKS ─► ④ IMPLEMENT ─► ⑤ REVIEW ─► ⑥ FIX ─► ⑦ VERIFY\n      ▲                                                                      │\n      └──────────────────── gaps / drift / failed gates ◄───────────────────┘\n                                          │\n                                exit when VERIFY passes\n                                          ▼\n                          human sign-off → PR (never auto-merge)\n```\n\n## Why\n\nSpecs drift from code, AI changes are plausible-but-wrong more often than we'd\nlike, and \"looks good\" reviews miss defects. This boilerplate makes the spec the\ncontract: implementation is generated *against* SPEC/PRD/ADR and a verifier\nchecks the result *back against* them, with **deterministic gates** (format,\nlint, type-check, test, build, secret/security scan) enforced by hooks the model\ncannot opt out of, on an **isolated branch**, under **cost and iteration caps**,\nwith a **human owning sign-off and merge**.\n\n## Quickstart\n\n```sh\nmake setup      # interactive: checks the Claude CLI + deps, wires the repo, smoke-tests\nmake doctor     # read-only: prerequisite + configuration status\nmake selftest   # dry-run the loop over the bundled example (no model calls, no cost)\nmake eval       # assert the guardrails actually fire (deterministic; no model calls)\nmake loop SPEC=specs/000-example   # run for real (needs `claude` auth)\n```\n\n`make selftest` walks all nine stages and writes a run report with a populated\ntraceability matrix to `.loop/runs/\u003cid\u003e/report.md` — without calling the model.\n\n## How the loop works\n\n| # | Stage | Owner (subagent) | Output | Gate |\n| - | ----- | ---------------- | ------ | ---- |\n| ① | Specify | `architect` | normalized EARS `spec.md` + open questions | human |\n| ①·5 | Spec review | `spec-reviewer` | readiness scorecard + verdict + risk class | auto (`NOT_READY` halts) |\n| ①·8 | Explore | `explorer` | codebase context map (cheap, read-only) | auto |\n| ② | Plan | `architect` | technical plan referencing ADRs/NFRs | auto (+opt. human) |\n| ③ | Tasks | `architect` | ordered, independently testable tasks | auto |\n| ④ | Implement | `implementer` | code + tests per task, on a branch | auto (hooks run) |\n| ⑤ | Review | `reviewer` + `security-auditor` | findings (severity, CWE) | auto |\n| ⑥ | Fix | `implementer` | patches for findings | auto |\n| ⑦ | Verify | `verifier` | SPEC/PRD/ADR ⇄ code ⇄ test matrix + coverage | human pre-merge |\n\nThe controller halts and asks a human on `NEEDS CLARIFICATION`, stops at\n`max_iterations` or `cost_ceiling_usd`, and halts if an iteration shows no\nmeasurable progress.\n\n## Architecture\n\n```\n.claude/            Claude Code integration\n  settings.json     hooks wiring + permission baseline (project mode)\n  skills/*/SKILL.md the seven stage slash commands\n  agents/*.md       architect, spec-reviewer, explorer, implementer, reviewer, security-auditor, verifier\n  hooks/            pretool-guard (secret+danger veto), posttool-format, stop-gate\n.claude-plugin/     plugin.json + marketplace.json (org-wide install)\nplugin/README.md    distribution docs\nspecs/              constitution.md, templates/, and one dir per feature\nadapters/           detect.sh + stacks/\u003clang\u003e.sh (six-verb gate contract)\nloop/               run.sh controller, state.schema.json, lib/\n.loop.yml           the per-repo config you edit\nMakefile            make setup | doctor | selftest | eval | loop | gates\n.github/            PR template + CI (gate suite + deterministic evals)\nscripts/            install.sh / uninstall.sh / spec-lint.sh (deterministic spec gate)\nevals/              make eval — deterministic guardrail assertions (no model calls)\nexamples/           a real worked example whose gates actually execute\nAGENTS.md           portable cross-tool agent context\nCLAUDE.md           Claude-specific pointer to the above\n```\n\n## Configuration (`.loop.yml`)\n\nThe single file most engineers touch. Highlights (see the file for all keys and\ninline docs):\n\n| Key | Meaning |\n| --- | --- |\n| `spec_dir` | where SPEC/PRD/ADR live |\n| `branch_prefix` / `protected_branches` | feature-branch prefix; branches the loop refuses to write |\n| `max_iterations` / `cost_ceiling_usd` | hard stops on review↔fix cycles and spend |\n| `require_human_gates` | which stages pause for a person (default: `spec`, `premerge`) |\n| `models` | model alias per stage (`opus`/`sonnet`/`haiku`) |\n| `gates.\u003cverb\u003e` | override any adapter command for your repo |\n| `secret_scan`, `open_pr`, `pr_draft` | guardrails and PR behavior |\n\n## Polyglot by adapters\n\nThe loop auto-detects the repo's stack(s) from manifest files and delegates\nbuild/lint/test to per-language adapters. Each `adapters/stacks/\u003clang\u003e.sh`\nexports the same six verbs — `fmt lint typecheck test build securityscan` —\nand missing optional tools skip gracefully (reported by `make doctor`, never\nsilently masked). Ship-in adapters: node, python, go, rust, java, dotnet, ruby.\n\n**Add a stack:** copy `adapters/stacks/_template.sh` to `stacks/\u003clang\u003e.sh`,\nimplement the verbs, and add a detection rule to `adapters/detect.sh`.\n\n**Override a gate without an adapter:** set `gates.\u003cverb\u003e` in `.loop.yml`, e.g.\n`gates.securityscan: \"semgrep --config auto\"`.\n\n## Safety \u0026 governance\n\n- Runs only on a dedicated worktree/branch; refuses protected branches and\n  destructive git operations.\n- A **PreToolUse** hook vetoes writes/commands that would expose a secret or\n  rewrite shared history (exit code 2 denies).\n- Hard `max_iterations` and `cost_ceiling_usd`; human gates after spec\n  normalization and before opening a PR.\n- Every run leaves an audit trail — `events.jsonl` + `report.md` with a\n  reproducibility header (models, tool versions, config hash, base/head SHAs).\n- **Data handling:** all processing is local; the only data leaving the machine\n  is the content sent to the model API. PII/secrets are kept out of logs/reports,\n  and `.loop/runs/` is gitignored.\n\n## Distribution\n\nInstall org-wide as a Claude Code plugin (slash commands + subagents + hooks in\nany repo), or vendor the repo to get the full headless orchestrator. See\n[`plugin/README.md`](plugin/README.md).\n\n## Portability\n\nSPEC/PRD/ADR, `specs/constitution.md`, and `AGENTS.md` are plain markdown, so\nengineers on Cursor / Copilot / Codex consume the same artifacts. The `.claude/`\ndirectory is the Claude Code reference implementation; other tools ignore it.\n\n## Tooling accuracy\n\nThe Claude-Code surface used here (headless `claude -p`, `--output-format json`,\n`--permission-mode`, `--model`, `--max-budget-usd`, hook events, plugin/skill/\nagent schemas) was verified against the installed CLI. Notably this CLI has **no\n`--max-turns`**, so iteration bounds are enforced by the controller. Verify\nagainst your installed version before relying on any flag — see `ONBOARDING.md`.\n\n## Next\n\nNew here? Follow [`ONBOARDING.md`](ONBOARDING.md) — your first loop in ~5 minutes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzd87pl%2Fcc-loop-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzd87pl%2Fcc-loop-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzd87pl%2Fcc-loop-boilerplate/lists"}