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/
• Screen Model topology: which screens need a [TYPE Model] (.svelte.ts), which atoms each model declares, which invariants cross widget boundaries
• API endpoint design (REST routes, WebSocket channels)
• database schema changes (SQLAlchemy models, migrations)
• Svelte component hierarchy and store topology
• async task orchestration patterns
• TypeScript DTO alignment: frontend types/ matching backend Pydantic schemas
• test strategy (pytest + vitest; L1 model invariants without render + L2 UX contracts with render)
• 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 Model & Component Reuse Scan (MANDATORY — before contract generation)

Before designing any new screen, execute a model-first inventory scan followed by a component inventory scan of the existing codebase to maximise reuse and prevent duplicate primitives.

Step 1: Screen Model scan (use a subagent with subagent_type: "explore"):

• Search frontend/src/lib/models/ for existing [TYPE Model] contracts
• Use axiom_semantic_discovery search_contracts type="Model" query="<domain>" for structured search
• Check model atoms, actions, and invariants — reuse if the screen state maps to an existing model
• New models use .svelte.ts extension, [TYPE Model] contract, @STATE/@ACTION/@INVARIANT tags

Step 2: Component scan (priority order):

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/models and a @RATIONALE noting WHY the asset is reused rather than rebuilt. For pattern-only reuse, the contract MUST reference the source page/file where the pattern was observed. Components that bind to a Screen Model declare @RELATION BINDS_TO -> [ModelId].

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.

Attention Compliance Gate (MANDATORY — before generating contracts)

Every contract in contracts/modules.md MUST pass these checks. Contracts that fail are invisible to the model after context compression (per semantics-core §VIII):

Rule	Check	Failure Consequence
ATTN_1	First anchor line: #region Domain.Sub.Name [C:N] [TYPE Type] [SEMANTICS tag1,tag2] — all on ONE line	CSA 4× pooling loses detail from multi-line anchors
ATTN_2	IDs are hierarchical: Core.Auth.Login, not login_handler	HCA 128× makes flat IDs indistinguishable from noise
ATTN_3	All contracts in a domain share primary @SEMANTICS keyword (e.g., all auth contracts use [SEMANTICS auth, ...])	DSA Lightning Indexer fails to group domain contracts
ATTN_4	Contract ≤150 lines, module ≤400 lines	Contracts exceeding the sliding window are partially invisible

Cross-stack compliance (fullstack features only):

• Backend Pydantic schema contract and frontend TypeScript DTO contract MUST have matching @RELATION edges crossing the stack boundary.
• Both MUST share at least one @SEMANTICS keyword so the DSA Indexer can link them.

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 DTOs in frontend/src/types/ — MUST match backend Pydantic schemas across the stack boundary
• Screen Model interfaces — typed atoms, FSM state unions, action payloads for .svelte.ts models

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
• Screen Model topology: which screens need a model, model-atom boundaries, invariant scope
• belief-state runtime behavior (JSON structured logging / console markers)
• semantic comment-anchor rules
• TypeScript-first frontend architecture (.svelte.ts models, typed props, typed API boundaries)
• payload/schema stability decisions

Contract Design Output

Generate contracts/modules.md as the primary design contract for implementation. Contracts must:

• use short hierarchical semantic IDs with 2-3 levels: Domain.Name (e.g., Core.Auth.Login, Api.Dashboards, Users.ListModel, Test.Migration.RunTask). NOT flat IDs like login_handler or UserListModel.
• classify each planned module/component/model with [C:N] complexity in the #region anchor (NOT @COMPLEXITY N)
• use canonical anchor syntax: #region Id [C:N] [TYPE TypeName] [SEMANTICS tags] / #endregion Id
• 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, Screen Models (.svelte.ts), stores, and services instead of inventing MCP/backend layers

Complexity guidance for this repository:

• C1: anchors only (DTOs, simple Pydantic schemas, pure constants)
• C2: typically adds @BRIEF (pure functions, utility helpers)
• C3: typically adds @RELATION (service modules, route handlers); Svelte components also @UX_STATE
• C4: typically adds @PRE, @POST, @SIDE_EFFECT; Screen Models also @STATE, @ACTION, @INVARIANT; orchestration paths should account for belief runtime markers
• C5: C4 + @DATA_CONTRACT, @INVARIANT, and explicit decision-memory continuity (@RATIONALE/@REJECTED)

Function-Level Contracts for C3+ (MANDATORY for cross-stack and orchestration)

For every C3+ function, method, or Screen Model action that is:

• An API endpoint (FastAPI route handler)
• A Screen Model action with @SIDE_EFFECT
• A C4/C5 orchestration function (migration runner, task executor, auth flow)

Generate its full #region header in contracts/modules.md under its parent module. This header becomes the implementation contract that the coding agent MUST satisfy.

Minimal header for C3 API endpoints:

#region Domain.Resource.Action [C:3] [TYPE Function] [SEMANTICS domain,action]
# @ingroup Domain
# @BRIEF One-line purpose.
# @RELATION DEPENDS_ON -> [DependencyService]
# @RELATION DEPENDS_ON -> [DTO:RequestSchema]

Full header for C4/C5 orchestration & cross-stack functions:

#region Domain.Resource.Action [C:4] [TYPE Function] [SEMANTICS domain,action]
# @ingroup Domain
# @BRIEF One-line purpose.
# @PRE Precondition 1 (verifiable by guard clause).
# @POST Output guarantee 1 (testable assertion).
# @SIDE_EFFECT State mutation, I/O, or external call.
# @SIDE_EFFECT Logging (REASON/REFLECT/EXPLORE markers required).
# @RELATION DEPENDS_ON -> [ServiceDependency]
# @RELATION DEPENDS_ON -> [DTO:InputSchema]
# @DATA_CONTRACT InputDTO -> OutputDTO
# @RATIONALE Why this implementation approach.
# @REJECTED What alternative was considered and forbidden.
# @TEST_EDGE: scenario_name -> Expected failure behavior.

Screen Model actions (Svelte .svelte.ts):

// #region ScreenModel.actionName [C:4] [TYPE Function] [SEMANTICS domain,action]
// @BRIEF What this action does.
// @ACTION Public action — callable from components.
// @PRE Guards before execution.
// @POST State guarantees after completion.
// @SIDE_EFFECT API call, store mutation, model state update.
// @RELATION CALLS -> [apiClient]
// @TEST_EDGE: network_failure -> ScreenState = "error"

Rules:

• Function contract headers are NOT implementation — they are design contracts. The coding agent implements the body.
• C1/C2 functions do NOT need pre-generated contracts — only C3+.
• @TEST_EDGE declarations enable qa-tester to write tests BEFORE implementation (true TDD).
• @DATA_CONTRACT on API endpoints enables fullstack-coder to align frontend TypeScript DTOs.
• @SIDE_EFFECT with belief runtime markers ensures molecular CoT logging is wired from day one.
• Cross-stack functions MUST have matching @DATA_CONTRACT on both backend and frontend sides.
• All contracts MUST pass the Attention Compliance Gate (ATTN_1-4) above.

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.