gh-jezweb-claude-skills-skills-project-workflow/commands/plan-feature.md

Plan Feature

Add a new feature to an existing project by generating new phases and integrating them into IMPLEMENTATION_PHASES.md and SESSION.md.

---

Your Task

Follow these steps to plan and integrate a new feature into an existing project.

1. Check Prerequisites

Check that planning docs exist:

ls SESSION.md docs/IMPLEMENTATION_PHASES.md

If SESSION.md doesn't exist:

• Output: "❌ No SESSION.md found. This command is for existing projects."
• Suggest: "For new projects, use /plan-project instead."
• Stop

If IMPLEMENTATION_PHASES.md doesn't exist:

• Output: "❌ No IMPLEMENTATION_PHASES.md found."
• Suggest: "Create baseline planning with /plan-project first."
• Stop

Read SESSION.md to extract:

• Current phase number and name
• Current phase status (🔄 in progress, ✅ complete, ⏸️ pending)
• Current stage (Implementation/Verification/Debugging)

Read IMPLEMENTATION_PHASES.md to extract:

• All existing phases
• Last phase number
• Project tech stack

2. Check Current Phase Status

If current phase is in progress (🔄):

Output warning:

⚠️ WARNING: Phase [N] - [Name] is in progress.

Current phase status: [Stage]
Progress: [Show task completion from SESSION.md]

Adding a new feature now may cause confusion. Options:

1. Finish current phase first (recommended)
2. Add feature anyway (will append after current phases)
3. Cancel and come back later

Your choice (1/2/3):

If choice 1 (Finish current phase):

• Output: "Complete Phase [N] first, then run /plan-feature again."
• Stop

If choice 2 (Add anyway):

• Output: "⚠️ Adding feature. New phases will start after Phase [last phase number]."
• Continue

If choice 3 (Cancel):

• Output: "Cancelled. Run /plan-feature when current phase is complete."
• Stop

If current phase is complete (✅) or paused (⏸️):

• Continue normally

3. Gather Feature Requirements

Ask clarifying questions about the feature:

I'll help plan this feature. A few questions:

1. Feature Description: What does this feature do?
   (Be specific: "Add user profiles with avatar upload" vs "Add profiles")

2. Scope: Is this feature...
   - Small (1-2 phases, ~2-4 hours)
   - Medium (3-4 phases, ~6-10 hours)
   - Large (5+ phases, ~12+ hours)

3. Dependencies: Does this feature require...
   - New database tables/columns?
   - New API endpoints?
   - New UI components?
   - Third-party integrations?
   - All of the above?

4. Priority: When should this feature be built?
   - Immediately after current phase
   - After specific phase: [specify phase number]
   - At the end (append to existing phases)

5. Integration: Does this feature...
   - Modify existing functionality (may require changes to existing phases)?
   - Add completely new functionality (independent phases)?

Wait for user answers.

4. Generate Feature Phases

Invoke project-planning skill to generate phases for this feature:

• Provide feature description + requirements from user
• Provide context of existing project (tech stack from IMPLEMENTATION_PHASES.md)
• Request specific phase types needed (Database, API, UI, Integration)
• Skill generates new phases following validation rules

Skill output: New phases in IMPLEMENTATION_PHASES.md format

Verify phases generated:

• Check that phases follow context-safe sizing (≤8 files, 2-4 hours)
• Check that phases have verification criteria
• Check that phases have concrete tasks

5. Integrate into IMPLEMENTATION_PHASES.md

Read existing IMPLEMENTATION_PHASES.md completely.

Determine insertion point based on user's priority answer:

• Immediately after current: Insert after current phase number
• After specific phase: Insert after specified phase number
• At the end: Append to end of document

If inserting mid-document:

• Renumber all subsequent phases (e.g., if inserting after Phase 3, old Phase 4 becomes Phase 7 if adding 3 phases)
• Update any cross-phase references

Add feature separator before new phases:

---

## Feature: [Feature Name] (Added [YYYY-MM-DD])

[Feature description from user]

---

Insert new phases with proper formatting:

• Match existing document style
• Include all required sections (Type, Estimated Time, Files, Tasks, Verification Criteria, Exit Criteria)
• Include file maps if phases are API/UI/Integration type
• Number phases correctly

Write updated IMPLEMENTATION_PHASES.md

6. Update SESSION.md

Read current SESSION.md completely.

Determine where to insert new phases (matching IMPLEMENTATION_PHASES.md):

• Same position as in IMPLEMENTATION_PHASES.md
• Maintain phase number consistency

Add new phases to SESSION.md:

• Set status as ⏸️ (pending) for all new phases
• Use collapsed format (just header + spec reference)
• Renumber existing phases if inserted mid-document

Example insertion:

## Phase 3: Tasks API ✅
**Completed**: 2025-11-07 | **Checkpoint**: abc1234
**Summary**: CRUD endpoints with validation

## Phase 4: User Profiles Database ⏸️
**Type**: Database | **Added**: 2025-11-07
**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-4`

## Phase 5: User Profiles API ⏸️
**Type**: API | **Added**: 2025-11-07
**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-5`

## Phase 6: User Profiles UI ⏸️
**Type**: UI | **Added**: 2025-11-07
**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-6`

## Phase 7: Task UI ⏸️
**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-7`
[... existing phase, renumbered from Phase 4 ...]

Update "Next Action" if feature is immediate priority:

• If user chose "Immediately after current" and current phase is complete
• Update Next Action to first task of first feature phase

Write updated SESSION.md

7. Update Related Docs (If Applicable)

Check if feature requires doc updates:

If feature adds database tables:

• Ask: "Should I update DATABASE_SCHEMA.md with new tables? (y/n)"
• If yes: Read DATABASE_SCHEMA.md, add schema definitions for new tables, write updated file

If feature adds API endpoints:

• Ask: "Should I update API_ENDPOINTS.md with new routes? (y/n)"
• If yes: Read API_ENDPOINTS.md, add endpoint documentation, write updated file

If feature changes architecture:

• Ask: "Should I update ARCHITECTURE.md with new data flows? (y/n)"
• If yes: Read ARCHITECTURE.md, update architecture diagrams/descriptions, write updated file

If feature adds UI components:

• Ask: "Should I update UI_COMPONENTS.md with new components? (y/n)"
• If yes: Read UI_COMPONENTS.md, add component documentation, write updated file

8. Create Git Commit for Feature Planning

Stage changes:

git add docs/IMPLEMENTATION_PHASES.md SESSION.md

If other docs were updated:

git add docs/DATABASE_SCHEMA.md docs/API_ENDPOINTS.md docs/ARCHITECTURE.md docs/UI_COMPONENTS.md

Create structured commit:

Extract from generated phases:

• Number of new phases
• Phase names and types
• Total estimated hours

git commit -m "$(cat <<'EOF'
Add feature: [Feature Name]

Added [N] new phases for [feature description]:
- Phase [X]: [Name] ([Type], [Y] hours)
- Phase [X+1]: [Name] ([Type], [Y] hours)
[... list all new phases ...]

Integration point: [After Phase N / End of plan]
Estimated: [X] hours (~[Y] minutes human time)

Docs updated:
- IMPLEMENTATION_PHASES.md (added phases)
- SESSION.md (added pending phases)
[- DATABASE_SCHEMA.md] (if updated)
[- API_ENDPOINTS.md] (if updated)
[- ARCHITECTURE.md] (if updated)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"

9. Output Feature Planning Summary

Display formatted summary:

═══════════════════════════════════════════════
   FEATURE PLANNING COMPLETE
═══════════════════════════════════════════════

✨ Feature: [Feature Name]
📦 Scope: [Small/Medium/Large] ([N] phases, [X] hours)

───────────────────────────────────────────────
NEW PHASES ADDED:
───────────────────────────────────────────────

Phase [X]: [Name] ([Type], [X] hours) ⏸️
Phase [Y]: [Name] ([Type], [X] hours) ⏸️
Phase [Z]: [Name] ([Type], [X] hours) ⏸️
[... list all new phases ...]

───────────────────────────────────────────────
INTEGRATION:
───────────────────────────────────────────────

• Inserted: [After Phase N / End of plan]
• Existing phases: [Renumbered from Phase X / Unchanged]
• Total project phases: [N]

───────────────────────────────────────────────
UPDATED DOCS:
───────────────────────────────────────────────

✅ IMPLEMENTATION_PHASES.md
✅ SESSION.md
[✅ DATABASE_SCHEMA.md] (if updated)
[✅ API_ENDPOINTS.md] (if updated)
[✅ ARCHITECTURE.md] (if updated)
[✅ UI_COMPONENTS.md] (if updated)

───────────────────────────────────────────────
CURRENT STATUS:
───────────────────────────────────────────────

Current Phase: Phase [N] - [Name] ([Status emoji])
New feature phases: ⏸️ (pending)

Next Action: [Current Next Action from SESSION.md]

═══════════════════════════════════════════════

10. Ask About Next Steps

Ask user:

Feature planning complete. What would you like to do?

Options:
1. Continue with current phase (recommended if in progress)
2. Start new feature immediately (skip ahead to feature phases)
3. Review feature phases first
4. Push to remote

Your choice (1/2/3/4):

If choice 1 (Continue current):

• Output: "Continuing with current work. Feature will be built later."
• No action needed

If choice 2 (Start feature immediately):

• Output: "⚠️ Skipping ahead to feature phases."
• Ask: "Update SESSION.md to mark current phase as paused (⏸️) and start feature? (y/n)"
• If yes:
  • Update SESSION.md: Change current phase to ⏸️, change first feature phase to 🔄
  • Expand first feature phase with task checklist
  • Set "Next Action" to first task of first feature phase
  • Output: "✅ SESSION.md updated. Starting [First Feature Phase Name]"

If choice 3 (Review first):

• Output: "Review new phases in docs/IMPLEMENTATION_PHASES.md. Run /continue-session when ready."
• Wait for user

If choice 4 (Push to remote):

git push

• Output: "✅ Feature planning pushed to remote" (if success)
• Output: "❌ Push failed. Run git push manually when ready." (if failed)

---

Error Handling

SESSION.md doesn't exist:

• Output: "❌ No SESSION.md found. This command is for existing projects."
• Suggest: "Use /plan-project for new projects."
• Stop

IMPLEMENTATION_PHASES.md doesn't exist:

• Output: "❌ No IMPLEMENTATION_PHASES.md found."
• Suggest: "Run /plan-project to create baseline planning."
• Stop

Current phase is in progress and user cancels:

• Output: "Cancelled. Finish current phase first, then run /plan-feature."
• Stop

Feature description is vague:

• Output: "❌ Feature description unclear."
• Ask: "Please describe what this feature does in 1-2 sentences."
• Wait for clarification

project-planning skill fails:

• Output: "❌ Failed to generate feature phases."
• Suggest: "Describe phases manually and I'll integrate them."
• Wait for user input

Phase numbering conflict:

• Output: "⚠️ Phase numbering conflict detected."
• Output: "Renumbering all phases to maintain sequence."
• Show old → new phase number mapping
• Continue with renumbering

File conflict with existing phases:

• Output: "⚠️ Warning: Feature phase [N] modifies files used in existing Phase [X]."
• Output: "Files: [list conflicting files]"
• Output: "This may require refactoring. Review carefully."
• Ask: "Continue anyway? (y/n)"

Git commit fails:

• Output: "⚠️ Git commit failed: [error message]"
• Output: "Fix git issue and commit manually."
• Ask: "Continue without commit? (y/n)"

Git push fails:

• Output: "⚠️ Push failed: [error message]"
• Output: "You can run git push manually later."
• Continue (not critical)

Related doc doesn't exist:

• Output: "⚠️ [Doc name] not found. Skipping update."
• Continue with other docs

---

Success Criteria

✅ Existing planning docs verified ✅ Current phase status checked ✅ Feature requirements gathered (5 questions answered) ✅ New phases generated with validation ✅ IMPLEMENTATION_PHASES.md updated with new phases ✅ SESSION.md updated with new pending phases ✅ Phase numbering consistent across all docs ✅ Related docs updated (if applicable) ✅ Git commit created for feature planning ✅ User has clear understanding of integration point ✅ User can continue current work or start feature