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

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