149 lines
7.3 KiB
Markdown
149 lines
7.3 KiB
Markdown
---
|
|
description: Execute the Python/Svelte implementation planning workflow and generate research, design, contracts, and quickstart artifacts.
|
|
handoffs:
|
|
- label: Create Tasks
|
|
agent: speckit.tasks
|
|
prompt: Break the Python/Svelte plan into executable tasks
|
|
send: true
|
|
- label: Create Checklist
|
|
agent: speckit.checklist
|
|
prompt: Create a requirements-quality checklist for the active Python/Svelte 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`
|
|
- `backend/pyproject.toml` and `backend/requirements.txt`
|
|
- `frontend/package.json` and `frontend/svelte.config.js`
|
|
- `docs/SEMANTIC_PROTOCOL_COMPLIANCE.md`
|
|
- `docs/adr/*.md` (Architecture Decision Records)
|
|
- `.specify/memory/constitution.md`
|
|
- `.opencode/skills/semantics-core/SKILL.md`
|
|
- `.opencode/skills/semantics-contracts/SKILL.md`
|
|
- `.opencode/skills/semantics-testing/SKILL.md`
|
|
- `.opencode/skills/semantics-frontend/SKILL.md`
|
|
- `.specify/templates/plan-template.md`
|
|
|
|
3. **Execute the planning workflow** using the template structure:
|
|
- Fill `Technical Context` for the current repository reality: Python 3.13+ backend (FastAPI, SQLAlchemy), Svelte 5 frontend (SvelteKit, Vite, Tailwind CSS), PostgreSQL storage, Docker deployment.
|
|
- 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 Python/Svelte repository, such as:
|
|
|
|
- backend module placement under `backend/src/` (api/, core/, models/, services/, schemas/)
|
|
- frontend component placement under `frontend/src/` (routes/, lib/components/, lib/stores/, lib/api/)
|
|
- `backend/tests/` and `frontend/tests/` strategy and required fixture coverage
|
|
- FastAPI endpoint / WebSocket schema design
|
|
- Svelte 5 runes reactivity model ($state, $derived, $effect, $props)
|
|
- PostgreSQL schema and migration strategy
|
|
- belief-state runtime coverage for C4/C5 Python flows
|
|
- semantic validation boundaries and static verification workflow
|
|
|
|
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:
|
|
- API callers (REST endpoints, WebSocket messages)
|
|
- CLI/operator flows
|
|
- Svelte UI flows (when the feature introduces frontend components)
|
|
- 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 Python/Svelte domain entities such as:
|
|
|
|
- FastAPI request/response schemas (Pydantic models)
|
|
- SQLAlchemy ORM entities
|
|
- Svelte store shapes and component props
|
|
- WebSocket message envelopes
|
|
- Task/report/artifact entities
|
|
|
|
### Global ADR Continuity
|
|
|
|
Before task decomposition, planning must identify any repo-shaping decisions this feature depends on or extends:
|
|
|
|
- Python module layout and decomposition (`backend/src/api/`, `backend/src/core/`, etc.)
|
|
- Frontend component architecture (Svelte 5 runes, SvelteKit routing)
|
|
- Belief-state runtime behavior for C4/C5 flows
|
|
- Semantic comment-anchor rules for Python and Svelte
|
|
- RBAC/security constraints (local auth, ADFS SSO)
|
|
- Plugin system lifecycle
|
|
|
|
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 Python backend modules (api routes, core services, models, plugins) and Svelte frontend components instead of inventing Rust/MCP layers
|
|
- use appropriate comment-anchor syntax: `# [DEF:...]` for Python, `<!-- [DEF:...] -->` for Svelte markup, `// [DEF:...]` for Svelte script blocks
|
|
|
|
Complexity guidance for this repository:
|
|
|
|
- **Complexity 1**: anchors only (DTOs, simple constants)
|
|
- **Complexity 2**: `@PURPOSE` (utility functions, pure helpers)
|
|
- **Complexity 3**: `@PURPOSE`, `@RELATION` (multi-step flows with dependencies); Svelte components also `@UX_STATE`
|
|
- **Complexity 4**: `@PURPOSE`, `@RELATION`, `@PRE`, `@POST`, `@SIDE_EFFECT`; Python orchestration paths should account for belief runtime markers (`belief_scope`, `reason`, `reflect`, `explore`); Svelte also `@UX_FEEDBACK`, `@UX_RECOVERY`, `@UX_REACTIVITY`
|
|
- **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.
|
|
|
|
### Quickstart Output
|
|
|
|
Generate `quickstart.md` using real repository verification paths:
|
|
|
|
- start or exercise the FastAPI backend entrypoint: `cd backend && python -m uvicorn src.app:app --reload`
|
|
- start or exercise the SvelteKit frontend: `cd frontend && npm run dev`
|
|
- invoke relevant API endpoints or CLI commands
|
|
- validate expected response envelopes, WebSocket messages, and recovery flows
|
|
- run `cd backend && pytest` for backend tests
|
|
- run `cd frontend && npm run test` for frontend tests
|
|
- run `ruff check backend/` for Python linting
|
|
|
|
## Key Rules
|
|
|
|
- Use absolute paths in workflow execution.
|
|
- Planning must reflect the current repository structure (`backend/src/`, `frontend/src/`, `docs/adr/`) rather than legacy Rust/MCP examples.
|
|
- Do not reference `.ai/*` or `.kilocode/*` paths as feature artifacts.
|
|
- 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.
|