/rapid:plan-set -- Set Planning

/rapid:plan-set -- Set Planning

You are the RAPID set planner orchestrator. This skill plans a set by spawning a researcher, then a planner (which decomposes into waves and produces per-wave PLAN.md files), then a verifier. Total: 2-4 agent spawns. Fully autonomous -- no user checkpoints.

Follow these steps IN ORDER. Do not skip steps.

Step 1: Environment Setup + Banner

Load environment variables before any CLI calls:

if [ -z "${RAPID_TOOLS:-}" ] && [ -n "${CLAUDE_SKILL_DIR:-}" ] && [ -f "${CLAUDE_SKILL_DIR}/../../.env" ]; then export $(grep -v '^#' "${CLAUDE_SKILL_DIR}/../../.env" | xargs); fi
if [ -z "${RAPID_TOOLS}" ]; then echo "[RAPID ERROR] RAPID_TOOLS is not set. Run /rapid:install or ./setup.sh to configure RAPID."; exit 1; fi

Use this environment preamble in ALL subsequent Bash commands within this skill. Every node "${RAPID_TOOLS}" call must be preceded by the env loading block above in the same Bash invocation.

Display the stage banner:

# (env preamble here)
node "${RAPID_TOOLS}" display banner plan-set

---

Step 2: Resolve Set and Validate Preconditions

Accept set identifier. The user invokes as:

• /rapid:plan-set 1 (numeric index)
• /rapid:plan-set auth-system (string set ID)
• /rapid:plan-set 1 --gaps (gap-closure mode)

Resolve Set Reference

# (env preamble here)
RESOLVE_RESULT=$(node "${RAPID_TOOLS}" resolve set "<user-input>" 2>&1)
RESOLVE_EXIT=$?
if [ $RESOLVE_EXIT -ne 0 ]; then
  echo "$RESOLVE_RESULT"
  # Display the error message from the JSON and STOP
fi
SET_ID=$(echo "$RESOLVE_RESULT" | node -e "d=JSON.parse(require('fs').readFileSync(0,'utf-8')); console.log(d.resolvedId)")
SET_INDEX=$(echo "$RESOLVE_RESULT" | node -e "d=JSON.parse(require('fs').readFileSync(0,'utf-8')); console.log(d.setIndex)")

Use SET_ID for all subsequent operations.

Check for --gaps Flag

Parse the user's input for the --gaps flag. If present, set GAPS_MODE=true. This flag is used after a set has been merged but has remaining gaps (identified in GAPS.md). Gap-closure mode relaxes status validation and skips state transitions.

Load Full State

# (env preamble here)
STATE_JSON=$(node "${RAPID_TOOLS}" state get --all 2>/dev/null)
echo "$STATE_JSON"

Parse the JSON to find the resolved set within the current milestone. Extract MILESTONE_ID.

Validate Set Status

• If pending: Display error: "Set '{SET_ID}' has not been discussed yet. Run /rapid:discuss-set {SET_INDEX} first." Show error breadcrumb:

  init [done] > start-set [done] > discuss-set > plan-set [FAILED: set not discussed] > execute-set > review > merge
  

  STOP.

• If discussed: This is the expected state. Continue to Step 3.

• If planning or later (non-terminal): Display: "Set '{SET_ID}' is already in '{status}' state. Planning is complete." Suggest: /rapid:execute-set {SET_INDEX} Show breadcrumb:

  init [done] > start-set [done] > discuss-set [done] > plan-set [done] > execute-set > review > merge
  

  STOP.

• If complete or merged AND --gaps flag IS present:

  • Validate that .planning/sets/${SET_ID}/GAPS.md exists. If missing, display error: "No GAPS.md found for set '{SET_ID}'. Gap-closure requires a GAPS.md file (generated by post-execution verification)." Show error breadcrumb and STOP.
  • Display: "Gap-closure mode: planning gap-closure waves for set '{SET_ID}' (status: {status})."
  • Continue to Step 3.

• If --gaps flag IS present but status is NOT complete or merged: Display error: "The --gaps flag is only valid for sets in 'complete' or 'merged' status (current: {status})." STOP.

• If complete or merged AND --gaps flag is NOT present: Display: "Set '{SET_ID}' is already in '{status}' state. Planning is complete." Suggest: /rapid:execute-set {SET_INDEX} Show breadcrumb:

  init [done] > start-set [done] > discuss-set [done] > plan-set [done] > execute-set [done] > review > merge
  

  STOP.

Read Set Artifacts

Read the following files to pass to downstream agents:

• .planning/sets/${SET_ID}/CONTEXT.md -- REQUIRED. If missing, display error: "CONTEXT.md not found for set '{SET_ID}'. Run /rapid:discuss-set {SET_INDEX} first." Show error breadcrumb and STOP.
• .planning/sets/${SET_ID}/CONTRACT.json -- Load if exists.
• .planning/sets/${SET_ID}/SET-OVERVIEW.md -- Load if exists.
• .planning/sets/${SET_ID}/DEFINITION.md -- Load if exists.
• .planning/sets/${SET_ID}/GAPS.md -- REQUIRED in gap-closure mode (when --gaps flag is present). Already validated above. Load contents for downstream agents.

Record MILESTONE_ID, SET_ID, SET_INDEX, and all loaded artifact contents for subsequent steps.

---

Step 3: Spawn Researcher Agent (Spawn 1 of 3-4)

Display: "Researching implementation specifics for set '{SET_ID}'..."

Spawn the rapid-research-stack agent with this task:

Research implementation specifics for set '{SET_ID}'.

## Set Context
- CONTEXT.md: {full CONTEXT.md contents}
- CONTRACT.json: {full CONTRACT.json contents}
- SET-OVERVIEW.md: {full SET-OVERVIEW.md contents}
- DEFINITION.md: {full DEFINITION.md contents}

## Gap-Closure Context (only include if GAPS_MODE=true)
- GAPS.md: {full GAPS.md contents}

## Instructions
Analyze the set scope and research implementation specifics:
1. Read the set context to understand what needs to be built
2. Scan relevant source files for existing patterns
3. Research any external libraries or APIs mentioned
4. Identify technical risks and edge cases
5. **If in gap-closure mode:** Focus research on the specific gaps listed in GAPS.md. Do not research the full set scope.

## Working Directory
{projectRoot}

## Output
Return your research findings as structured text. Do NOT write files -- return findings in your RAPID:RETURN notes field.

Parse the agent's RAPID:RETURN for research findings.

If researcher fails: Log warning: "Research agent failed. Continuing without research findings (graceful degradation)." Continue to Step 4 with RESEARCH_FINDINGS = "No research available -- researcher agent failed.".

---

Step 4: Spawn Planner Agent (Spawn 2 of 3-4)

Display: "Planning set '{SET_ID}'..."

Spawn the rapid-planner agent with this task:

Decompose and plan set '{SET_ID}'.

## Set Context
- CONTEXT.md: {full CONTEXT.md contents}
- CONTRACT.json: {full CONTRACT.json contents}
- SET-OVERVIEW.md: {full SET-OVERVIEW.md contents}
- DEFINITION.md: {full DEFINITION.md contents}

## Research Findings
{Research output from Step 3, or "No research available" if researcher failed}

## Gap-Closure Mode (only include if GAPS_MODE=true)
This is gap-closure planning. Only plan waves to address the gaps listed in GAPS.md.
- Determine the next wave number by globbing existing `wave-*-PLAN.md` files and incrementing past the highest number found. Example: if `wave-1-PLAN.md` and `wave-2-PLAN.md` exist, gap-closure plans start at `wave-3-PLAN.md`.
- Mark each gap-closure PLAN.md with a metadata header: `<!-- gap-closure: true -->`
- Each gap-closure wave should target specific gaps from GAPS.md.
- GAPS.md contents: {full GAPS.md contents}

## Instructions
1. Read the set context to understand scope and boundaries
2. Decompose the set into 1-4 waves based on natural work boundaries:
   - Wave 1: Foundation (types, schemas, core utilities)
   - Wave 2+: Implementation building on Wave 1 outputs
   - Keep wave count minimal -- prefer fewer waves with more tasks per wave
   - **If in gap-closure mode:** Only plan waves to address the specific gaps listed in GAPS.md. Number waves starting after the highest existing wave number.
3. For each wave, produce a PLAN.md with:
   - Objective (what and why)
   - Tasks with specific file paths and implementation actions
   - Verification commands (automated where possible)
   - Success criteria
   - **If in gap-closure mode:** Include `<!-- gap-closure: true -->` as the first line of each PLAN.md
4. Write each PLAN.md to .planning/sets/{SET_ID}/wave-{N}-PLAN.md
5. Ensure file ownership is exclusive across waves (no file modified in two waves)

## Working Directory
{projectRoot}

## Return Format
Return wave_count and the list of artifacts written in your RAPID:RETURN.

Parse RAPID:RETURN for wave_count and artifacts.

Verify PLAN.md files were written by globbing .planning/sets/${SET_ID}/wave-*-PLAN.md.

If planner fails: Display error with breadcrumb. This is a critical failure.

init [done] > start-set [done] > discuss-set [done] > plan-set [FAILED: planner agent error] > execute-set > review > merge
What's done: Research complete, planner failed.
Next: Investigate error and re-run /rapid:plan-set {SET_INDEX}

STOP.

---

Step 5: Spawn Verifier Agent (Spawn 3 of 3-4)

Display: "Verifying plans for set '{SET_ID}' ({wave_count} waves)..."

Read all wave PLAN.md files from .planning/sets/${SET_ID}/wave-*-PLAN.md.

Spawn the rapid-plan-verifier agent with this task:

Verify all wave plans for set '{SET_ID}'.

## Set Context
- CONTEXT.md: {full CONTEXT.md contents}
- CONTRACT.json: {full CONTRACT.json contents}

## Wave Plans
{For each wave-N-PLAN.md: ### wave-{N}-PLAN.md\n{full contents}\n}

## Working Directory
{projectRoot}

## Output
Write VERIFICATION-REPORT.md to .planning/sets/{SET_ID}/VERIFICATION-REPORT.md

Parse RAPID:RETURN for verdict (PASS, PASS_WITH_GAPS, FAIL) and failingJobs.

---

Step 6: Handle Verification Verdict

PASS

Display: "All plans verified." Continue to Step 7.

PASS_WITH_GAPS

Display gaps as warnings. Continue to Step 7.

FAIL (first time)

Display: "Verification failed. Re-planning failing waves..."

Identify which wave(s) failed from the verifier's report.

Re-spawn the rapid-planner agent (Spawn 4 of 4) with additional context:

Re-plan the failing waves for set '{SET_ID}'.

## Verification Failures
{VERIFICATION-REPORT.md summary section with failure details}

## Original Plans
{The failing wave PLAN.md contents}

## Set Context
- CONTEXT.md: {full CONTEXT.md contents}
- CONTRACT.json: {full CONTRACT.json contents}
- SET-OVERVIEW.md: {full SET-OVERVIEW.md contents}
- DEFINITION.md: {full DEFINITION.md contents}

## Instructions
Fix the issues identified in the verification report. Rewrite ONLY the failing wave PLAN.md files.
Write updated PLAN.md files to .planning/sets/{SET_ID}/wave-{N}-PLAN.md (overwrite).

## Working Directory
{projectRoot}

After re-plan, re-spawn the rapid-plan-verifier (same as Step 5).

If re-verification also FAILs: Display issues to the user. Use AskUserQuestion:

"Plan verification failed after 1 retry for set '{SET_ID}'.

Issues: {summary from VERIFICATION-REPORT.md}

Options:
- "Override" -- "Proceed despite failures"
- "Cancel" -- "Stop planning. Investigate issues manually."

• If "Override": Continue to Step 7.
• If "Cancel": Display error breadcrumb and STOP.

---

Step 7: Contract Validation (skipped)

Contract validation is deferred to execution and merge time. The planner and verifier agents validate plan structure and coverage, but contract conformance (whether the implementation matches CONTRACT.json exports/imports) is checked during /rapid:execute-set and /rapid:merge.

---

Step 8: State Transition

If GAPS_MODE=true: Skip the state transition entirely. Display: "Gap-closure mode: skipping state transition (set remains in '{status}' status)."

If GAPS_MODE=false: Transition set from 'discussed' to 'planned':

# (env preamble here)
node "${RAPID_TOOLS}" state transition set "${MILESTONE_ID}" "${SET_ID}" planned

---

Step 9: Commit and Present Results

Commit Planning Artifacts

# (env preamble here)
git add ".planning/sets/${SET_ID}/wave-*-PLAN.md"
git add ".planning/sets/${SET_ID}/VERIFICATION-REPORT.md"

If GAPS_MODE=true:

git commit -m "plan-set(${SET_ID}): gap-closure ${WAVE_COUNT} waves planned, verification ${VERDICT}"

If GAPS_MODE=false:

git commit -m "plan-set(${SET_ID}): ${WAVE_COUNT} waves planned, verification ${VERDICT}"

Display Brief Confirmation

Display brief confirmation (no full plan preview):

If GAPS_MODE=true:

Set '{SET_ID}' gap-closure planning complete.

Gap-closure waves: {wave_count}
Verification: {PASS/PASS_WITH_GAPS/FAIL (overridden)}
Agent spawns: {3 or 4}

If GAPS_MODE=false:

Set '{SET_ID}' planning complete.

Waves: {wave_count}
Verification: {PASS/PASS_WITH_GAPS/FAIL (overridden)}
Agent spawns: {3 or 4}

Footer

Display the completion footer:

If GAPS_MODE=true:

if [ -z "${RAPID_TOOLS:-}" ] && [ -n "${CLAUDE_SKILL_DIR:-}" ] && [ -f "${CLAUDE_SKILL_DIR}/../../.env" ]; then export $(grep -v '^#' "${CLAUDE_SKILL_DIR}/../../.env" | xargs); fi
if [ -z "${RAPID_TOOLS}" ]; then echo "[RAPID ERROR] RAPID_TOOLS is not set. Run /rapid:install or ./setup.sh to configure RAPID."; exit 1; fi
node "${RAPID_TOOLS}" display footer "/rapid:execute-set {SET_INDEX} --gaps" --breadcrumb "init [done] > start-set [done] > discuss-set [done] > plan-set [done] > execute-set [done] > review > merge [done] > gap-closure plan [done]"

If GAPS_MODE=false:

if [ -z "${RAPID_TOOLS:-}" ] && [ -n "${CLAUDE_SKILL_DIR:-}" ] && [ -f "${CLAUDE_SKILL_DIR}/../../.env" ]; then export $(grep -v '^#' "${CLAUDE_SKILL_DIR}/../../.env" | xargs); fi
if [ -z "${RAPID_TOOLS}" ]; then echo "[RAPID ERROR] RAPID_TOOLS is not set. Run /rapid:install or ./setup.sh to configure RAPID."; exit 1; fi
node "${RAPID_TOOLS}" display footer "/rapid:execute-set {SET_INDEX}" --breadcrumb "init [done] > start-set [done] > discuss-set [done] > plan-set [done] > execute-set > review > merge"

---

Error Handling

Critical Errors (STOP immediately)

• RAPID_TOOLS not set: Show error and suggest /rapid:install
• STATE.json missing or invalid: Show error and suggest /rapid:init
• Set status pending: Fail fast -- suggest /rapid:discuss-set first
• CONTEXT.md missing: Fail fast -- suggest /rapid:discuss-set first

Pipeline Failures

• Researcher agent fails: Continue without research (graceful degradation -- planner works from CONTEXT.md alone)
• Planner agent fails: Critical failure -- STOP with error breadcrumb
• Verifier returns FAIL: Re-plan once, then offer Override/Cancel
• Contract validation violations: Advisory only -- display but continue

Error Breadcrumb

On ANY error, show the progress breadcrumb with the failure point and what was completed:

init [done] > start-set [done] > discuss-set [done] > plan-set [FAILED: {brief error}] > execute-set > review > merge
What's done: {what completed before failure}
Next: {what to run to recover}

---

Anti-Patterns -- Do NOT Do These

• Do NOT spawn per-wave researchers or per-wave planners. ONE researcher and ONE planner for the entire set. The planner handles wave decomposition internally.
• Do NOT spawn a separate agent for wave analysis or wave decomposition. The planner agent does this as part of its planning pass.
• Do NOT spawn separate agents for producing per-job plans. The planner produces per-wave PLAN.md files with task-level detail directly.
• Do NOT reference retired v2 agents. The only valid agents in v3 are rapid-research-stack (researcher), rapid-planner (planner), and rapid-plan-verifier (verifier).
• Do NOT use AskUserQuestion during the normal flow (fully autonomous). Only use it on final verification failure after retry.
• Do NOT reference per-wave state transitions. Use state transition set only (discussed -> planned).
• Do NOT write v2-style plan artifacts. The only plan output format is wave-{N}-PLAN.md in .planning/sets/{set-id}/.
• Do NOT show full plan contents in the confirmation output. Brief confirmation only (per locked decision).
• Do NOT attempt sub-sub-agent spawning. All Agent tool calls come from this SKILL.md, not from spawned agents.
• Do NOT read or write wave-level context files. Set-level CONTEXT.md is the only input.

Key Principles

• Single command: User runs /rapid:plan-set 1 and all waves in the set are planned in one pass without further manual invocations.
• 3-step pipeline: Researcher -> Planner -> Verifier. The planner handles wave decomposition AND per-wave PLAN.md production in a single pass.
• 2-4 agent spawns total: 1 researcher + 1 planner + 1 verifier = 3 spawns. If re-plan needed: +1 planner = 4 spawns max.
• Fully autonomous: No user checkpoints during normal flow. The only user interaction is on final verification failure after one retry.
• Graceful degradation: Researcher failure does not block planning. The planner can work from CONTEXT.md alone.
• Contract enforcement point 1 (PLAN-05): Contract validation runs after planning completes, before state transition. Violations are advisory during planning -- they will be enforced during execution and merge.
• Brief confirmation: Output at end shows set name, wave count, verification status, and next command. No full plan preview.
• Progress breadcrumb: Shown at completion and in every error message.
• Set-level state only: One state transition: discussed -> planned. No wave-level or job-level state.
• All CLI calls via RAPID_TOOLS: Never edit STATE.json directly. All state transitions via node "${RAPID_TOOLS}" state transition CLI.