semantic cleanup
This commit is contained in:
144
.opencode/command/speckit.plan.md
Normal file
144
.opencode/command/speckit.plan.md
Normal file
@@ -0,0 +1,144 @@
|
||||
---
|
||||
description: Execute the Rust MCP implementation planning workflow and generate research, design, contracts, and quickstart artifacts.
|
||||
handoffs:
|
||||
- label: Create Tasks
|
||||
agent: speckit.tasks
|
||||
prompt: Break the Rust MCP plan into executable tasks
|
||||
send: true
|
||||
- label: Create Checklist
|
||||
agent: speckit.checklist
|
||||
prompt: Create a requirements-quality checklist for the active Rust MCP feature
|
||||
---
|
||||
|
||||
## User Input
|
||||
|
||||
```text
|
||||
$ARGUMENTS
|
||||
```
|
||||
|
||||
You **MUST** consider the user input before proceeding (if not empty).
|
||||
|
||||
## Outline
|
||||
|
||||
1. **Setup**: Run `.specify/scripts/bash/setup-plan.sh --json` from repo root and parse `FEATURE_SPEC`, `IMPL_PLAN`, `SPECS_DIR`, and `BRANCH`.
|
||||
- `IMPL_PLAN` is the authoritative path for `plan.md` inside `specs/<feature>/`.
|
||||
- Derive `FEATURE_DIR` from `IMPL_PLAN` and write every planning artifact there.
|
||||
- Never treat `.kilo/plans/*` as workflow output for `/speckit.plan`.
|
||||
|
||||
2. **Load canonical planning context**:
|
||||
- `README.md`
|
||||
- `Cargo.toml`
|
||||
- `docs/SEMANTIC_PROTOCOL_COMPLIANCE.md`
|
||||
- `docs/adr/ADR-0001-semantic-rust-module-layout.md`
|
||||
- `docs/adr/ADR-0002-belief-state-runtime.md`
|
||||
- `docs/adr/ADR-0003-comment-anchored-semantic-protocol.md`
|
||||
- `docs/adr/ADR-0004-task-shaped-server-routing.md`
|
||||
- `.specify/memory/constitution.md`
|
||||
- `.kilo/skills/semantics-core/SKILL.md`
|
||||
- `.kilo/skills/semantics-contracts/SKILL.md`
|
||||
- `.kilo/skills/semantics-testing/SKILL.md`
|
||||
- `.specify/templates/plan-template.md`
|
||||
|
||||
3. **Execute the planning workflow** using the template structure:
|
||||
- Fill `Technical Context` for the current repository reality: Rust crate, task-shaped MCP server, semantic contracts, belief runtime, and repository-local verification.
|
||||
- Fill `Constitution Check` using the local constitution, semantic protocol compliance doc, and ADR set.
|
||||
- ERROR if a blocking constitutional or semantic conflict is discovered and cannot be justified.
|
||||
- Phase 0: generate `research.md` in `FEATURE_DIR`, resolving all material unknowns.
|
||||
- Phase 1: generate `data-model.md`, `contracts/modules.md`, optional machine-readable contract artifacts, and `quickstart.md` in `FEATURE_DIR`.
|
||||
- Materialize blocking ADR references and planning decisions inside the plan and downstream contracts.
|
||||
- Run `.specify/scripts/bash/update-agent-context.sh kilocode` after planning artifacts are written.
|
||||
|
||||
4. **Stop and report** after planning artifacts are complete. Report branch, `plan.md` path, generated artifacts, and blocking ADR/decision-memory outcomes.
|
||||
|
||||
## Phase 0: Research
|
||||
|
||||
Research must resolve only implementation-shaping unknowns that matter for this Rust MCP repository, such as:
|
||||
|
||||
- crate/module placement under `src/`
|
||||
- `tests/*.rs` strategy and required fixture coverage
|
||||
- MCP tool/resource schema design
|
||||
- runtime evidence and belief-state coverage
|
||||
- semantic validation boundaries and static verification workflow
|
||||
- task-shaped routing, workspace safety, and error-envelope design
|
||||
|
||||
Write `research.md` with concise sections:
|
||||
|
||||
- Decision
|
||||
- Rationale
|
||||
- Alternatives Considered
|
||||
- Impact On Contracts / Tasks
|
||||
|
||||
Use `[NEED_CONTEXT: target]` instead of inventing relation targets, DTO names, or module boundaries that cannot be grounded in repo context.
|
||||
|
||||
## Phase 1: Design, ADR Continuity, and Contracts
|
||||
|
||||
### UX / Interaction Validation
|
||||
|
||||
Validate the proposed design against `ux_reference.md` as an **interaction reference** for MCP callers, CLI/operator flows, result envelopes, warnings, and recovery guidance.
|
||||
|
||||
If the planned architecture degrades the promised interaction model, deterministic recovery path, or context-budget behavior, stop and warn the user.
|
||||
|
||||
### Data Model Output
|
||||
|
||||
Generate `data-model.md` for Rust/MCP domain entities such as:
|
||||
|
||||
- tool request/response structs
|
||||
- semantic query payloads
|
||||
- runtime evidence envelopes
|
||||
- workspace/checkpoint/index/security entities
|
||||
- contract and relation traceability data
|
||||
|
||||
### Global ADR Continuity
|
||||
|
||||
Before task decomposition, planning must identify any repo-shaping decisions this feature depends on or extends:
|
||||
|
||||
- Rust module layout and decomposition
|
||||
- task-shaped tool/resource routing
|
||||
- belief-state runtime behavior
|
||||
- semantic comment-anchor rules
|
||||
- payload/schema stability decisions
|
||||
|
||||
For each durable choice, ensure the plan references the relevant ADR and explicitly records accepted and rejected paths.
|
||||
|
||||
### Contract Design Output
|
||||
|
||||
Generate `contracts/modules.md` as the primary design contract for implementation. Contracts must:
|
||||
|
||||
- use short semantic IDs
|
||||
- classify each planned module/component with `@COMPLEXITY` 1-5
|
||||
- use canonical relation syntax `@RELATION PREDICATE -> TARGET_ID`
|
||||
- preserve accepted-path and rejected-path memory via `@RATIONALE` and `@REJECTED` where needed
|
||||
- describe MCP tools/resources, runtime evidence, validation envelopes, and semantic boundaries instead of inventing backend/frontend layers
|
||||
|
||||
Complexity guidance for this repository:
|
||||
|
||||
- **Complexity 1**: anchors only
|
||||
- **Complexity 2**: `@PURPOSE`
|
||||
- **Complexity 3**: `@PURPOSE`, `@RELATION`
|
||||
- **Complexity 4**: `@PURPOSE`, `@RELATION`, `@PRE`, `@POST`, `@SIDE_EFFECT`; Rust orchestration paths should account for belief runtime markers before mutation or return
|
||||
- **Complexity 5**: level 4 plus `@DATA_CONTRACT`, `@INVARIANT`, and explicit decision-memory continuity
|
||||
|
||||
If a planned contract depends on unknown schema, relation target, or ADR identity, emit `[NEED_CONTEXT: target]` instead of fabricating placeholders.
|
||||
|
||||
### Optional Machine-Readable Contracts
|
||||
|
||||
You MAY generate machine-readable artifacts in `contracts/` only when they mirror the actual MCP tool/resource payloads of this Rust server. Do **not** default to REST/OpenAPI or frontend-sync artifacts unless the feature truly introduces them.
|
||||
|
||||
### Quickstart Output
|
||||
|
||||
Generate `quickstart.md` using real repository verification paths, typically:
|
||||
|
||||
- start or exercise the MCP server entrypoint
|
||||
- invoke relevant MCP tools/resources
|
||||
- validate expected envelopes and recovery flows
|
||||
- run `cargo test --all-targets --all-features -- --nocapture`
|
||||
- run `cargo clippy --all-targets --all-features -- -D warnings` when applicable
|
||||
- run `python3 scripts/static_verify.py`
|
||||
|
||||
## Key Rules
|
||||
|
||||
- Use absolute paths in workflow execution.
|
||||
- Planning must reflect the current repository structure (`src/**/*.rs`, `tests/*.rs`, `docs/adr/*`) rather than legacy Python/Svelte examples.
|
||||
- Do not reference `.ai/*` or `.kilocode/*` paths.
|
||||
- Do not write any feature planning artifact outside `specs/<feature>/...`.
|
||||
- Do not hand off to `speckit.tasks` until blocking ADR continuity and rejected-path guardrails are explicit.
|
||||
Reference in New Issue
Block a user