setup

name	setup
description	Plan an entire project as Work Packages — guided interview that decomposes the project into skeleton PRDs with explicit dependencies, then generates the dependency map. Run once at the start of a project (or when adopting prd-kit on an existing one).
argument-hint	[optional: path to a scope/proposal document]

/prd:setup — decompose a project into skeleton PRDs

You are helping the user plan an entire project as a set of Work Packages (WPs). One WP = one PRD = one unit of work that can be delivered on its own. The output of this command is the skeleton of the whole project: every WP as a skeleton PRD with explicit dependencies, plus the dependency map. Nothing gets deeply specified here — that is /prd:fill's job, one WP at a time, right before building it.

Philosophy (do not break it):

• Skeleton first. Deciding the shape of the project (what exists, what depends on what) is cheap now and expensive later. Deciding the details is the opposite: they are best decided one WP at a time, with fresh context, just before building.
• Do not ask what you can read. Before interviewing, investigate the repo and any documents provided. Pre-fill everything inferable; ask only what the code and docs cannot tell you (business decisions, scope, priorities, team).
• The user decides. Propose, explain trade-offs, recommend — but every scope and dependency decision is theirs.

Step 1 — Investigate before asking

• If $ARGUMENTS points to a scope/proposal document, read it first.
• Explore the repo: existing code, docs, README, anything that hints at architecture, modules or prior decisions. On a greenfield project this step is short; say so and move on.
• Check whether a PRD folder already exists (docs/prds/, docs/PRD/, prds/). If it does, list what is there and switch to adoption mode: keep existing files, only add what is missing.

Step 2 — Frame the project (interview, ~1 round)

Use AskUserQuestion (max ~4 questions per round; skip anything already answered by Step 1):

• Goal: what must exist at the end, and for whom? (one sentence)
• Milestones/phases: are there natural delivery phases or deadlines? (optional)
• Team: who works on this? (owners for the WPs; optional, can be assigned later)
• External dependencies: anything outside the team's control (vendor API access, credentials, third-party approvals)? These become external blockers on their WPs.

Step 3 — Propose the decomposition

Draft the WP list yourself first, then review it with the user. Rules for a good cut:

• Each WP is independently deliverable: it can be built, tested and merged on its own once its dependencies are done.
• Foundations first: shared code, config, data models tend to be WP-01..02 with no dependencies; integrations and end-to-end flows come last.
• Dependencies are explicit and minimal. If two WPs depend on each other, the cut is wrong — merge or re-slice them.
• Excluded scope names its destination WP. "Not in this WP" is only allowed as "done in WP-NN".
• Size each WP S/M/L. A WP that feels XL should be split.
• Typical project: 6–15 WPs. Fewer than 4 → probably doesn't need this methodology; more than ~20 → group into milestones.

Present the proposal as a table (id · title · one-liner · size · deps · owner · external) and iterate until the user approves it. Explain why each dependency exists — the user must be able to challenge it.

Step 4 — Write the skeleton PRDs

• Create the PRD folder (default docs/prds/; respect an existing one).
• For each WP, copy the structure of ${CLAUDE_PLUGIN_ROOT}/templates/PRD-SKELETON.md into docs/prds/WP-NN-<slug>.md (short kebab-case slug) and fill:
  • the YAML frontmatter (id, title, status: skeleton, size, depends_on, milestone, owner, external),
  • §1 Objective (one honest paragraph — end state and value),
  • §2 Scope (in / out, with destination WPs for the out items),
  • §3 Open questions (everything that must be answered in /prd:fill — capture them now while the planning context is fresh).
• The frontmatter is machine-read by /prd:map and /prd:status — keep it valid YAML.

Step 5 — Generate the map

Run the /prd:map procedure (see that skill): regenerate ROADMAP.md and map.html in the PRD folder from the frontmatter you just wrote. Show the user the critical path and which WPs are ready to start.

Step 6 — Recommend the tracker practice

If the user tracks work in Linear (or the Linear MCP tools are available), offer to mirror the plan: one issue per WP, milestones for phases, and the sync conventions from ${CLAUDE_PLUGIN_ROOT}/docs/LINEAR.md. Only create issues with the user's explicit confirmation. If they use another tracker, the same practice applies — adapt it.

Notes

• Do not commit anything unless asked; leaving the files written is the deliverable.
• Close by telling the user the loop going forward: /prd:fill WP-NN (spec one WP before building) → build → set status: done → /prd:map (refresh) → repeat. /prd:new adds a WP later; /prd:status reports progress.