182 lines
6.3 KiB
Markdown
182 lines
6.3 KiB
Markdown
---
|
|
tags: ["workflow", "spec", "feature-spec", "project-management", "conversational"]
|
|
description: "Create local feature specifications through natural language conversation"
|
|
argument-hint: "[SPEC-### | --epic PROJ-### | --update SPEC-###]"
|
|
allowed-tools: ["Read", "Write", "Edit", "Glob", "Grep", "Task", "TodoWrite"]
|
|
model: claude-opus-4-5
|
|
references_guidelines:
|
|
- docs/development/workflows/pm-workflows.md # Spec creation workflows and file formats
|
|
- docs/development/misc/jira-integration.md # Jira mode (if enabled in CLAUDE.md)
|
|
---
|
|
|
|
# /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
|
|
|
|
```bash
|
|
/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
|
|
|
|
1. **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)
|
|
|
|
2. **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
|
|
|
|
3. **Conversational Creation**
|
|
- Main goal, primary users
|
|
- Acceptance scenarios (2-5 Given-When-Then)
|
|
- Success criteria, OUT of scope
|
|
- Follow spec-template.md structure
|
|
|
|
4. **Create Spec File**
|
|
- Write pm/specs/SPEC-###-<name>.md
|
|
- Mark Jira source if --epic used
|
|
|
|
5. **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
|
|
|
|
6. **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:**
|
|
|
|
1. **Load Context**
|
|
- Read SPEC-###-<name>.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
|
|
|
|
2. **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?
|
|
|
|
3. **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
|
|
|
|
4. **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
|
|
|
|
5. **Document Changes**
|
|
- Add update note to spec with timestamp
|
|
- Summary of what changed and why
|
|
- Link to completed tasks that informed changes
|
|
|
|
**Example:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
/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.
|