speq-plan

name	speq-plan
description	Plan and create spec deltas for new features or changes to existing features.
model	sonnet

Spec Planner (Orchestrator)

This skill is a thin orchestrator. It conducts the clarifying interview, collects context, and then delegates the heavy planning work (spec delta authoring, test mapping, task decomposition) to the planner-agent sub-agent.

Why this split: Orchestration (asking questions, reading a few files, shepherding the workflow) does not need expensive reasoning. The actual planning — architectural tradeoffs, MECE decomposition, ADR authoring — does. Splitting the work concentrates reasoning on the step that benefits from it.

Required Skills (for the orchestrator)

Invoke before starting:

• /speq-cli — Spec discovery and search

The planner-agent sub-agent invokes /speq-planning, /speq-code-tools, /speq-ext-research, and /speq-cli itself; plan-reviewer invokes /speq-plan-review.

Workflow

0. Load Project Hook (orchestrator)

Check for .speq/plan-hook.md in the repo root.

• Present: read it. Announce "Loaded project hook: .speq/plan-hook.md". Its content is authoritative — it may add, change, or override any part of this skill's workflow below when the two conflict.
• Absent: continue normally, no mention.

1. Discovery (orchestrator)

Use speq CLI to understand what exists:

speq domain list
speq feature list
speq search query "<relevant terms>"

This is lightweight — enough context to ask good clarifying questions, not a full exploration.

2. Clarifying Interview (orchestrator)

Apply the Socratic Method via AskUserQuestion — never assume. Decompose the problem space using MECE partitioning:

• Probe — surface hidden assumptions with open-ended questions
• Partition — present alternative solutions as MECE options
• Challenge — test design tradeoffs through guided counterexamples

Record answers in a concise interview summary to pass to the sub-agent.

3. Plan Name (orchestrator)

Pattern: <verb>-<feature-scope>[-<qualifier>]

Verb	When
add	New feature
change	Modify existing
remove	Deprecate/delete
refactor	Restructure, same behavior
fix	Bug or spec mismatch

4. Delegate to planner-agent

Spawn the planner sub-agent with everything it needs:

Delegate to planner-agent — Plan <plan-name>

## Plan Name
<plan-name>

## User Intent
<1-3 sentence summary of what the user wants>

## Clarifying Interview Results
<verbatim Q&A from the AskUserQuestion exchanges>

## Existing Context
<output of relevant `speq search` / `speq feature get` calls>

## External Research
<any research already conducted, or "none — agent to research as needed">

## Project Hook
<if active: note ".speq/plan-hook.md — read it and apply it" — otherwise omit this section>

## Your Task
Produce spec deltas and plan.md per the `planner-agent` workflow. Tag tasks requiring deep reasoning with [expert] so the implementer orchestrator can route them to implementer-expert-agent.

Return the list of files created and the validation result.

5. Review planner-agent output (orchestrator)

When the sub-agent returns:

1. Confirm speq plan validate <plan-name> passed (re-run if uncertain)
2. List all created files
3. If the sub-agent escalated a question back to you, resolve it with the user and respawn with the clarification

6. Adversarial Plan Review (orchestrator)

planner-agent is both author and, until now, sole judge. Before handing the plan off, spawn plan-reviewer — a diabolus advocatus — to challenge it. Bounded to 2 rounds total.

Round 1:

Delegate to plan-reviewer — Review <plan-name> (round 1)

## Plan Name
<plan-name>

## User Intent
<verbatim original request>

## Clarifying Interview Results
<verbatim Q&A>

## Plan Artifacts
plan.md, decision-log.md, and every specs/_plans/<plan-name>/**/spec.md delta

## Project Hook
<if active: note ".speq/plan-hook.md — read it and apply it" — otherwise omit this section>

If BLOCKER findings exist:

1. Respawn planner-agent with only the BLOCKER list, instructing it to revise the specific plan/spec-delta content addressing each one, log each resolved blocker as a ## Review Findings entry in decision-log.md ([plan-review] title prefix), and re-run speq plan validate.
2. Respawn plan-reviewer for round 2, passing the round-1 BLOCKER list so it confirms each is actually resolved before checking for new ones.
3. Do not loop a third time, even if round 2 surfaces new BLOCKERs.

If BLOCKERs remain after round 2 — use AskUserQuestion: present the remaining blockers, let the user accept the risk and proceed, or give guidance and respawn planner-agent manually.

ADVISORY findings are never looped on or persisted — carry them into step 7's report so the user sees them before implementing.

7. Explain next steps (orchestrator)

• Inform the user that the plan is created and ready for review
• List all created files
• Report any ADVISORY findings from step 6 so the user sees them before implementing
• Inform the user to call /speq-implement <plan-name> to continue
• Inform the user to call /clear to start implementing with a fresh context window
• If Claude Code is in "plan mode", call ExitPlanMode and ask to proceed with cleared context

Spec Hierarchy (reference)

specs/
├── <domain>/<feature>/spec.md     # Permanent
├── _plans/<plan-name>/            # Active
└── _recorded/<plan-name>/         # Archived

Work Split (reference)

Step	Performed by	Why
Discovery, interview, coordination	This skill (pins Sonnet)	Conversational, tool-call heavy
Spec delta authoring, ADR, task decomposition	planner-agent sub-agent	Reasoning-heavy; defect here compounds through implementation
Adversarial review, revision loop	plan-reviewer sub-agent	Catches intent drift, infeasibility, and ambiguity before implementation, not after

Each sub-agent pins its own model and effort in its frontmatter, so planning quality is independent of the parent session's configuration.