wf-phase1-spec

name	wf-phase1-spec
description	Phase 1 - Create an initial feature specification from a roadmap item. Generates a structured spec file ready for Phase 2 review.

Phase 1: Create Feature Specification

Generate a comprehensive initial spec for a roadmap feature.

Feature to Specify

$ARGUMENTS

Instructions

Step 0: Read Project Config

1. Try to read .claude/workflow/project-config.json
2. Extract values (use these defaults if file is absent or field is missing):
   • specDir = docs/specs
   • archiveDir = docs/specs/archive
   • roadmapFile = ROADMAP.md
3. Use {specDir}, {archiveDir}, and {roadmapFile} throughout this skill

Step 1: Handle Missing Arguments

If no feature ID was provided in arguments:

1. Read {roadmapFile} to find features marked with ⬜ (not implemented)
2. Use AskUserQuestion to ask the user which feature to create a spec for:
   • List up to 4 unimplemented features as options
   • Include feature ID and brief description in each option

Step 2: Gather Context

Once you have a feature ID:

1. Read {roadmapFile} to find the feature description and requirements
2. Read CLAUDE.md to understand existing patterns and implemented features
3. Check for any reference documentation in the repo (e.g., docs/, references/, specs/)
4. Review related existing specs in {specDir}/ for format and patterns
5. Check existing code for any partial implementations or related systems

Step 3: Analyze Dependencies

Identify:

• Which existing systems this feature integrates with
• Required modifications to existing files
• New files/classes needed
• Database schema changes (if any)
• Configuration/constants to add

Step 4: Create Spec Directory

Create the directory: {specDir}/{feature-id-lowercase}/ (e.g., {specDir}/sf14/ for SF-14)

Step 5: Generate Spec File

Create {specDir}/{feature-dir}/{FEATURE-ID}_{NAME}_SPEC.md using this template:

# {FEATURE-ID}: {Feature Name} Specification

**Status**: DRAFT
**Created**: {date}
**Complexity**: {Simple | Medium | Complex}

---

## Complexity Tier

**Tier**: {Simple | Medium | Complex}
**Justification**: {Why this tier - be specific}

| Tier | Criteria | Recommended Phases |
|------|----------|-------------------|
| Simple | Single pattern, <100 LOC, follows existing templates | 1 → 4 → 5 |
| Medium | 2-5 files, follows existing patterns, some integration | 1 → 2 (3 agents) → 3 → 4 → 5 |
| Complex | New patterns, architecture, 5+ files, novel mechanics | 1 → (1.5) → 2 → 3 → 4 → 5 → 6 |

---

## Overview

{Brief description of what this feature does and why it matters}

---

## Components

### 1. {Component Name}

{Description of this component}

**Formula / Logic** (if applicable):

result = baseValue × modifier × efficiency

Where:
- `baseValue` = description
- `modifier` = description

### 2. {Next Component}

{Continue for each component}

---

## Configuration / Constants (if applicable)

| Name | Value | Description |
|------|-------|-------------|
| `CONSTANT_NAME` | value | What this controls |

---

## Architecture Integration (if applicable)

{Where this fits in the system — e.g., processing order, event pipeline, request lifecycle}

---

## Files

### Added
- `NewComponent.ext` - Core logic for {feature}
- `NewResult.ext` - Result type for {operation}

### Modified
- `ExistingFile.ext` - {What changes and why}

---

## HTTP Endpoints (if applicable)

| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/{resource}/{action}` | {description} |

---

## Test Strategy

| Test | Focus | Estimated Cases |
|------|-------|-----------------|
| `{Feature}Test` | Core logic verification | 10-15 |
| `{Feature}IntegrationTest` | End-to-end integration | 5-8 |
| `{Feature}EdgeCaseTest` | Boundary conditions | 8-12 |

---

## Key Implementation Notes

1. {Important architectural decision or constraint}
2. {Performance consideration}
3. {Integration note with existing systems}

---

## Related Specifications

- [{Related Feature}]({path}) - {How it relates}

---

## Open Questions

- [ ] {Question needing resolution before implementation}
- [ ] {Another open question}

---

**Last Updated**: {date}

Step 6: Output Summary

After creating the spec, display:

1. Confirm the file was created with its path
2. List each component with a 1-2 sentence description
3. List all configuration/constants being added
4. List all files being added/modified
5. List each open question with context
6. Show any HTTP endpoints being added

Then proceed to Step 7.

Step 7: Write Context and Prompt for Next Step

7a: Write Context File

Create/update .claude/workflow/phase-context.json:

{
  "specPath": "{full spec file path}",
  "featureId": "{FEATURE-ID}",
  "lastPhase": "wf-phase1-spec",
  "timestamp": "{current ISO datetime}",
  "context": {
    "complexityTier": "{Simple | Medium | Complex}",
    "complexityJustification": "{brief reason for tier selection}",
    "components": ["{list component names identified}"],
    "openQuestions": {count of open questions},
    "properties": ["{list constants/config names being added}"],
    "filesAffected": {count of files added + modified},
    "recommendedNextPhase": "{wf-phase1-iterate | wf-phase2-review | wf-phase4-implement-sonnet}"
  }
}

7b: Prompt for Next Step (Based on Complexity Tier)

1. Read .claude/templates/context-reminder.md if it exists and display it; otherwise display: "Context Management: Consider starting a new conversation before the next phase to free up context window for better performance."
2. Based on the complexity tier in the spec, recommend different paths:

For Simple tier:

• Use AskUserQuestion:
  • header: "Next step"
  • question: "This is a Simple tier feature. Recommended: skip reviews and go straight to implementation."
  • option1: label="Continue to /wf-phase4-implement-sonnet (Recommended)", description="Skip Phase 2/3 - pattern-following feature"
  • option2: label="Continue to /wf-phase2-review anyway", description="Run review despite simple tier"
  • option3: label="Edit spec first", description="Make changes before proceeding"

For Medium tier:

• Use AskUserQuestion:
  • header: "Next step"
  • question: "This is a Medium tier feature. Recommended: run Phase 2 with 3 agents."
  • option1: label="Continue to /wf-phase2-review (Recommended)", description="Context auto-loaded - agents selected based on feature type"
  • option2: label="Continue to /wf-phase1-iterate first", description="Quick agent review before full Phase 2"
  • option3: label="Edit spec first", description="Make changes before proceeding"

For Complex tier:

• Use AskUserQuestion:
  • header: "Next step"
  • question: "This is a Complex tier feature. Recommended: run Phase 1.5 first for early feedback."
  • option1: label="Continue to /wf-phase1-iterate (Recommended)", description="Quick agent review before full Phase 2"
  • option2: label="Continue to /wf-phase2-review", description="Skip to full review"
  • option3: label="Edit spec first", description="Make changes before proceeding"

3. If user selects "Clear context and stop", delete .claude/workflow/phase-context.json