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

description, handoffs

description	handoffs
Execute the implementation planning workflow for ss-tools (Python backend + Svelte frontend) and generate research, design, contracts, and quickstart artifacts.	label agent prompt send Create Tasks speckit.tasks Break the plan into executable tasks for Python/Svelte implementation true label agent prompt Create Checklist speckit.checklist Create a requirements-quality checklist for the active 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
   • 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
   • .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.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.
   • 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 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
• 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

Frontend Component Reuse Scan (MANDATORY — before contract generation)

Before designing any new Svelte component, execute a component inventory scan of the existing codebase to maximise reuse and prevent duplicate primitives. Use a subagent with subagent_type: "explore" to scan:

Scan targets (priority order):

1. frontend/src/lib/ui/ — design-system atoms: Button.svelte, Select.svelte, Input.svelte, Card.svelte
2. frontend/src/lib/components/ui/ — composite UI widgets: SearchableMultiSelect.svelte, MultiSelect.svelte
3. frontend/src/lib/components/ — feature components that may be adaptable
4. Inline patterns in existing pages (frontend/src/routes/) — badges, skeletons, empty states, collapsibles

For each found component, the scan MUST return:

• Exact file path
• Props interface (what it accepts)
• Whether it's a direct fit, adaptable, or pattern-only

Reuse decision tree:

Situation	Action
Component exists and fits	@RELATION DEPENDS_ON -> [ExistingComponent] — zero new code
Pattern exists (badge, skeleton, tooltip)	Document the Tailwind classes to replicate; no component extraction
No reusable asset exists	Create new component only then

Output: The contracts/modules.md for every frontend contract MUST include @RELATION edges to reused components and a @RATIONALE noting WHY the component is reused rather than rebuilt. For pattern-only reuse, the contract MUST reference the source page/file where the pattern was observed.

Forbidden patterns:

• Creating a new <Modal> when confirm() suffices
• Building a custom <Select> when $lib/ui/Select.svelte exists
• Inventing a <Toast> system when addToast() from $lib/toasts.js is already wired

UX / Interaction Validation

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

Quickstart Output

Generate quickstart.md using real repository verification paths:

• Backend: cd backend && source .venv/bin/activate && python -m pytest -v
• Frontend: cd frontend && npm run test
• Lint: cd backend && python -m ruff check .
• Frontend lint: cd frontend && npm run lint
• Docker: docker compose up --build

Key Rules

• Use absolute paths in workflow execution.
• 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.