Feature Spec

---
name: feature-spec
description: Define feature requirements (problem, users, scope, acceptance criteria) through guided Q&A and write FEATURE_SPEC.md. Use when starting a new feature.
argument-hint: <feature-name>
allowed-tools: Bash, Read, Write, AskUserQuestion
---

Generate a feature specification document for the feature `$1`.

## Workflow

Copy this checklist and track progress:

```
Feature Spec Progress:
- [ ] Directory guard
- [ ] Handle arguments (feature name)
- [ ] Plan status guard
- [ ] Create feature directory
- [ ] Existing file guard (prevent overwrite)
- [ ] Run guided Q&A process (from PROMPT.md)
- [ ] Write FEATURE_SPEC.md
- [ ] Update plans/PLAN_STATUS.md
- [ ] Capture deferred requirements
- [ ] Cross-model review (if Codex available)
```

## Directory Guard

1. If `.toolkit-marker` exists in the current working directory → **STOP**:
   "You're in the toolkit repo. Feature skills run from your project directory.
    Run: `cd ~/Projects/your-project && /feature-spec $1`"

2. Check `.claude/toolkit-version.json` exists in the current working directory (confirms `/setup` was run).
   If missing → **STOP**: "Toolkit not installed. Run `/setup` from the toolkit first."

3. Check `AGENTS.md` exists in the current working directory (confirms project root).
   If missing → **STOP**: "Run this from your project root (where AGENTS.md lives)."

## Arguments

- `$1` = feature name (e.g., `analytics`, `dark-mode`)
- If `$1` is empty, ask the user for the feature name
- `PROJECT_ROOT` = current working directory
- `FEATURE_DIR` = `PROJECT_ROOT/features/$1`

## Plan Status Guard

Read `~/.claude/skills/shared/PLAN_STATUS.md` before writing files.

1. Ensure `PROJECT_ROOT/plans/` exists.
2. Read `PROJECT_ROOT/plans/PLAN_STATUS.md` if it exists.
3. If another path is listed as `Current plan` with `Current status: active`,
   ask whether this feature supersedes it, should be recorded as non-current
   planned work, or should abort.
4. If this feature supersedes the current plan, record the previous plan as
   `superseded` in the history table.
5. If `plans/PLAN_STATUS.md` is missing, create it after writing the feature spec.

Create `features/$1/` if it doesn't exist:
```bash
mkdir -p "features/$1"
```

## Existing File Guard (Prevent Overwrite)

Before asking any questions, check whether `FEATURE_DIR/FEATURE_SPEC.md` already exists.

- If it does not exist: continue normally.
- If it exists: **STOP** and ask the user what to do:
  1. **Archive then overwrite (recommended)**: copy the existing feature plan set to `features/archive/YYYYMMDD-HHMMSS-$1/`, mark the archived snapshot as superseded when practical, then write the new document to `FEATURE_DIR/FEATURE_SPEC.md`
  2. **Overwrite**: replace `FEATURE_DIR/FEATURE_SPEC.md` with the new document
  3. **Abort**: do not write anything; suggest they rename/move the existing file first

## Process

Read `.claude/skills/feature-spec/PROMPT.md` and follow its instructions exactly:

1. Ask the user to describe the feature they want to add
2. Work through each question category (Problem, Users, Behavior, Integration, Scope)
3. Make recommendations with confidence levels
4. Generate the final FEATURE_SPEC.md document

## Output

Write the completed specification to `FEATURE_DIR/FEATURE_SPEC.md`.

Update `PROJECT_ROOT/plans/PLAN_STATUS.md` so:
- `Current plan` is `features/$1/` unless the user explicitly chose non-current planned work
- `Current type` is `feature`
- `Current stage` is `feature-spec`
- `Current status` is `active` for current work, or `planned` for non-current work
- the history table records any archived or superseded plan snapshot

## Deferred Requirements Capture (During Q&A)

**IMPORTANT:** Capture deferred requirements interactively during the Q&A process, not after.

Write deferred items to `PROJECT_ROOT/DEFERRED.md` (not the feature directory).

### When to Trigger

During the Q&A, watch for signals that the user is deferring something:
- "out of scope"
- "not in this feature" / "separate feature"
- "v2" / "future version"
- "later" / "eventually"
- "follow-up" / "future enhancement"
- "nice to have"
- "we'll skip that for now"

### Capture Flow

When you detect a deferral signal, immediately use AskUserQuestion:

```
Question: "Would you like to save this to your deferred requirements?"
Header: "Defer?"
Options:
  - "Yes, capture it" — I'll ask a few quick questions to document it
  - "No, skip" — Don't record this
```

**If user selects "Yes, capture it":**

Ask these clarifying questions:

1. **What's being deferred?**
   "In one sentence, what's the requirement or feature?"
   (Pre-fill with your understanding from context)

2. **Why defer it?**
   Options: "Out of scope for this feature" / "Separate feature" / "V2" / "Needs more research" / "Other"

3. **Notes for later?**
   "Any context that will help when revisiting this?"
   (Optional — user can skip)

### Write to DEFERRED.md Immediately

After collecting answers, append to `PROJECT_ROOT/DEFERRED.md` right away.

**If file doesn't exist, create it:**

```markdown
# Deferred Requirements

> Captured during specification Q&A. Review when planning future versions.

## From FEATURE_SPEC.md: {FEATURE_NAME} ({date})

| Requirement | Reason | Notes |
|-------------|--------|-------|
| {user's answer} | {selected reason} | {notes or "—"} |
```

**If file exists, add new feature section or append to existing:**

```markdown

## From FEATURE_SPEC.md: {FEATURE_NAME} ({date})

| Requirement | Reason | Notes |
|-------------|--------|-------|
| {user's answer} | {selected reason} | {notes or "—"} |
```

### Continue Q&A

After capturing (or skipping), continue the spec Q&A where you left off.

## Lean Mode (`--lean`)

When `--lean` is passed:
- **Skip all post-generation gates.** Do not run `/verify-spec`, `/codex-consult`, or `/criteria-audit`. Report each as `LEAN_SKIP` in the output.
- All other steps (Q&A, document generation, deferred capture) run normally.

## Post-Generation Gates (MANDATORY unless `--lean`)

These gates MUST execute before you produce the "Next Step" output. The output template requires results from each gate. Reporting `SKIPPED` without `--lean` is a skill violation — go back and run the gate.

### Gate 1: Spec Verification

After writing FEATURE_SPEC.md, run quality verification:

1. Invoke `/verify-spec feature-spec` on the generated document
2. This runs **quality checks only** (no upstream context preservation since FEATURE_SPEC.md has no upstream):
   - Q-001: Vague/unmeasurable language ("fast", "user-friendly", "simple")
   - Q-002: Subjective terms without targets ("better", "improved")
   - Q-003: Missing rationale for decisions
   - Q-005: Implicit assumptions
   - Q-006: Conflicting requirements
   - Q-PS-001: Missing user flow (feature mentioned without step-by-step interaction)
   - Q-PS-002: Only happy path described (no edge cases)
   - Q-PS-003: Unbounded scope ("all", "any", "every" without limits)
   - Q-PS-004: Missing non-functional requirements (performance, security, accessibility)
3. Present CRITICAL issues with resolution options (max 2 fix iterations)
4. Do not proceed to Gate 2 until verification passes or user explicitly chooses to proceed with noted issues

### Gate 2: Cross-Model Review

After verification, run cross-model review if Codex CLI is available:

1. Check if Codex CLI is installed: `codex --version`
2. If available, run `/codex-consult` on the generated document
3. Present any findings to the user before proceeding

**Consultation invocation:**
```
/codex-consult --research "feature requirements, user stories" features/$1/FEATURE_SPEC.md
```

**If Codex finds issues:**
- Show critical issues and recommendations
- Ask user: "Address findings before proceeding?" (Yes/No)
- If Yes: Apply suggested fixes
- If No: Continue with noted issues

**If Codex CLI is not installed or not authenticated:** Report `UNAVAILABLE` (not `SKIPPED` — the distinction matters).

## Error Handling

| Situation | Action |
|-----------|--------|
| Feature name argument is empty and user does not provide one | Prompt again with AskUserQuestion; do not proceed without a feature name |
| FEATURE_SPEC.md already exists and user selects "Abort" | Stop immediately, do not write any files, suggest renaming or moving the existing file |
| PROMPT.md not found at `.claude/skills/feature-spec/PROMPT.md` | Stop and report "Skill asset missing — reinstall toolkit or run /setup" |
| DEFERRED.md write fails (permissions or disk) | Output deferred items to terminal, warn user, continue with spec generation |
| Codex CLI invocation fails or times out | Log the error, skip cross-model review, proceed to Next Step |

## Next Step

**Pre-condition**: All gates above have completed, or `--lean` was explicitly passed. If you have not run them, STOP and run them now. Reporting `SKIPPED` without `--lean` is a skill violation.

When complete, inform the user:
```
FEATURE_SPEC.md created at features/$1/FEATURE_SPEC.md
Deferred Requirements: {count} items captured to DEFERRED.md
Verification: PASSED | PASSED WITH NOTES | NEEDS REVIEW | LEAN_SKIP
Cross-Model Review: PASSED | PASSED WITH NOTES | UNAVAILABLE | LEAN_SKIP

Next: Run /feature-technical-spec $1
```