---
description: Create or update the feature specification from a natural-language feature description for the Python/Svelte repository.
handoffs:
  - label: Build Technical Plan
    agent: speckit.plan
    prompt: Create a Python/Svelte implementation plan for the active feature
  - label: Clarify Spec Requirements
    agent: speckit.clarify
    prompt: Clarify specification requirements
    send: true
---

## User Input

```text
$ARGUMENTS
```

You **MUST** consider the user input before proceeding (if not empty).

## Outline

The feature description is the text passed to `/speckit.specify`.

1. Generate a concise short name (2-4 words) for the feature branch.
2. Check existing branches/spec directories and run `.specify/scripts/bash/create-new-feature.sh --json ...` exactly once.
   - This step is the source of truth for the feature lifecycle.
   - It MUST create and checkout the git branch `NNN-short-name` when git is available.
   - It MUST create `specs/NNN-short-name/` and initialize `spec.md` there.
   - Treat the returned `SPEC_FILE` path as authoritative and derive `FEATURE_DIR` from it.
3. Load these sources before writing the spec:
   - `.specify/templates/spec-template.md`
   - `.specify/templates/ux-reference-template.md`
   - `.specify/memory/constitution.md`
   - `README.md`
   - `docs/SEMANTIC_PROTOCOL_COMPLIANCE.md`
   - relevant `docs/adr/*` when the feature clearly touches an existing architectural lane
4. Create or update the following artifacts inside `FEATURE_DIR` only:
   - `spec.md`
   - `ux_reference.md`
   - `checklists/requirements.md`
5. Generate `ux_reference.md` as an **interaction reference** for API callers, CLI/operator flows, Svelte UX states, result envelopes, warnings, and recovery behavior.
6. Write `spec.md` focused on **what** the user/operator needs and **why**, not how the Python/FastAPI backend or Svelte frontend will implement it.
7. Validate the spec against a requirements-quality checklist and iterate until major issues are resolved.

## Specification Rules

- Use domain language appropriate for this repository: API callers (REST/WebSocket), CLI operators, Svelte UI users, task runners, data migration operators, Git integration users.
- Avoid leaking implementation details such as FastAPI route names, SQLAlchemy models, Svelte component names, or exact file-level refactors.
- Use `[NEEDS CLARIFICATION: ...]` only for truly blocking product ambiguities. Maximum 3 markers.
- Prefer informed defaults grounded in repository context over unnecessary clarification.
- The default project structure is a web application with `backend/src/` (Python) and `frontend/src/` (Svelte). Assume this unless the feature explicitly changes it.
- Do not assume Rust, MCP server, cargo, or `src/*.rs` conventions unless the feature actually introduces them.
- Do not write feature outputs to `.kilo/plans/`, `.kilo/reports/`, or any path outside `specs/<feature>/...`.

## UX / Interaction Reference Rules

- `ux_reference.md` is mandatory. For this repository it covers both:
  - **API/interaction reference** for backend callers (REST endpoints, WebSocket messages, CLI commands)
  - **Svelte UX reference** for frontend flows (when the feature has a UI component)
- Capture:
  - caller/operator/end-user persona
  - happy-path invocation flow (API requests, CLI commands, or UI interactions)
  - result envelope expectations (JSON response shapes, CLI output, UI feedback)
  - warning/degraded states
  - failure recovery guidance
  - canonical terminology
- Include `@UX_STATE`, `@UX_FEEDBACK`, `@UX_RECOVERY`, `@UX_REACTIVITY` guidance when the feature introduces Svelte components.

## Quality Validation

Generate `FEATURE_DIR/checklists/requirements.md` and ensure it validates:

- no implementation leakage into `spec.md`
- no stale Rust/MCP assumptions unless the feature explicitly needs them
- compatibility with the Python/FastAPI backend and Svelte frontend surface
- measurable success criteria
- explicit edge cases and recovery paths
- decision-memory readiness for downstream planning

If unresolved clarification markers remain, present them in a compact, high-impact format and stop for user input.

## Completion Report

Report:

- branch name
- feature directory under `specs/`
- `spec.md` path
- `ux_reference.md` path
- checklist path and status
- readiness for `/speckit.clarify` or `/speckit.plan`