Spec init

Spec Cascade Init Skill

You are scaffolding a docs-first cascade: a small set of empty, human-fillable steering documents that capture product direction before any code exists. This is optimus's bootstrap for spec-driven development.

What you produce (three skeletons under the project root, all product- and tool-neutral):

• docs/product/product-context.md — the long-term product vision.
• docs/product/mvp-prd.md — the first product slice (MVP PRD).
• docs/product/tech-stack.md — the target technology stack.

The boundary — do not cross it. You emit empty skeletons with TODO markers for a human to fill. You author no product content — no personas, no metrics/KPIs, no business-value prose, no technology choices. optimus is an engineering tool; the cascade is product/PM territory that a human owns. The engineering build spec is authored later by /optimus:brainstorm (in docs/specs/), not here. See $CLAUDE_PLUGIN_ROOT/references/sdd-mapping.md for the full contract.

Step 1 — Pre-flight

• Decide where the cascade should live. Normally that is the current project root. If this directory is part of a larger multi-repo workspace, consult $CLAUDE_PLUGIN_ROOT/skills/init/references/multi-repo-detection.md; when 2+ repos are detected, ask the user which repo the product lives in and scaffold inside that repo by default. If the user insists on the workspace root, warn them before scaffolding: /optimus:brainstorm and /optimus:tdd resolve docs/product/ from the repo they run in, so they will never auto-load a workspace-root cascade — the user would have to move the cascade into the target repo for it to be read as steering.
• This skill is most valuable on a greenfield project (docs-first, before code), but it is safe to run anywhere — Step 2 guarantees it never clobbers existing work.

Step 2 — Non-destructive existence check

For each of the three target files, check whether it already exists:

• If a file exists, never overwrite it — record it as exists → skipped.
• If a file is missing, you will create it in Step 3.

If all three already exist, the cascade is already scaffolded: report that and skip to Step 4.

Step 3 — Emit the skeletons

• Read $CLAUDE_PLUGIN_ROOT/skills/spec-init/references/cascade-templates.md.
• For each missing file, create the parent directory if needed (docs/product/) and write the matching template block verbatim to its target path. Do not fill in the TODO markers — that is the human's job.
• Write only these three files. Specifically, do not:
  • scaffold a build-spec file in docs/specs/ — the buildable spec is authored later by /optimus:brainstorm or dropped in by a human, in docs/specs/; see the contract;
  • write anything under .claude/ (settings, hooks, .optimus-version, or docs) — agent/project setup is /optimus:init's job, not this skill's;
  • invent product names, technology choices, or any content beyond the neutral templates.

Step 4 — Report and hand off

• Summarize what was created vs. skipped.

• Tell the user to fill the TODO sections top-down (vision → MVP PRD → target stack), and state the precedence (the canonical rule lives in $CLAUDE_PLUGIN_ROOT/references/sdd-mapping.md and is restated in each scaffolded doc's header) so they know how the docs relate: higher docs set long-term direction; the active build spec governs what to build right now — when they conflict about current work, the active build spec wins.

• Close with the handoff tip. The recommended next skill (/optimus:brainstorm) is not a continuation skill (the human fills the docs out-of-band and brainstorm gathers its own context), so use the default — Variant C in $CLAUDE_PLUGIN_ROOT/references/skill-handoff.md:

  Next step: fill in the cascade's TODO sections (vision → MVP PRD → target stack). Then run /optimus:brainstorm to design the first build — it reads the cascade as steering and writes the engineering spec to docs/specs/.

  Tip: for best results, start a fresh conversation for the next skill — each skill gathers its own context from scratch.