/spec Command

WHAT: Create/refine local feature specifications through conversational interaction.

WHY: Natural conversation ensures complete spec structure without rigid forms. Specs document WHAT to build locally, separate from PM tool tracking.

HOW: See pm-guide.md for spec creation workflows, file formats, and task suggestion strategies. For Jira mode, see jira-integration.md.

Usage

/spec                   # Start conversation (create new or work with existing)
/spec SPEC-###          # Work with specific spec
/spec --epic PROJ-###   # Create spec from Jira epic (requires Jira integration)
/spec --update SPEC-### # Review and update spec based on recent development (run after task completion)

Execution Flow

Before you start: Read pm-guide.md for spec creation workflows, file formats, and task suggestion strategies. For Jira mode, read jira-integration.md.

High-Level Steps

Determine Mode
- No arguments: Ask "Create new or work on existing?"
- SPEC-### provided: Refinement mode
- --epic PROJ-###: Fetch Jira epic and pre-populate
- --update SPEC-###: Review mode (analyze recent development and update spec)
Load Context
- Read docs/development/templates/spec-template.md for structure
- Glob pm/specs/SPEC-*.md for next number
- If --epic: Fetch from Jira via Atlassian MCP
Conversational Creation
- Main goal, primary users
- Acceptance scenarios (2-5 Given-When-Then)
- Success criteria, OUT of scope
- Follow spec-template.md structure
Create Spec File
- Write pm/specs/SPEC-###-.md
- Mark Jira source if --epic used
Task Creation (interactive)
- Suggest 2-3 foundational tasks based on spec scope
- Interactive loop: Which to create? (yes/all/custom/stop)
- For each selected task:
  - Create pm/issues/TASK-###-name/ directory
  - Create TASK.md from templates/task-template.md template
  - Link task → spec (frontmatter: spec: SPEC-###)
  - Update spec → task reference (Tasks section)
- Per pm-workflows.md task suggestion strategy
Optional Jira Epic
- Ask: Create corresponding Jira epic?
- If yes: Run /jira-epic --spec SPEC-###

See pm-guide.md "Spec Creation Workflows" for complete conversational flow patterns.

Update Mode (`--update SPEC-###`)

When to use: After completing tasks to sync spec with implementation reality.

Workflow:

Load Context
- Read SPEC-###-.md
- Read all linked TASK-###/TASK.md files
- Read all linked TASK-###/WORKLOG.md files (completed tasks)
- Read recent git commits for the spec's feature branch
Analyze Development Activity
- What was actually implemented vs planned?
- Were there scope changes during implementation?
- Did acceptance scenarios change?
- Were new edge cases discovered?
- Did any requirements change?
Review Incomplete Tasks
- Read all tasks with status: todo or in_progress
- Based on completed work, do these tasks still make sense?
- Should any be:
  - Modified (scope changed based on discoveries)
  - Removed (no longer needed)
  - Split (too large based on actual complexity)
  - Merged (smaller than expected)
- Suggest changes interactively
Update Spec
- Revise description if scope changed
- Update/add acceptance scenarios based on discoveries
- Update definition of done if needed
- Mark completed tasks as done
- Add new tasks if gaps discovered
- Update "Out of Scope" section if boundaries changed
Document Changes
- Add update note to spec with timestamp
- Summary of what changed and why
- Link to completed tasks that informed changes

Example:

# After completing TASK-001 and TASK-002 for SPEC-001
/spec --update SPEC-001

→ Reads SPEC-001-user-authentication.md
→ Reads completed TASK-001/WORKLOG.md, TASK-002/WORKLOG.md
→ Reviews remaining TASK-003, TASK-004, TASK-005

AI: "During TASK-001, you implemented OAuth in addition to email/password.
     Should we update the spec to include OAuth in the description?"

User: "Yes"

AI: "TASK-004 was for 'password complexity rules', but you already
     implemented basic validation in TASK-001. Should we:
     1. Remove TASK-004 (no longer needed)
     2. Modify TASK-004 to focus on advanced rules only
     3. Keep as-is"

User: "2"

→ Updates SPEC-001 with OAuth in description
→ Updates TASK-004 description to "Advanced password rules (strength meter, common password detection)"
→ Adds update note with timestamp

Integration with Workflow:

/implement TASK-001 --full  # Complete task
/quality                     # Verify quality
/spec --update SPEC-001      # Sync spec with reality
/plan TASK-002              # Plan next task with updated context

Workflow Patterns

Local-first (recommended):

/spec → /jira-epic --spec SPEC-### → /plan TASK-### → /implement → /spec --update SPEC-###

Jira-first:

/spec --epic PROJ-### → /plan TASK-### → /implement → /spec --update SPEC-###

Local-only:

/spec → /plan TASK-### → /implement → /spec --update SPEC-###

Iterative development cycle:

/spec SPEC-001                    # Create spec with tasks
/plan TASK-001 → /implement       # Complete first task
/spec --update SPEC-001           # Review and adjust remaining work
/plan TASK-002 → /implement       # Next task with updated context
/spec --update SPEC-001           # Continue iterating

Error Handling

--epic without Jira: Enable Jira in CLAUDE.md or omit --epic flag Epic not found: Verify epic exists and you have access MCP unavailable: Fallback to manual creation

See jira-integration.md for complete error scenarios and solutions.

6.3 KiB Raw Permalink Blame History