speq-plan
Plan a feature or change through a clarifying interview, producing spec deltas, plan.md, and decision-log.md via planner-agent with adversarial review. Use when the user asks to plan, spec, design, or scope a new feature, a change or removal of existing behavior, a refactor, or a fix — before any implementation.
marconae · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add marconae/speq-skill --skill speq-plan技能说明
name: speq-plan description: Plan a feature or change through a clarifying interview, producing spec deltas, plan.md, and decision-log.md via planner-agent with adversarial review. Use when the user asks to plan, spec, design, or scope a new feature, a change or removal of existing behavior, a refactor, or a fix — before any implementation. model: sonnet
Spec Planner (Orchestrator)
This skill is a thin orchestrator. It runs the clarifying interview, collects context, and delegates the planning work (spec delta authoring, test mapping, task decomposition) to planner-agent.
Required Skills (for the orchestrator)
Invoke before starting:
/speq-cli: spec discovery and search
planner-agent and plan-reviewer invoke their own required skills.
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 can add to, change, or override any part of this workflow. If the hook conflicts with this workflow, the hook wins.
- Absent: continue without mention.
1. Discovery (orchestrator)
Run the speq CLI:
speq domain list
speq feature list
speq search query "<relevant terms>"
Collect only enough context for good interview questions, not a full exploration.
2. Clarifying Interview (orchestrator)
Apply the Socratic Method via AskUserQuestion. Never assume. Decompose the problem space with MECE partitioning:
- Probe: surface hidden assumptions with open-ended questions
- Partition: present alternative solutions as MECE options
- Challenge: test design tradeoffs with counterexamples
Record the answers in a concise summary for 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
<the exact `speq domain list` / `speq feature list` / `speq search query "..."` / `speq feature get` calls you ran, each followed by its output — name the query, not just the result>
## 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:
- Confirm
speq plan validate <plan-name>passed. Re-run if uncertain. - List all created files.
- If the sub-agent escalated a question, resolve it with the user and respawn with the clarification.
6. Adversarial Plan Review (orchestrator)
Spawn plan-reviewer, a diabolus advocatus, to challenge the plan before handoff. Maximum 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>
It writes its findings to specs/_plans/<plan-name>/review/round-1.md and returns only PLAN REVIEW round 1: BLOCKERS: <n>, ADVISORY: <n>, INTENT: <n> — <path>. INTENT counts the BLOCKERs on the Intent Fidelity axis alone.
If INTENT > 0: the reviewer holds that the plan solves a different problem than the one asked. Read the Intent-Fidelity findings from the round file. Present them via AskUserQuestion before any revision. The user accepts the plan as-is, or gives guidance and you respawn planner-agent manually.
If INTENT == 0 and BLOCKER findings exist:
Plan Size classification (compute before respawning plan-reviewer for round 2): the plan is small when all three hold — the plan-name's verb (per the verb table) is fix; plan.md has no ## Design section; decision-log.md's ## Design Decisions section is empty. Otherwise full.
- Respawn
planner-agentwith the path toreview/round-1.md. Instruct it to read the BLOCKER findings from that file, execute eachFix:line, log each resolved blocker as a[plan-review]-prefixed## Review Findingsentry indecision-log.md, and re-runspeq plan validate. - Respawn
plan-reviewerfor round 2 with the same path plus the computedPlan Size: small | fullfield, so it confirms each round-1 BLOCKER is resolved before checking for new ones (or, onsmall, confirms and stops there). - Do not run a third round, even if round 2 raises new BLOCKERs.
If BLOCKERs remain after round 2: read the unresolved BLOCKER findings from review/round-2.md and use AskUserQuestion. The user accepts the risk and proceeds, or gives guidance and you respawn planner-agent manually.
ADVISORY findings never loop and are never persisted. Read them from the last round file and carry them into step 7's report. If round 2 ran confirm-only (Plan Size: small), it produced no ADVISORY findings of its own — read them from round 1's file instead.
7. Explain next steps (orchestrator)
- Report that the plan is created and list all created files
- Report ADVISORY findings from step 6, read from the r