mck-scaffold
Interview-driven project scaffolder for Claude Code. Picks the right Spec-Driven Development methodology for your project — instead of installing the most popular one.
Status: v0.18.0 — harness live for 6 methodologies; brownfield install merge + --dry-run; /mck-scaffold:uninstall (full teardown or per-methodology); downgrade detection; per-methodology upstream.json pinning + drift log; --run-upstream[=SUBSET] auto-invokes upstream tools (all picked, or comma-separated subset); scripts/apply_research_drift.py bulk-applies upstream pin bumps from a structured drift document (the research-refresh SKILL's output); routing as canonical JSON via scripts/route.py; picker SKILL auto-chains into /mck-scaffold:init. 195 scenarios pass across 10 test suites. v1.0 ships after manual /mck-scaffold:init dogfood from a real Claude Code session.
What it does
You run /mck-scaffold:init in a project folder. It:
- (Step 0) Reads
research/last-run.json and offers to refresh the framework catalog if it's stale (skip-default if < 30 days, neutral 30–90, strongly-recommended-default > 90).
- (Steps 1–6) Walks you through an 8-question interview, applies Piskala's three-level rigor taxonomy + Wasowski's four decision contexts, routes deterministically to a methodology preset (Superpowers / Spec-Kit / MUSUBI / OpenSpec / BMAD / lean), and shows a confirmable decision summary.
- (Step 7) Composes your project's
CLAUDE.md, AGENTS.md, .claude/settings.json, and docs/decisions/{INTERVIEW,METHODOLOGY}.md from shared base + methodology fragment + stack adapter, with full conflict resolution on existing files.
- (Step 8) Auto-runs the upstream framework install (
specify init, npx musubi-sdd init, openspec init, etc.) — not a manual step, the scaffolder does it.
- (Step 9) Prints a final summary including any post-install advisories the upstream tool surfaced (e.g., Spec-Kit's
.claude/ credentials-gitignore note).
The interview is the product. The templates are commodity. The research pipeline keeps both fresh.
What gets installed (the neuro-symbolic harness)
Picking a methodology drops a deterministic enforcement layer into your project — not just markdown rules telling Claude to be disciplined, but actual hook scripts that make undisciplined actions fail.
Each methodology ships its own hook flavor; they all share the same harness primitives (_core.py, .claude-harness/profile, docs/audit-log.jsonl):
| Methodology | Hook | Refuses |
|---|
L1-spec-kit | spec_gate + spec_shape + task_proof | Edits to src/* without a covering spec; malformed spec frontmatter; edits whose covered test no longer passes |
L1-superpowers | hardgate_check + tdd_check | src/* edits without an approved design marker; new source files without a sister test |
L1-bmad | prd_gate | src/* edits without a PRD under docs/prd/ referencing the file |
L2-csdd-security | secret_gate | Edits introducing 12 credential patterns (AWS keys, GitHub PATs, JWTs, hardcoded passwords, etc) |
L2-musubi | traceability_gate | Edits to files not present in docs/traceability.md (Article V) |
L2-openspec-brownfield | proposal_gate | Edits to files not referenced by any active proposal in openspec/ |
L1-lean | (none, by design) | The lean preset opts out of harness enforcement |
L3-watch | (info-only) | Drops docs/horizon/L3-WATCH.md |
One strictness dial at .claude-harness/profile (one word): warn (advisory), block (refuse + audit), strict (block + audit + CI parity). The same file controls every methodology installed in the project.
Stack templates ship their own strictness baselines that drop at the project root (skipped if already present):
python → pyproject.toml with strict ruff (15+ rule groups) + strict mypy + pytest --strict-markers + coverage gatedotnet → Directory.Build.props with Nullable=enable + TreatWarningsAsErrors + AnalysisLevel=latestangular → tsconfig.strict.json + .eslintrc.cjs with strict-type-checked + Angular strict templates
All harness events flow to a single chronological JSONL audit log at docs/audit-log.jsonl, keyed by hook name (spec_gate.block, secret_gate.block, traceability_gate.block, etc) — one source of truth for "what got blocked, when, why." Every install / remove / uninstall event records the plugin version (mck_scaffold_version) and the per-methodology upstream pin (pinned_upstream_versions), so the audit log alone tells you exactly which versions a project has had over time.
Why
The agentic-coding ecosystem (mid-2026) has 15+ SDD frameworks. Adoption is bimodal — Superpowers (~166k stars) and Spec-Kit (~90k) dominate popularity; MUSUBI (28 stars) and CSDD (academic) dominate formal rigor. Choosing the wrong end of this spectrum is the most common dysfunction in real deployments.
