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:

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:

# 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:

## 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