speq-planning
Plan-authoring workflow — spec delta authoring, test mapping, plan.md/decision-log.md generation, expert-task tagging, headless escalation, and revision mode. Triggered by planner-agent.
marconae · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add marconae/speq-skill --skill speq-planning技能说明
name: speq-planning description: Plan-authoring workflow — spec delta authoring, test mapping, plan.md/decision-log.md generation, expert-task tagging, headless escalation, and revision mode. Triggered by planner-agent.
Plan Authoring
Guiding Principles
- BDD (Gherkin syntax): scenarios use GIVEN/WHEN/THEN; integration tests by default, unit tests only for isolated pure computation
- EARS syntax: spec narratives use unambiguous behavioral clauses
- RFC 2119 keywords: THEN steps use MUST, MUST NOT, SHALL, SHALL NOT, SHOULD, SHOULD NOT, MAY (uppercase)
- ADR (Nygard format): design sections capture Goals / Non-Goals / Architecture / Trade-offs / Key Interfaces
Workflow
1. Discover Existing Specs
The orchestrator already ran speq domain list / speq feature list / speq search query and passed the results as this brief's ## Existing Context section. Treat that as the baseline. Do not re-run the same queries. Re-query only for gaps it does not answer:
speq feature get <domain>/<feature> # a specific feature's full spec, if Existing Context only named it
speq search query "<narrower terms>" # only if Existing Context's results do not cover a sub-area you need
Search first when modifying existing behavior. Check Existing Context before you assume a feature does not exist yet.
2. Author Spec Deltas
For each feature in scope:
specs/<domain>/<feature>/spec.md exists?
├─ Yes → DELTA markers (/speq-plan's references/delta-template.md)
└─ No → Full spec (/speq-plan's references/feature-template.md)
Output: specs/_plans/<plan-name>/<domain>/<feature>/spec.md
3. Test Mapping and Verification
Every scenario requires two forms of external proof. No claims, only evidence.
Integration tests (mandatory per scenario):
- Map each scenario to an integration test (file path + test name)
- One test per scenario by default; combine only when scenarios share setup and assertions
- Unit tests only for pure computation with no I/O
Manual invocation (mandatory per feature):
- Concrete commands that invoke the built software
- Expected observable output per command
4. Generate plan.md
Populate plan.md per /speq-plan's references/plan-template.md:
- Context: why the change is being made
- Features: table referencing spec delta files (NEVER embed spec content), immediately followed by an Impact entry describing user/operator-facing consequences (breaking changes called out, or "None")
- Design: ADR for new features / major changes; skip for minor fixes. For a new abstraction or module boundary, justify it against
/speq-design-philosophy's Quick Diagnostic (deep vs. shallow, dependency direction) - Tasks: work breakdown in implementation order
- Parallelization: knowledge clusters, per the rules below
- Verification: Scenario Coverage + Manual Testing + Checklist (from
specs/mission.md)
Parallelization groups are knowledge clusters. Group tasks vertically: one spec delta plus the code area it governs. Never group by layer. Layer slices (fixtures, then module, then CLI, then tests) make each layer's agent re-derive the same mental model; a vertical slice orients one agent once. Each group row declares a Knowledge column: the group's spec delta path(s) plus the source and test files they govern. The implement orchestrator hands this entry to the group's agent as its orientation pointer. Two facts govern the grouping:
- Tasks that share a spec delta or a source module default into one group.
- Overlapping
Knowledgeentries across groups are a consolidation signal, not a parallelism opportunity.
If two clusters would contend on one shared file, split the module per feature (often the better design; check it against /speq-design-philosophy) or declare a dependency and sequence the clusters. Parallelism is a side effect, not the goal.
5. Generate decision-log.md
Create specs/_plans/<plan-name>/decision-log.md from /speq-plan's references/decision-log-plan-template.md.
What to capture:
- Interview section: verbatim or close paraphrase of every Q&A exchange passed from the orchestrator
- Design Decisions section: one entry per significant choice made while authoring spec deltas or plan.md (architecture patterns, rejected alternatives, scope boundaries)
- Review Findings section: leave empty; populated in Revision Mode after
plan-reviewerblockers, and byspeq-implementafter code review
For each decision entry, set Promotes to ADR: yes when the decision is:
- An architectural or workflow pattern adopted project-wide
- A deliberate rejection of a commonly expected approach
- A constraint that future planners need to know to avoid re-litigating
Set Promotes to ADR: no for local design choices, scope trims, and implementation details.
If a decision supersedes an earlier one, name the superseded decision's title in the entry. recorder-agent maps that title to the superseded ADR's slug at promotion.
6. Expert-Task Tagging (CRITICAL)
Tag tasks that require deep reasoning with [expert] at the end of the task line:
- [ ] 2.1 Add CLI flag parsing
- [ ] 2.2 Implement lock-free queue for concurrent spec writes [expert]
- [ ] 2.3 Write integration tests for flag combinations
- [ ] 2.4 Refactor validator to preserve ordering invariants across plugins [expert]
Use [expert] only when the task genuinely needs it:
- Concurrency / ordering / race conditions
- Cross-file refactors with behavioral dependencies
- Novel algorithms or non-obvious correctness
- Security-sensitive code paths
Do NOT tag as expert:
- Standard CRUD, CLI flag plumbing, test fixtures
- Copy-paste from existing patterns
- Documentation or config changes
Over-tagging wastes tokens; under-tagging risks defects. If any task in a parallelization group carries the tag, the orchestrator routes the whole group to `implementer-expert-agent
阅读完整来源 ↗