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

description, handoffs

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

User Input

$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