dvy1987/agent-loom / .agents/skills/feature-spec
feature-spec
VerifiedWrite the executable feature specification — the WHAT and WHY artifact that agents and reviewers treat as source of truth. Owns both /specify and /clarify modes. Load when the user asks to write a feature spec, write a specification, write an executable spec, define functional requirements, capture acceptance criteria as Given/When/Then, or when the spec-driven-development orchestrator routes here. Also triggers on "feature spec", "executable spec", "/specify", "/clarify", "write the spec for this feature", "specification for", "spec-driven", "machine-readable spec". Output: docs/specs/YYYY-MM-DD-<slug>-feature-spec.md. Hard gate: cannot Approve while [NEEDS CLARIFICATION] markers remain.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.5 KB |
| references/examples.md | markdown | 1.3 KB |
| references/feature-spec-schema.md | markdown | 4.9 KB |
references/feature-spec-schema.md
View on GitHub# Feature Spec Schema
Use this template for every feature spec. Save to `docs/specs/YYYY-MM-DD-<slug>-feature-spec.md`.
---
## Frontmatter
```yaml
---
artifact: feature-spec
status: Draft | Clarifying | Approved
constitution: docs/constitution.md@<version>
title: <Feature Title>
slug: <kebab-case-slug>
sources:
- docs/prd/... # optional
- docs/specs/... # optional design doc from brainstorming
---
```
---
## Body Template
```md
# Feature Spec: <Title>
## Summary
<1–2 sentences: what changes for the user, why now>
## Problem
<Who has this pain, what current friction, what's at stake>
## User Scenarios
### US-1 <name>
<Persona>: <plain-language scenario>
### US-2 <name>
...
## Functional Requirements
- **FR-1** <noun-verb statement of capability>
- **FR-2** ...
## Non-Functional Requirements
- **NFR-1** <category>: <measurable target>
- **NFR-2** ...
## Acceptance Criteria
### AC-FR-1.1
**Given** <preconditions>
**When** <action>
**Then** <observable outcome with measurable threshold>
### AC-FR-1.2
...
(One AC minimum per FR. NFRs that map to specific FRs reference them; global NFRs get their own AC-NFR-N section.)
## Edge Cases
- **EC-1** <abnormal/boundary condition> → expected handling
- **EC-2** ...
(Minimum 3.)
## Out of Scope
- <specific thing this spec explicitly does not cover>
- ...
## Constitution Waivers
(Only present if any constitution rule is intentionally not satisfied. Each waiver must cite the rule ID and a rationale.)
- **C-X.Y waived** — Rationale: <why this rule cannot apply here>
## Needs Clarification
- **CL-1** <question> — relates to: FR-2
- **CL-2** ...
(If empty, status can be set to Approved.)
## Review Checklist
- [ ] No architecture or library mentioned
- [ ] Every FR has ≥1 AC
- [ ] Constitution rules referenced where relevant (e.g., "satisfies C-2.1")
- [ ] No vague adjectives
- [ ] Out of Scope non-empty and specific
- [ ] All CLs resolved before Approval
- [ ] Any waivers explicit with rationale
```
---
## Status Lifecycle
```
Draft → CL list may be non-empty, no plan yet
Clarifying → user is actively resolving CLs
Approved → CL list empty, user confirmed; implementation-plan can consume
```
---
## Test Skeletons from Acceptance Criteria
Every AC is written so it converts mechanically to a failing test — this is the SDD×TDD seam. Emit skeletons when the spec reaches `Approved` (on request, or when `spec-driven-development /implement` starts).
**Mapping rules:**
| AC part | Test part |
|---------|-----------|
| **Given** <preconditions> | Arrange — fixtures, seeded state, mocks at boundaries only |
| **When** <action> | Act — one call/interaction, mirroring the user-visible action |
| **Then** <outcome + threshold> | Assert — observable outcome; thresholds become explicit assertions |
**Conventions:**
- One skeleton per AC. Test name carries the AC ID so `spec-crosscheck` can trace it: `test_AC_FR_1_1_expired_token_rejected` / `it('AC-FR-1.1: rejects expired token')`.
- The skeleton body arranges and acts, then asserts against the contract — it MUST fail on current code (Red). No implementation, no `skip`, no empty assertion that vacuously passes.
- Skeletons are handed to `test-driven-development` as the Red phase starting point; `incremental-implementation` picks which AC's skeleton each slice turns green.
- Global NFR ACs (latency, error-rate) become threshold assertions or a named perf/integration test — still carrying the AC ID.
**Example** (from AC-FR-1.1 "Given a magic link older than 15 minutes, When the user clicks it, Then the API returns 410 and no session is created"):
```python
def test_AC_FR_1_1_expired_link_returns_410_and_no_session():
link = seed_magic_link(age_minutes=16) # Given
response = client.get(link.url) # When
assert response.status_code == 410 # Then
assert session_store.count() == 0
```
---
## Cross-References (read by other skills)
- The `constitution` field in frontmatter is read by `spec-crosscheck` to verify rule coverage.
- The `slug` is reused by `implementation-plan` to name the plan file (e.g., `docs/plans/<slug>-plan.md`).
- FR/NFR IDs are referenced by tasks in the plan ("T-3 implements FR-2").
- AC IDs are carried into test names by the Test Skeletons above; `spec-crosscheck` Check C reads them for AC↔test traceability.
- The `Out of Scope` list is enforced by `spec-crosscheck` Check F.
- The `Constitution Waivers` section is enforced by `spec-crosscheck` Check B.
---
## Style Guidelines
- **Voice:** declarative, present tense ("The system rejects expired tokens", not "should reject")
- **IDs:** never reuse — once an FR-3 is dropped, never replace it with a new FR-3
- **Edge cases:** prefer concrete failures over generic ones ("user clicks expired link" not "error states")
- **Granularity:** one FR = one user-observable behavior. If you need "and" in an FR, split it.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |