93 lines
4.3 KiB
Markdown
93 lines
4.3 KiB
Markdown
---
|
|
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`
|