| Getting Started & Learning | |
| "I'm new", "getting started", "how do I start", "first time" | Walk through setup and first workflow from getting started guide |
| "what is SDD", "spec-driven development", "methodology" | Explain SDD from methodology reference |
| "walk me through", "show me the workflow", "end to end" | Guide through the worked example in getting started — see "Your First Complete Workflow" |
| "best practices", "tips", "common mistakes", "anti-patterns" | Share guidance from best practices |
| Per-Command Coaching | |
| "help with specify", "how to write a spec", "specification tips" | Coach on /speckit-specify — detailed first prompt, user stories, P1/P2/P3 |
| "help with clarify", "when to clarify", "resolve ambiguities" | Coach on /speckit-clarify — when to run vs skip, evaluating recommendations |
| "help with plan", "planning", "implementation plan" | Coach on /speckit-plan — constitution gates, Phase 0 research, artifacts |
| "help with checklist", "validate requirements", "quality check" | Coach on /speckit-checklist — "unit tests for English", domain selection |
| "which checklists", "recommend checklists", "what domains" | Run /speckit recommend-checklists — analyze spec to recommend domains with enriched prompts |
| "help with tasks", "generate tasks", "task breakdown" | Coach on /speckit-tasks — user-story-first, [P] markers, independent testability |
| "help with analyze", "consistency check", "cross-artifact" | Coach on /speckit-analyze — severity levels, CRITICAL blocks, coverage gaps |
| "help with implement", "execute tasks", "start building" | Coach on /speckit-implement — checklist pre-check, TDD, phase execution |
| "help with constitution", "project principles", "governance" | Coach on /speckit-constitution — principle design, versioning, enforcement |
| Deep-Dive References | |
| "checklist domains", "what checklists", "which domains" | Guide domain selection from checklist guide |
| "constitution design", "good principles", "constitution tips" | Guide constitution design from constitution guide |
| "upgrade speckit", "update templates" | Provide upgrade guidance from command guide — see "Upgrade Guidance" |
| Plugin Usage | |
| "install codex agents", "subagents missing", "repair codex install", "refresh codex agents" | Route to the SpecKit Pro Codex install skill. Explain that speckit-autopilot and speckit-coach still own skill-local agents/openai.yaml metadata sidecars, but real custom agents register from .codex/agents/*.toml or ~/.codex/agents/*.toml, so the install skill copies the bundled codex-agents/*.toml templates into place and the user must restart Codex afterward. |
| "run autopilot", "execute workflow", "autonomous" | Guide to $speckit-autopilot — prerequisites, workflow file setup, and autonomous execution. See autopilot guide |
| "check status", "where am I", "workflow progress", "what's next", "roadmap", "project health" | Guide to $speckit-status for technical roadmap progress (completed, ready, blocked specs), or $speckit-doctor for project health diagnostics ($speckit-doctor requires the doctor extension — install via specify extension add doctor) |
| "roadmap map", "home note", "Map of Content", "roadmap-MOC", "navigation", "how is the home note structured", "curated vs generated zone", "two-zone", "can I edit the INDEX", "cap epics" | Explain the roadmap-MOC home note's two-zone structure from roadmap-MOC guide — the curated epics zone is hand-authored/editable, the GENERATED INDEX zone is machine-regenerated by runner operation generate-spec-index-write and never hand-edited, and the cap-epics-below-~10 guardrail is advisory (warns, never blocks) |
| "fix up this speckit-pro project", "repair existing SpecKit project", "make template edits durable", "template customizations got overwritten", "upgrade-safe templates", "reviewability preset repair" | Run the Project Fixup workflow below. Audit .specify, migrate reviewability-related direct core template edits into a project-local preset, verify specify preset resolve, preserve host PR templates, and restore core templates only from a reviewed source. |
| "configure autopilot", "settings", "consensus mode" | Guide to .claude/speckit-pro.local.md settings (project-relative path, works on both Claude Code and Codex) — consensus mode, auto-commit, gate failure behavior. See autopilot guide |
| "how does consensus work", "clarify automation" | Explain the 3-agent consensus protocol — codebase-analyst, spec-context-analyst, domain-researcher. See autopilot guide |
| "gap remediation", "checklist automation" | Explain checklist gap remediation loop — consensus agents propose fixes, auto-edit, re-verify. See autopilot guide |
| "analyze automation", "finding remediation" | Explain analyze remediation loop — CRITICAL/HIGH findings auto-fixed via consensus. See autopilot guide |
| "PR automation", "review loop", "copilot review" | Explain the post-PR review remediation loop — polling, auto-fix, comment resolution. See autopilot guide |
| "branching", "worktree", "SPECIFY_FEATURE" | Explain branch detection hierarchy — env var → git branch → specs/ scan. See autopilot guide |
| Presets & Extensions (v0.8.x) | |
| "preset", "customize templates", "override templates", "methodology" | Explain presets — stackable template overrides, resolution order, commands. See presets & extensions guide |
| "extension", "add extension", "install extension", "community catalog" | Explain extensions and use the live catalog playbook. See presets & extensions guide — "Browsing the live catalog" section. |
| "what extensions are available", "search extensions", "find an extension for X", "browse extensions", "list community extensions" | Run Play 1 — Discovery: specify extension search [keyword] (fallback to gh api against catalog.community.json, then WebFetch the raw URL). Render results grouped by category. See presets & extensions guide — "Browsing the live catalog". |
| "tell me about the X extension", "info on X extension", "what does X extension do", "details on X extension" | Run Play 2 — Deep dive: specify extension info <id>. Fallback: fetch the extension's own extension.yml from its repo via gh api or WebFetch and read out provides.commands, hooks, requires.speckit_version, tags. Cross-reference against specify --version. |
| "install X extension", "add the X extension", "remove X extension", "disable an extension", "enable an extension", "configure an extension" | Run Play 3 — Install / configure / remove. Always confirm with the user before mutating. Use specify extension add/remove/enable/disable/set-priority. Every install / configure / hook-wiring response MUST end with a two-line closing block, verbatim — do not paraphrase, do not skip, even if the rest of the response is long:
**No plugin update or restart needed** — the autopilot re-reads .specify/extensions.ymlat every phase boundary, so any hook you wire here fires on the next autopilot run. Noclaude/codexrestart, no/plugin marketplace update, no session reload.
**Two config files to know:** .specify/extensions//-config.yml(shared, commit to git) and.specify/extensions//-config.local.yml (personal, gitignored).
If the extension should fire automatically at a phase boundary, register it in .specify/extensions.yml. |
| "archive extension", "Archive Sweep", "archive cleanup", "spec graveyard", "remove merged specs", "provenance" | Explain the Racecraft archive extension path: install or vendor racecraft-lab/spec-kit-archive from a pinned tag/commit, run Archive Sweep at autopilot startup, exclude the current target spec, keep unsafe checkouts dry-run-only, and clean active specs/** only after archive success plus recovery commands. |
| "hook events", "after_implement", "before_specify" | Explain the 8 hook events and how extensions use them. See presets & extensions guide |
| "template resolution", "which template", "preset resolve" | Explain 4-tier resolution: overrides > presets > extensions > core. See presets & extensions guide |
| "catalog", "custom catalog", "extension catalog", "preset catalog" | Explain multi-catalog stacks, custom catalogs, env vars. See presets & extensions guide |
| "doctor", "project diagnostics", "health check" | If the doctor extension is installed, run $speckit-doctor for full project diagnostic (structure, agents, features, scripts, extensions, git); install via specify extension add doctor. See presets & extensions guide |
| "upgrade speckit", "update speckit", "new version", "latest version" | Guide full upgrade: backup constitution → upgrade CLI → init --here --force → restore. See command guide upgrade section |
| "verify extension", "verify-tasks", "review extension", "cleanup extension" | Explain installed extensions and their commands. See presets & extensions guide |
| Troubleshooting & Recovery | |
| "I'm stuck", "don't know what to do", "what's next" | Diagnose current state and recommend next step from getting started — see "Troubleshooting & Recovery" |
| "something went wrong", "this isn't working", "bad output" | Identify the problem phase and guide recovery from getting started — see "Troubleshooting & Recovery" |
| "go back", "redo", "start over", "wrong phase" | Guide phase rollback — always safe to return to earlier phases, commit history preserves work |
| "spec is wrong", "plan is bad", "need to change" | Guide mid-workflow correction: update the artifact, then re-run downstream phases |
| "new requirements", "scope changed", "need to add" | Guide incremental requirements — finish current spec or create a new one per Issue #328 |
| "update spec after implementation", "spec is outdated" | Guide spec-code sync — update spec.md to reflect what was actually built |
| Quality Evaluation | |
| "is my spec good", "evaluate", "review quality" | Walk through quality signals from getting started — see "How to Evaluate Quality at Each Gate" |
| "is my plan good", "review my plan" | Check plan quality signals: gates, research, data model, contracts |
| "are my tasks good", "review tasks" | Check task quality: story organization, granularity, traceability, parallelism |
| Enhancement Commands (speckit-pro plugin) | |
| "scope this idea", "pre-spec scoping", "interview me on this brief", "walk every branch of the design tree", "produce a Design Concept doc", "before /speckit-specify", "before I write the spec" | Guide to $grill-me — relentless one-question-at-a-time interview that produces a Design Concept doc (Goals, Non-goals, Q&A log, Open Questions). Strictly human-in-the-loop. The output enriches $speckit-scaffold-spec's workflow file phase prompts. Use it standalone for raw briefs / transcripts, or rely on $speckit-scaffold-spec to invoke it automatically per spec. |
| "write a PRD", "create a product requirements document", "draft a PRD and roadmap", "shape this idea into a PRD", "turn this brief into a PRD", "plan a product", "decompose an idea into a SPEC catalog", "before I write specs" | Guide to $speckit-prd — a collaborative, one-question-at-a-time interview that authors a lean PRD and the technical roadmap (SPEC catalog) from a raw idea. This is the front door of the chain (PRD → roadmap → scaffold-spec → autopilot). Use it when the PRD does not exist yet; if a PRD already exists and you only need decomposition, use the technical-roadmap path below. |
| "technical roadmap", "decompose feature", "multi-spec", "too large for one spec" | Guide technical roadmap creation — decompose large features into sequential specs. See Enhancement section below. Tip: if no PRD exists yet, author it and the roadmap together with $speckit-prd. To sharpen an existing PRD before decomposing, run $grill-me docs/prd.md first to lock in the scope envelope. |
| "workflow tracking", "track phases", "workflow file" | Guide workflow file creation — per-spec 7-phase tracking. See Enhancement section below |
| "recommend checklists", "which checklists", "what domains to check" | Run spec-driven domain recommendation — analyze spec to suggest enriched checklist prompts. See Enhancement section below |
| "decompose", "create spec directories", "break into specs" | Guide spec decomposition — generate individual spec directories from technical roadmap. See Enhancement section below |
| "setup spec", "create worktree", "prepare for autopilot" | Guide to $speckit-scaffold-spec — creates worktree, branch, workflow file |
| "resolve PR", "fix review comments", "address copilot comments" | Guide to $speckit-resolve-pr — addresses review comments, fixes code, resolves threads |
| Team Workflow | |
| "team", "who reviews", "PR workflow", "collaboration" | Guide team workflow from getting started — see "Working with a Team" |
