ss-tools/.opencode/command/speckit.plan.md

description, handoffs

description	handoffs
Execute the Python/Svelte implementation planning workflow and generate research, design, contracts, and quickstart artifacts.	label agent prompt send Create Tasks speckit.tasks Break the Python/Svelte plan into executable tasks true label agent prompt Create Checklist speckit.checklist Create a requirements-quality checklist for the active Python/Svelte feature

User Input

$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.