What's included
The big picture: Blueprint is about 140 files of process — CI, Git hooks, scripts, Claude Code agents and skills — and no application code. This page lists all of it.
Why it matters: You own everything you clone. Knowing what each part does tells you what’s safe to delete and what’s quietly holding something up.
The bottom line: Nothing here is mandatory. Delete what you don’t need — but delete it on purpose (see Removing what you don’t need).
By category
Section titled “By category”| Category | Files | What it gives you |
|---|---|---|
| Project contract | AGENTS.md |
The agent-agnostic rules any coding agent reads: stack, commands, invariants and forbidden operations, the branch → MR → green-pipeline flow, where the gates live — see Agent portability |
| Claude agents | .claude/agents/ |
Specialist reviewers and helpers — see Agents |
| Claude skills | .claude/skills/ |
Slash-command workflows — see Skills |
| Claude hooks | .claude/hooks/, .claude/settings.json |
Guards that block risky edits, reminders after edits, and a security gate before an MR opens |
| Claude rules | CLAUDE.md (imports AGENTS.md on line 1), .claude/operating-rules.md, nested scripts/CLAUDE.md and ci/CLAUDE.md, .claude/rules/ (backend.md, frontend.md, tests.md, api-compat.md, docs.md, claude-config.md, ux-copy.md, specs.md), reference material in docs/harness/, global-claude-md.example (optional) |
The Claude Code workflow on top of the contract: skills, agents, hooks, the fast-path gate chain. Claude reads these automatically; nested files load only for their folder, and a rule file loads only when Claude works with a file matching its paths: globs |
| Personas | .claude/personas.md |
The users /voc, /voc-audit, and /sunset-check role-play |
| Security invariants | .claude/security-invariants.md |
Cross-surface security rules architect, rbac-check, security-review, and threat-model check against — see Security invariants registry |
| CI pipeline | .gitlab-ci.yml, ci/*.yml |
Governance jobs out of the box, plus stack templates — see CI pipeline |
| Git hooks | hooks/, scripts/setup-hooks.sh |
Pre-commit: secret scan, format-check, lint, typecheck. Pre-push: make pre-push-checks |
| Behavioral evals | evals/, ci/evals.yml, scripts/check-evals.py, scripts/run-evals.sh, scripts/eval-plugin-dir.sh, scripts/eval-trend.py |
Planted-defect cases that score the agents and skills with claude plugin eval, with and without them loaded; a free lint on every MR and a paid weekly run. Ships in 0.8 — see Evaluating the harness |
| Check scripts (gates) | scripts/check-*, scripts/osv-severity-gate.sh, scripts/gitleaks-precommit.sh, load-bearing.declarations, .gitleaks.toml |
Checks that each prove they can still fail — see Harness gates |
| Optional templates | scripts/templates/check-served-assets.sh |
Copy-in smoke check that a built single-page-app image serves its own assets; a template, not a gate Blueprint runs on your code. Only its --self-test runs in CI — see Served-assets smoke test |
| Parallel work | scripts/wt |
One worktree per issue, safe with several sessions at once — see Parallel work |
| Changelog | changelog.d/, scripts/assemble-changelog.sh |
One-line fragments per MR, assembled at release |
| Release | scripts/release.sh, scripts/release-notes.sh, docs/releases/ |
Version bump, changelog assembly, per-release notes |
| Templates | .gitlab/issue_templates/, .gitlab/merge_request_templates/ |
Bug, Feature, Feedback, and Task issues; a standard MR description |
| Specs | docs/specs/, scripts/check-spec-completeness.py, scripts/spec-rules/ |
Product specs, their template, and the completeness gate that decides whether a spec can become issues — see Spec-driven development |
| ADRs | docs/adr/ |
Architecture Decision Records, created with /adr |
| Docs site | website/ |
This site (Astro Starlight → GitLab Pages). The reset deletes it by default; --keep-website keeps a stub as a starting point for yours |
| Dependency updates | renovate.json, .github/dependabot.yml |
Automated update MRs — keep one, delete the other |
| Setup | Makefile, scripts/customize.sh, scripts/doctor.sh, scripts/gitlab-bootstrap.sh, scripts/blueprint-status |
make setup, make customize (setup checklist), make status (lifecycle checklist: Configure → Specify → Plan → Build → Release, ships in 0.8), make doctor (prerequisites), and /kickoff’s GitLab bootstrap (project, settings, protections, labels, seed issues) |
| Conventions | CONTRIBUTING.md, .gitattributes, .env.example |
Branch and commit rules, line endings, example environment |
Removing what you don’t need
Section titled “Removing what you don’t need”- No frontend? Delete
ci/node.yml, the node blocks in theMakefile,frontend/, and theux-design,ux-review, andaccessibilityagents. If you don’t ship a single-page-app image, also deletescripts/templates/check-served-assets.shtogether with its--self-testlines in thetooling-self-testsjob of.gitlab-ci.ymland in thegate-self-teststarget of theMakefile; deleting only the script fails CI. - No HTTP endpoints? Delete the
rbac-checkagent and thepre-mr-security-gate.shhook (and itsPreToolUseentry in.claude/settings.json). Delete its eval cases too,evals/review/authz-detail-idor/,evals/review/grant-path-parity/,evals/review/grant-path-shared-helper/,evals/review/grant-path-clean-control/andevals/review/rbac-clean-control/: with the agent gone they can only fail. The same holds for any agent or skill you delete.grep -rl '<name>' evals/finds its cases. - Not running the behavioral evals? Delete
evals/(both ofci/evals.yml’s jobs then skip themselves), or deleteci/evals.yml, its include line in.gitlab-ci.yml, the fourscripts/*eval*scripts,scripts/tests/eval-trend/, and their lines in theMakefile,tooling-self-testsandload-bearing.declarations. - No public API contract yet? Delete
.claude/rules/api-compat.mdand the Backward compatibility section ofAGENTS.md. - No docs site? Nothing to do after the reset: it deletes
website/by default, and thewebsite:buildandpagesjobs skip themselves without it. (ci/docs.ymlcan stay — it does nothing without a docs site.) Without the reset, deletewebsite/by hand. - No Helm chart? Leave
ci/helm.ymlcommented out, or delete it. - No CI? Delete
.gitlab-ci.ymlandci/. The changelog and hooks still work locally. - No Claude Code? Delete
.claude/,evals/andglobal-claude-md.example, and remove the@.claude/operating-rules.mdimport line fromCLAUDE.md. KeepAGENTS.md: it is the whole project contract, and tools that follow theAGENTS.mdconvention read it directly. KeepCLAUDE.mdtoo:scripts/gate-yield.py --check-fastpath, which CI runs, reads its fast-paths table. Everything else works on its own. What another agent does and does not get: Agent portability. - Different license? Replace
LICENSE. - GitHub instead of GitLab? Move
.gitlab-ci.ymlto.github/workflows/and.gitlab/to.github/; the scripts already useghwhenoriginis on GitHub. Deleterenovate.jsonand keep.github/dependabot.yml(scripts/customize.sh --reset-template --githubdoes this). - GitLab (the default)? Delete
.github/dependabot.yml; keeprenovate.json(scripts/customize.sh --reset-template --gitlabdoes this).
Yes, but: before deleting a check script, look for it in load-bearing.declarations
and the Makefile’s pre-push-checks list. Deleting a gate cleanly means removing its
callers too.
Suggested enhancements
Section titled “Suggested enhancements”| Add | What it gives you | When |
|---|---|---|
| Per-path CODEOWNERS rules | Automatic reviewer assignment by path (/kickoff already writes a root CODEOWNERS with a default owner) |
More than two people with distinct areas |
| Container image scanning | CVE scanning of built images (Trivy, GitLab container scanning) | Shipping containers to production |
| Language vulnerability jobs | pip-audit / npm audit alongside osv-scan |
You want the ecosystem’s native advisories too |
| A richer MR template | Migration notes, deploy impact, rollback plan | Deploys with migrations or several services |
| Approval rules | N approvals before merge, per-path overrides | A formal review process |
| Merge trains | GitLab’s server-side merge queue | main breaks often from concurrent merges (/mass-merge is the client-side version) |
Choosing where to deploy is a separate question — see Deployment options.
Go deeper: the file tree
Section titled “Go deeper: the file tree”⛔ marks a skill only you can start (disable-model-invocation: true).
.├── .claude/│ ├── agents/ # the agents — see the Agents page│ │ ├── accessibility.md # WCAG 2.1 AA (sonnet, read-only)│ │ ├── architect.md # technical approach before code (opus)│ │ ├── changelog.md # writes the changelog fragment (sonnet)│ │ ├── completeness-check.md # fresh-agent audit of branch vs. issue, before push (opus by default; opus or sonnet by risk tier under /wave)│ │ ├── dependency.md # license/CVE/justification before adding a package (sonnet)│ │ ├── docs.md # writes and updates docs (sonnet)│ │ ├── generated-artifact-check.md # stale schemas, types, SDKs (sonnet)│ │ ├── perf-check.md # N+1, unbounded queries (sonnet, read-only)│ │ ├── rbac-check.md # access control on endpoints (opus, read-only)│ │ ├── regression-check.md # what this breaks that used to work (sonnet)│ │ ├── schema-check.md # migration safety, before push (sonnet)│ │ ├── security-review.md # OWASP Top 10 + project risks (opus; /wave runs it on sonnet)│ │ ├── spec-review.md # semantic review of a draft spec (opus, read-only, report-only)│ │ ├── test-scaffold.md # tests for uncovered code (sonnet)│ │ ├── threat-model.md # trust boundaries, before code (opus)│ │ ├── ux-design.md # UI proposal, before code (opus)│ │ └── ux-review.md # design-system compliance (sonnet, read-only)│ ├── skills/ # the skills — see the Skills page│ │ ├── adr/SKILL.md # /adr│ │ ├── ci-debug/SKILL.md # /ci-debug│ │ ├── conventions-review/SKILL.md # /conventions-review (was /review)│ │ ├── dotplanning/ # /dotplanning ⛔│ │ │ ├── SKILL.md│ │ │ ├── kickoff-questions.md # the twelve kickoff questions│ │ │ └── html-output-spec.md # report layout│ │ ├── fix-mr/SKILL.md # /fix-mr ⛔│ │ ├── import-design/SKILL.md # /import-design│ │ ├── import-spec/SKILL.md # /import-spec ⛔ (deprecated alias of /spec import)│ │ ├── incident-postmortem/SKILL.md # /incident-postmortem│ │ ├── kaizen/SKILL.md # /kaizen│ │ ├── kickoff/ # /kickoff ⛔│ │ │ ├── SKILL.md│ │ │ └── stack-map.md # stack and answer → file edits│ │ ├── mass-merge/ # /mass-merge ⛔│ │ │ ├── SKILL.md│ │ │ └── failure-modes.md # failure modes and recovery│ │ ├── memory-audit/SKILL.md # /memory-audit ⛔│ │ ├── mr/SKILL.md # /mr ⛔│ │ ├── next/SKILL.md # /next│ │ ├── pre-release/SKILL.md # /pre-release│ │ ├── release/SKILL.md # /release ⛔│ │ ├── spec/ # /spec ⛔│ │ │ ├── SKILL.md # commands, bare dispatch by status, aliases│ │ │ └── reference/│ │ │ ├── interview.md # new, resume, audit, revise│ │ │ └── import.md # import, --dry-run, re-import diff│ │ ├── spec-intake/SKILL.md # /spec-intake (deprecated alias of /spec)│ │ ├── sunset-check/SKILL.md # /sunset-check│ │ ├── tracker-hygiene/SKILL.md # /tracker-hygiene│ │ ├── voc/SKILL.md # /voc│ │ ├── voc-audit/SKILL.md # /voc-audit ⛔│ │ └── wave/SKILL.md # /wave ⛔ (was /batch)│ ├── hooks/│ │ ├── context-nudge.sh # Stop hook: tells you once when context passes a threshold (ships in 0.8)│ │ ├── on-stop.sh # Stop hook: blocks until `make test-scoped` ran (silent on the stub)│ │ ├── post-edit-checks.sh # reminders after an edit│ │ ├── post-mr-cost.sh # PostToolUse: posts the MR's cost record after `glab mr create`│ │ ├── pre-mr-security-gate.sh # stops `glab mr create` until security reviews ran│ │ ├── pre-tool-agent-budget.sh # PreToolUse: stops a /wave implementer past 120 tool calls (ships in 0.8)│ │ ├── pre-tool-safety.sh # blocks lock-file and migration edits│ │ └── session-start-status.sh # SessionStart: one progress line (ships in 0.8)│ ├── cost-ledger.json # cost ledger setting: on or off (write it with scripts/cost-ledger)│ ├── model-prices.json # dated list-price table scripts/est-cost.py reads for est-cost-usd:│ ├── kaizen-declined.json # /kaizen proposals you've turned down│ ├── operating-rules.md # gate reference + cross-cutting rules, imported by CLAUDE.md│ ├── personas.md # your users (replace the examples)│ ├── rigor.json # the rigor floor: paths whose MRs run at strict or strict-light (add your migrations and auth code)│ ├── rules/ # path-scoped rules: backend, frontend, tests, api-compat, docs, claude-config, ux-copy, specs│ ├── security-invariants.md # cross-surface security rules (replace the examples)│ └── settings.json # hooks, allowed and denied commands├── .github/dependabot.yml # GitHub dependency updates (delete on GitLab)├── .gitlab/│ ├── issue_templates/ # Bug.md, Feature.md, Feedback.md, Task.md│ └── merge_request_templates/ # Default.md├── changelog.d/README.md # fragment naming guide├── ci/│ ├── CLAUDE.md # rules for editing CI (imports scripts/CLAUDE.md)│ ├── cloudflare-deploy.yml # marketing-site deploy template (opt-in, fully commented out)│ ├── docker.yml # kaniko build, compose project names│ ├── docs.yml # internal docs link check (included by default)│ ├── go.yml # golangci-lint, go test, govulncheck│ ├── helm.yml # chart registry drift, install/upgrade drills│ ├── mutation.yml # optional nightly mutation gate (mutmut example, off by default)│ ├── node.yml # eslint, vitest, license check, added-file coverage│ ├── python.yml # ruff, pytest, license check, app-aware gates, fuzz, load test│ ├── sonar-complexity.yml # cognitive-complexity tier (off by default)│ ├── sonar-exclusions.yml # Sonar ignore-criteria rule-key check (off by default)│ └── trivyignore-expiry.yml # .trivyignore expiry-date check (off by default)├── docs/│ ├── adr/ # ADR format guide, seed ADR, and Blueprint's own ADRs│ ├── harness/ # reference moved out of CLAUDE.md and operating-rules.md: Claude Code config, branching, agent workflow, milestone labels, the rigor floor, VoC, memory and mass-merge rules│ ├── specs/ # product specs, TEMPLATE.md and a sample, checked by check-spec-completeness.py│ └── releases/ # Blueprint's own release notes (replace with yours)├── hooks/│ ├── pre-commit # secret scan, format-check, lint, typecheck (each if defined)│ └── pre-push # make pre-push-checks├── scripts/│ ├── CLAUDE.md # rules for writing check scripts│ ├── lib/│ │ ├── codeowners-locations.sh # where a CODEOWNERS file counts (customize.sh and the /kickoff writer share it)│ │ ├── git-hooks-dir.sh # finds the real hooks folder (works in worktrees)│ │ └── git-ignored.sh # lets checks skip ignored files, like CI's clean clone│ ├── spec-rules/ # data for the spec gate: section aliases, vague terms, verdict schema│ ├── tests/ # tests for wt, setup, onboarding, the security hook, app-aware gates│ ├── adr-accepted-issue-sweep.py # open issues written before the ADR they cite (or the spec D-nn)│ ├── assemble-changelog.sh # fragments → CHANGELOG.md│ ├── check-added-files-covered.mjs # a new source file missing from the coverage report│ ├── check-artifact-assertions.sh # tag jobs assert their artifacts aren't empty│ ├── check-chart-registry.sh # the published Helm chart installs as documented│ ├── check-cognitive-complexity.py # complexity tier for script entry points│ ├── check_mutation_score.py # mutation gate: merge shards, score floor, fails closed│ ├── check-compose-project-names.sh # each compose file pins its own project name│ ├── check-docs-internal-links.py # docs links, anchors, and assets resolve│ ├── check-edition-boundary.sh # the open-source tree never names the enterprise package (open core)│ ├── _paths.py # shared path-containment helper (resolve_within)│ ├── mutmut_export.py # mutmut 2.x cache to shard JSON (mutation gate adapter)│ ├── mutmut_config.py.example # shard hook for the mutation gate│ ├── check-gate-selftest-parity.sh # every gate self-tests in its own CI job│ ├── check-issue-collision.sh # blocks a duplicate MR for an issue│ ├── wave-preflight.py # /wave: is this issue already done on main?│ ├── wave-resume.py # /wave: classify leftover claims and worktrees│ ├── cost-ledger # reads and writes the cost ledger setting (on, off, status)│ ├── orchestrator-tokens.py # /wave: sums the orchestrating session's token usage for a branch│ ├── subagent-tokens.py # /wave: sums the branch's subagents' token usage, descendants included│ ├── est-cost.py # /wave: prices the branch's token usage at list prices (est-cost-usd:)│ ├── cost-table.py # renders and posts the numbered ## Cost of this MR comments│ ├── post-mr-cost.py # the only code that measures and posts them (hook, --round, --measure)│ ├── check-load-bearing.sh # declared one-line guards still exist│ ├── check-memory-index.sh # Claude memory index size and dead links│ ├── check-migration-numbering.sh # migration numbers that collide on the merged tree│ ├── check-mr-followups.sh # a declared follow-up must cite an open issue│ ├── check-spec-trace.sh # imported specs and their issues must trace both ways│ ├── check-gate-ledger.py # MR `## Gates` outcomes must be parseable│ ├── check-rigor-floor.py # an MR touching the rigor floor must record strict or strict-light and its gate lines│ ├── check-ci-include-all.py # CI files parse with every include enabled│ ├── check-nul-bytes.sh # no NUL bytes in text files│ ├── check-prepush-parity.sh # every CI gate can also run before push│ ├── check-release-pipeline.py # a tag can't publish unless every job at its commit passed│ ├── check-security-deferred.sh # every issue that ever carried security::deferred is resolved│ ├── check-spec-completeness.py # a spec under docs/specs/ is complete enough to become work│ ├── check-single-fastpath-table.sh # one fast-paths table; no rule heading in both AGENTS.md and CLAUDE.md│ ├── check-serializer-ts-parity.py # backend schema and TypeScript types agree│ ├── check-shellcheck.sh # every shell script passes shellcheck│ ├── check-sigpipe-readers.sh # no early-exit reader behind a pipe│ ├── check-shell-portability.sh # no BSD-only or GNU-only shell idiom (stat/sed -i/date/grep -P ...)│ ├── check-cc-claims.sh # Claude Code claims need a doc link + checked date│ ├── check-skill-names.sh # no skill shadows a Claude Code built-in name or alias│ ├── check-commands-doc.py # every skill has a commands.md entry with Before this:/Next:│ ├── check-agent-contract.sh # agent "Do not use" clauses, one severity scale│ ├── check-claudemd-size.sh # no CLAUDE.md over 200 lines (allowlist: claudemd-size-allowlist.txt), byte budget: claudemd-byte-budget.txt│ ├── check-stale-references.sh # stale-reference rules (see harness-gates)│ ├── check-tag-only-jobs.sh # tag-only CI jobs changed since the last tag│ ├── check-version-lockstep.py # every version-bearing file agrees│ ├── check-yaml-duplicate-keys.py # no repeated key in .gitlab-ci.yml or ci/*.yml│ ├── check-bare-issue-refs.py # no bare #NNN Blueprint issue reference in shipped files│ ├── check-harness-reference.py # every hook, scripts/wt subcommand and make target has a reference-page entry│ ├── check-docs-stale.py # no doc quotes a make target, script or flag that no longer exists│ ├── check-ws-event-reachability.py # published real-time events are actually reachable│ ├── blueprint-status # make status: the lifecycle checklist (Configure → Specify → Plan → Build → Release) and --json / --require for skills│ ├── ci-assert-artifacts.sh # helper: fail a publish job with an empty artifact│ ├── customize.sh # setup checklist; --init starts the repo│ ├── detect-stack.py # /kickoff's stack detection: proposes Makefile recipes, the CI include and rules globs as a diff; writes only on a confirmed plan id│ ├── doctor.sh # prerequisite check│ ├── gate-yield.py # per-gate yield, escapes and cost from the MR ledger; --by-model: yield per gate and model; --spec-trace: spec-intake yield│ ├── gitleaks-precommit.sh # secret scan for the pre-commit hook│ ├── gitlab-bootstrap.sh # /kickoff's GitLab project, settings, protections, labels and seed issues│ ├── helm-install-drill.sh # install + upgrade the chart on a real kind cluster│ ├── kickoff-state.py # /kickoff's saved answers per round (.claude/state/kickoff.json), so a re-run resumes│ ├── mr-verdict.py # one MR's verification verdict from its Gates/Requirements│ ├── nightly_load_test.py # p95 latency budgets│ ├── osv-severity-gate.sh # fail on dependency CVEs above a threshold│ ├── release-notes.sh # docs/releases/<version>.md│ ├── release.sh # version bump + changelog assembly│ ├── schemathesis_hooks.py.example # starter hooks for the schema fuzz job│ ├── security-deferred-verdict.sh # accepted-risk note verdict: regex, calendar, expiry│ ├── setup-hooks.sh # installs hooks/ into Git│ ├── templates/│ │ └── check-served-assets.sh # optional template, not a gate: an SPA image serves its own assets (self-test runs in CI)│ ├── write-ownership-files.sh # /kickoff's CODEOWNERS, SECURITY.md, support line and LICENSE copyright line│ ├── write-edition-boundary.sh # /kickoff's Open core follow-up: writes edition-boundary.conf│ └── wt # worktree helper: issue check-out lock, private `wt stash`├── website/ # this docs site├── .env.example├── .gitattributes # line endings, merge strategies, binary detection├── .gitignore├── .gitlab-ci.yml # governance CI + stack includes├── .gitleaks.toml # secret-scan config and allowlist├── CHANGELOG.md├── AGENTS.md # project contract for any coding agent├── CLAUDE.md # Claude Code workflow; imports AGENTS.md on line 1├── CONTRIBUTING.md # contributor workflow├── LICENSE # Apache 2.0 (change if you like)├── Makefile # setup, customize, doctor, lint, test, build, checks├── README.md├── global-claude-md.example # optional personal-preferences template├── load-bearing.declarations # one-line guards that must not disappear├── nightly-load-test-budgets.json # latency budgets for the load test└── renovate.json # GitLab dependency updates (delete on GitHub)