From mck-scaffold
> **Status:** Phase 7 — fully functional. Runs the interview (Steps 1–6), then executes scaffolding (Step 7), triggers upstream installs (Step 8), and prints the final summary (Step 9). Acceptance: same answers always produce the same target-project files; re-runs are idempotent.
How this skill is triggered — by the user, by Claude, or both
Slash command
/mck-scaffold:initThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> **Status:** Phase 7 — fully functional. Runs the interview (Steps 1–6), then executes scaffolding (Step 7), triggers upstream installs (Step 8), and prints the final summary (Step 9). Acceptance: same answers always produce the same target-project files; re-runs are idempotent.
Status: Phase 7 — fully functional. Runs the interview (Steps 1–6), then executes scaffolding (Step 7), triggers upstream installs (Step 8), and prints the final summary (Step 9). Acceptance: same answers always produce the same target-project files; re-runs are idempotent.
Step 0: research-refresh staleness check (NEW in v0.11.0)
Step 1: detect project context
Step 2: load interview definition (questions.md + routing.md)
Step 3: run interview (Q1–Q8 with pruning)
Step 4: apply routing (deterministic lookup)
Step 5: produce decision summary
Step 6: confirm or iterate
─────────── confirmation point ───────────
Step 7: execute scaffolding (compose + write files)
Step 8: trigger upstream installs (auto, not optional — Phase 11 contract)
Step 9: final summary + manual-steps callout
Steps 0–6 do not write to the target project. Step 0 may write to mck-scaffold itself if user opts in to a research refresh. Steps 7–8 write to the target project.
New in v0.11.0. Surface upstream-ecosystem drift before routing decisions get made against a stale catalog. The dogfood on
consultant-helper(2026-05-15) immediately surfaced Spec-Kit drift less than 30 days after the catalog was written — staleness is real and routing against stale data produces broken installs.
Read research/last-run.json from the plugin root. Extract timestamp_iso and compute days_since against today.
Render an appropriate prompt based on staleness:
| Staleness | Prompt tone |
|---|---|
| < 30 days | Brief, skip-by-default: "Catalog refreshed {days_since} days ago — fresh. Skipping refresh by default. Pass --refresh to override." |
| 30–90 days | Neutral: "Catalog refreshed {days_since} days ago. Refresh before this scaffold? It catches upstream drift (~5-10 min, 4 parallel research streams)." |
| > 90 days | Strong: "Catalog refreshed {days_since} days ago — drift is likely. Strongly recommended to refresh before this scaffold. Skip only if you've verified the framework you expect to route to hasn't shifted." |
Use AskUserQuestion with options sized to the staleness tone:
< 30 days → ["Skip refresh, proceed to interview" (default), "Force refresh anyway"]30-90 days → ["Refresh first (recommended)", "Skip refresh — proceed to interview"]> 90 days → ["Refresh first (strongly recommended)" (default), "Skip — proceed without refresh"]If user opts to refresh:
Invoke the research-refresh skill conversationally. It will run its own pipeline (4 parallel research streams → diff → per-section confirm → apply). When it completes, return here and proceed to Step 1.
If user opts to skip:
Proceed directly to Step 1. The current catalog state in research/streams/*.md and interview/routing.md will drive the routing.
Argument handling at Step 0:
--refresh — force the refresh prompt regardless of staleness (useful for "I know there was a release yesterday, re-check anyway")--no-refresh — skip Step 0 entirely without prompting (useful for scripted / CI invocations)If neither flag is passed, follow the staleness-tone logic above.
Run these checks in the current working directory and report what you found:
.git/ exist?CLAUDE.md exist?.claude/ exist?.specify/, docs/constitution.md with MUSUBI banner, openspec/, docs/superpowers/, ~/.claude/plugins/.../superpowers/.docs/decisions/INTERVIEW.md exist? This is the re-run indicator.Print a one-line context summary, e.g.:
Detected:
.gitpresent, no existing CLAUDE.md, no prior SDD framework. Treating this as a fresh init in an existing repo.
If docs/decisions/INTERVIEW.md is present, route to the re-run subroutine (see "Idempotency" near the end). Do NOT proceed with a fresh interview when a prior scaffold record exists.
Read these files from the plugin root (the directory containing .claude-plugin/plugin.json):
interview/questions.md — Q1–Q8 question tree, options, pruning rulesinterview/routing.md — answer-combination → preset routing table + install command listThese are the source of truth. If their content conflicts with anything in this SKILL.md body, the markdown files win.
For each question Q1–Q8 (respecting pruning):
interview/questions.md.AskUserQuestion call using the verbatim wording.multiSelect: true; all others single-select.brownfield, skip Q3 and Q4.≠ d, skip Q8.AskUserQuestion call. Never batch.Record answers in a running dictionary.
Read interview/routing.md. Match answers against the primary routing table — this is a deterministic lookup, not a judgment call. Resolve:
methodology_preset: one of L1-lean, L1-spec-kit, L1-superpowers, L2-musubi, L2-openspec-brownfieldmethodology_overlays: zero or more of L2-csdd-security, L3-watchstack_adapters: from Q5 (each selected stack name, e.g., dotnet, angular, unity, python)mcp_orientation: yes/no from Q6multi_agent_appetite: none/limited from Q7install_commands: from routing.md's "Meta-installer triggers per preset" table — collect commands for preset + each overlayIf the routing table has no exact match for the answer combination, that's a routing bug. Report it to the user and abort — do not silently pick a default.
Print the markdown block defined in Phase 2 (interview answers table, resolved methodology, rationale paragraphs, scaffolded-files preview, honest caveats from methodology-picker/SKILL.md). Do not write to disk yet.
After the decision summary, ask via AskUserQuestion:
"Does this routing look right?"
- Yes — proceed to scaffold and install. → continue to Step 7
- No — try a different preset. → surface 2 next-closest routing rows; user picks one; re-render summary
- Tweak an answer. → ask which question to revisit; rerun forward from there
- Dry-run only. → skip Steps 7-8; print "what would be written / installed" without writing
If --dry-run was passed as an argument, force the dry-run path.
Order matters. Compose files first (Steps 7a–7g), THEN run installs (Step 8). Some overlay operations (e.g., CSDD
constitution.append.md) must happen AFTER the methodology's install creates the base constitution — those are handled at the end of Step 8.
Define the variable dictionary first:
{{project_name}} = basename of cwd
{{project_path}} = absolute cwd
{{scaffold_date}} = today (ISO format YYYY-MM-DD)
{{mck_scaffold_version}} = from .claude-plugin/plugin.json "version"
{{re_eval_date}} = scaffold_date + 6 months
{{git_present}} = yes/no
{{prior_claude_md}} = yes/no
{{prior_claude_dir}} = yes/no
{{prior_sdd_markers_or_none}} = comma-separated detected markers or "(none)"
{{methodology_preset}} = from Step 4
{{methodology_overlays_or_none}} = csv or "(none)"
{{methodology_overlays_suffix}} = " with overlays X, Y" or ""
{{preset_one_liner}} = first sentence of methodologies/{preset}/README.md
{{stack_adapters_csv}} = csv from Q5
{{mcp_orientation}} = yes/no
{{multi_agent_appetite}} = none/limited
{{q1_answer}} ... {{q8_answer}} = verbatim option labels from questions.md
{{q5_answer_csv}} = csv of selected stacks
{{pruning_notes}} = e.g. "Q2 was 'brownfield', so Q3 and Q4 were skipped." or "No pruning applied."
{{user_notes_or_none}} = free-text "Other" notes from interview or "(none)"
{{rationale_paragraphs}} = generate from preset + answers (1-3 short paragraphs)
{{alternatives_list}} = next-closest routing rows as bulleted "not chosen because..." list
{{caveats_block}} = caveats from methodology-picker that apply to this preset
{{scaffolded_files_list}} = filled in as Step 7 progresses
{{installed_plugins_list}} = filled in as Step 8 progresses
From the plugin root:
templates/shared/CLAUDE.md.tmpltemplates/shared/AGENTS.md.tmpltemplates/shared/settings.json.tmpltemplates/shared/docs/decisions/INTERVIEW.md.tmpltemplates/shared/docs/decisions/METHODOLOGY.md.tmpltemplates/methodologies/{methodology_preset}/CLAUDE.append.mdtemplates/methodologies/{methodology_preset}/settings.merge.jsontemplates/methodologies/{overlay}/CLAUDE.append.md, settings.merge.json, and constitution.append.md if presentstack_adapters: templates/stack/{stack}/CLAUDE.append.md, settings.merge.jsonCache content in memory before any writes.
CLAUDE.md.tmpl, substituted.{{methodology_specific_content}} = methodology preset's CLAUDE.append.md, substituted. Append any overlay's CLAUDE.append.md, substituted, in routing order.{{stack_specific_content}} = concatenation of each stack adapter's CLAUDE.append.md, in Q5 selection order, each substituted.{{...}} placeholders remain. If any do, report a substitution gap and abort the write.Write to {{project_path}}/CLAUDE.md. See "Step 7h — write contract" for conflict handling.
Substitute variables on AGENTS.md.tmpl. Write to {{project_path}}/AGENTS.md.
.claude/settings.jsonStart with settings.json.tmpl. Deep-merge each layer's settings.merge.json in order: methodology → overlays → each stack (in Q5 selection order).
Merge rules:
permissions.allow and permissions.deny, deduplicate.Apply MCP overlay if mcp_orientation = yes (Phase 7 placeholder: leave hooks arrays as merged; MCP-specific allowlist fragment lands when MCP overlay template is built — currently a no-op).
Write the merged JSON to {{project_path}}/.claude/settings.json.
docs/decisions/INTERVIEW.mdSubstitute the shared INTERVIEW.md.tmpl with answers and project context. Write to {{project_path}}/docs/decisions/INTERVIEW.md.
docs/decisions/METHODOLOGY.mdBuild {{rationale_paragraphs}}, {{alternatives_list}}, {{caveats_block}} per the variable dictionary. {{scaffolded_files_list}} is the running list of files written so far. {{installed_plugins_list}} will be filled after Step 8.
Substitute and write to {{project_path}}/docs/decisions/METHODOLOGY.md. This file is updated again after Step 8 to fill in {{installed_plugins_list}}.
If L3-watch is in methodology_overlays, write templates/methodologies/L3-watch/horizon/L3-WATCH.md (substituted) to {{project_path}}/docs/horizon/L3-WATCH.md. (The L3-watch template ships in Phase 8.)
For each file about to be written:
| Situation | Action |
|---|---|
| Target file does not exist | Write. Add to scaffolded_files_list. |
| Target file exists, content matches what we would write | Skip silently. No-op. |
| Target file exists, content differs | Show a unified diff. AskUserQuestion: overwrite / skip / abort the whole scaffold. Default = skip. |
Never silently overwrite a file the user has changed. Mck-scaffold is opinionated about respecting user edits.
Read the install_commands resolved in Step 4. There are two command types:
These are auto-executed. Step 8a is not optional. After Step 6 confirmation, every bash-runnable install in the resolved preset's row of interview/routing.md runs via the Bash tool. Do not defer to "user runs this later" — the whole point of the scaffolder is that it scaffolds.
Reference the canonical install commands in interview/routing.md § "Meta-installer triggers per preset". For each:
$IsWindows (PowerShell) or uname -s (bash). Some preset install commands branch on this (e.g., Spec-Kit needs --script ps on Windows + UTF-8 env vars).$env:PYTHONIOENCODING = "utf-8" and $env:PYTHONUTF8 = "1" BEFORE invocation. Without this, Spec-Kit's banner crashes with UnicodeEncodeError on the default cp1252 codepage..specify/ already exists → conflictdocs/constitution.md with MUSUBI banner + .claude/skills/@orchestrator → conflictopenspec/ already exists → conflict--force handles the merge (most modern installers support this)--force (auto-install is the explicit Phase 11 contract; only escalate to user prompt if conflict detection finds something genuinely ambiguous)Bash tool with output captured. Apply long timeouts (180–600 seconds) — first-time uvx invocations download from GitHub which can be slow."<short description>" argument BEFORE the install runs — it's free-text and required..specify/, openspec/, docs/constitution.md). If markers missing, capture stderr and surface to user. Continue with the next install — don't abort the whole run for a partial failure..claude/ security advisory — if Spec-Kit ran, its post-install output recommends adding parts of .claude/ to .gitignore to prevent agent credential leakage. Append this note to the final summary (Step 9) so the user sees it./plugin install … is a Claude Code harness command, not a Bash command. A skill body cannot programmatically invoke another slash command. Surface them to the user explicitly:
⚠ Manual step required:
The following slash commands must be run in this Claude Code session to complete the install.
Please run each one and confirm before continuing:
/plugin install superpowers@claude-plugins-official
/plugin reload
Capture in installed_plugins_list regardless (with a (manual) marker). Trust that the user ran them.
Per DESIGN.md §10, the locked default is "pin to known-good; quarterly re-eval." In Phase 7, we do NOT yet hard-pin upstream versions — install commands use @latest or the marketplace's chosen version. Pinning lands as a Phase 7.1 iteration once known-good versions for each upstream are vetted.
If L2-csdd-security is in methodology_overlays:
docs/constitution.md exists in the target project (MUSUBI's npx musubi-sdd init creates it).templates/methodologies/L2-csdd-security/constitution.append.md (substituted).{{project_path}}/docs/constitution.md.scaffolded_files_list as "modified".If MUSUBI's install didn't create docs/constitution.md (failure, skipped, conflict), skip the append and surface a warning.
Re-substitute METHODOLOGY.md to fill in {{installed_plugins_list}}.
Print a closing markdown block:
✅ mck-scaffold complete.
## Files written
{scaffolded_files_list — relative paths}
## Plugins / commands installed
{installed_plugins_list — including `(manual)` slash-command items}
## Manual steps still required
{slash commands the user must run, if any — usually `/plugin install superpowers@...` + `/plugin reload`}
## Re-evaluation cadence
This methodology is recommended for review on **{{re_eval_date}}** (six months from today). At that point, re-run `/mck-scaffold:init` — it will detect this scaffold and offer reconfigure or diff.
## Next
1. Read `CLAUDE.md` — it's your project's authoritative conventions.
2. Read `docs/decisions/METHODOLOGY.md` — it's why this setup was chosen.
3. {preset-specific next step, e.g.:
- L1-superpowers: "Try `/superpowers:brainstorm` on your first feature."
- L1-spec-kit: "Try `/speckit.specify` on your first feature."
- L2-musubi: "Try `@requirements-analyst` to draft your first EARS spec."
- L2-openspec-brownfield: "Run `uvx shotgun plan` again if your codebase changes significantly."
}
When docs/decisions/INTERVIEW.md exists at Step 1:
methodology_preset from the file.--dry-run — force the dry-run path at Step 6 (skip Steps 7–8 entirely)--overlay=<name> — Phase 10 feature; Phase 7 echoes "(overlay support arrives in Phase 10)" and continues normally{{...}} placeholders remain in any target-project file after substitutiondocs/constitution.md is created--dry-run skips Steps 7–8 cleanly(manual) items)Write and Edit for file ops. Write creates parent dirs automatically.permissions.allow and permissions.deny; objects merge recursively; scalars overwrite.Bash installs:
--no-confirm flags speculatively — only when documented by the upstream tool..claude-plugin/plugin.json) at the start of Step 1. All template loads are relative to it.--- old, +++ new, hunks). Don't print giant files; truncate at ~200 lines and link to the source paths.Provides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
npx claudepluginhub mckruz/mck-scaffold --plugin mck-scaffold