agents

.opencode/command/speckit.plan.md

@@ -1,13 +1,13 @@
 ---
-description: Execute the Python/Svelte implementation planning workflow and generate research, design, contracts, and quickstart artifacts.
+description: Execute the implementation planning workflow for ss-tools (Python backend + Svelte frontend) and generate research, design, contracts, and quickstart artifacts.
 handoffs:
   - label: Create Tasks
     agent: speckit.tasks
-    prompt: Break the Python/Svelte plan into executable tasks
+    prompt: Break the plan into executable tasks for Python/Svelte implementation
     send: true
   - label: Create Checklist
     agent: speckit.checklist
-    prompt: Create a requirements-quality checklist for the active Python/Svelte feature
+    prompt: Create a requirements-quality checklist for the active feature
 ---
 
 ## User Input
@@ -27,20 +27,20 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 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)
+   - `requirements.txt` (backend dependencies)
+   - `frontend/package.json` (frontend dependencies)
    - `.specify/memory/constitution.md`
    - `.opencode/skills/semantics-core/SKILL.md`
    - `.opencode/skills/semantics-contracts/SKILL.md`
+   - `.opencode/skills/semantics-python/SKILL.md`
+   - `.opencode/skills/semantics-svelte/SKILL.md`
    - `.opencode/skills/semantics-testing/SKILL.md`
-   - `.opencode/skills/semantics-frontend/SKILL.md`
    - `.specify/templates/plan-template.md`
+   - relevant `docs/adr/*.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.
+    - Fill `Technical Context` for the current repository reality: Python 3.9+/FastAPI backend, SvelteKit 5/Tailwind frontend, PostgreSQL, Docker, semantic contracts, belief runtime.
+    - Fill `Constitution Check` using the local constitution.
     - 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`.
@@ -51,19 +51,17 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 ## 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
+Research must resolve only implementation-shaping unknowns that matter for this repository, such as:
+- module placement under `backend/src/` or `frontend/src/`
+- API endpoint design (REST routes, WebSocket channels)
+- database schema changes (SQLAlchemy models, migrations)
+- Svelte component hierarchy and store topology
+- async task orchestration patterns
+- test strategy (pytest + vitest) and required fixture coverage
+- belief runtime instrumentation for C4/C5 flows
 - semantic validation boundaries and static verification workflow
 
 Write `research.md` with concise sections:
-
 - Decision
 - Rationale
 - Alternatives Considered
@@ -75,54 +73,47 @@ Use `[NEED_CONTEXT: target]` instead of inventing relation targets, DTO names, o
 
 ### 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
+Validate the proposed design against `ux_reference.md` as an **interaction reference** for operators, API callers, CLI/operator flows, result envelopes, warnings, recovery guidance, and (when applicable) browser-based UI flows.
 
 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
+Generate `data-model.md` for ss-tools domain entities such as:
+- Pydantic request/response schemas
+- SQLAlchemy models and relationships
+- WebSocket message formats
+- Task state transitions
+- Git operation entities
+- Plugin configuration schemas
+- Frontend TypeScript types (when feature is fullstack)
 
 ### 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
+- Python module layout and decomposition
+- FastAPI route organization
+- SvelteKit routing and component hierarchy
+- belief-state runtime behavior (JSON structured logging / console markers)
+- 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 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
+- describe Python modules, FastAPI routes, Svelte components, stores, and services instead of inventing MCP/backend layers
 
 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 1**: anchors only (DTOs, simple Pydantic schemas)
+- **Complexity 2**: `@PURPOSE` (pure functions, utility helpers)
+- **Complexity 3**: `@PURPOSE`, `@RELATION` (service modules, route handlers)
+- **Complexity 4**: `@PURPOSE`, `@RELATION`, `@PRE`, `@POST`, `@SIDE_EFFECT`; 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.
@@ -130,19 +121,15 @@ If a planned contract depends on unknown schema, relation target, or ADR identit
 ### 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
+- Backend: `cd backend && source .venv/bin/activate && python -m pytest -v`
+- Frontend: `cd frontend && npm run test`
+- Lint: `python -m ruff check backend/src/ backend/tests/`
+- Docker: `docker compose up --build`
 
 ## 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.
+- Planning must reflect the current repository structure (`backend/src/**/*.py`, `frontend/src/**/*.svelte`, `backend/tests/`, `docs/adr/*`).
+- Do not reference `.ai/*` or `.kilocode/*` paths (use `.opencode/` for skills).
 - 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.