plan-workflow

Plan Workflow

Execute full implementation workflow from Claude Code plan files (~/.claude/plans/*.md).

Features:

• Plan file parsing with Phase/Task extraction
• GitHub issue creation and status tracking
• Design document verification
• Parallel task execution with automated commits

Prerequisites

• GitHub CLI (gh) authenticated: gh auth status
• Project scope required: gh auth refresh -s project,read:project

Execution Checklist

Execute ALL steps in order. DO NOT skip any step.

---

1. Find Plan File

Check plan file path from user arguments.

If path provided:

• Read the file using Read tool

If no path provided:

• Search for .md files in ~/.claude/plans/ directory using Glob
• Sort by modification time (newest first)
• Use AskUserQuestion to let user select:

{
  "questions": [
    {
      "question": "Which plan file to execute?",
      "header": "Select Plan",
      "multiSelect": false,
      "options": [
        {
          "label": "{plan-file-1.md}",
          "description": "Modified: {date}"
        },
        {
          "label": "{plan-file-2.md}",
          "description": "Modified: {date}"
        }
      ]
    }
  ]
}

If no files found:

"No plan files found. Use Claude Code plan mode to create a plan first."

---

2. Parse Plan File

Read plan file and extract phases and tasks.

Parsing Rules:

1. Phase Recognition: ## or ### level headings as phases

   • Patterns: ## 1., ## Step 1:, ## Phase 1:, ## Task 1:
   • Exclude: ## Overview, ## Summary, ## Notes, ## 검증 방법, ## GitHub 연동, ## 파일 구조

2. Task Recognition:

   • - [ ] checkbox items (priority)
   • - regular list items (only if no checkboxes exist)
   • Task description may include issue reference: #12, #13

3. Skip Completed: Items marked - [x] are skipped

4. Extract GitHub References:

   • Issue numbers: #12, #13
   • Issue URLs: https://github.com/{owner}/{repo}/issues/{number}

5. Extract Design Documents:

   • Patterns: 검증 문서:, Reference:, docs/
   • Example: 검증 문서: 00-overview.md, 02-design-system.md

Parsed Result Structure:

phases = [
  {
    name: "Task 1: #12 프로젝트 초기 설정",
    tasks: [
      {
        description: "디렉토리 구조 정리",
        issueNumber: 12,
        designDocs: ["docs/frontend/00-overview.md"]
      }
    ],
    verificationDocs: ["00-overview.md", "02-design-system.md"]
  }
]

---

3. Display Plan Summary and Confirm

Display parsed results:

Plan Parsing Complete

File: {plan-file-path}
Phases: {N}
Total Tasks: {M}
GitHub Issues Found: {list of #numbers}
Design Documents: {list}

Phase 1: {name} ({task_count} tasks) - Issue #{number}
Phase 2: {name} ({task_count} tasks) - Issue #{number}
...

Use AskUserQuestion to confirm execution:

{
  "questions": [
    {
      "question": "Execute this plan?",
      "header": "Confirm",
      "multiSelect": false,
      "options": [
        {
          "label": "Execute All",
          "description": "Execute all phases in order"
        },
        {
          "label": "Select Phases",
          "description": "Choose which phases to execute"
        }
      ]
    }
  ]
}

---

4. Check GitHub Configuration

4.1 Get Repository Info

gh repo view --json nameWithOwner,owner -q '.nameWithOwner + " " + .owner.login'

4.2 Check Existing Issues

For each issue number found in plan:

gh issue view {number} --json state,title,body,labels

4.3 GitHub Integration Decision

If issues exist and are valid:

• Use existing issues for status tracking

If issues don't exist or plan has no issue references:

Use AskUserQuestion:

{
  "questions": [
    {
      "question": "Create GitHub issues for this plan?",
      "header": "GitHub",
      "multiSelect": false,
      "options": [
        {
          "label": "Create Issues",
          "description": "Create Epic and Phase issues on GitHub"
        },
        {
          "label": "Local Only",
          "description": "Execute without GitHub integration"
        }
      ]
    }
  ]
}

---

5. Create GitHub Issues (If Selected)

5.1 Create Labels

gh label create "plan" --color "7057ff" --description "Plan-based task" 2>/dev/null || true
gh label create "in-progress" --color "FBCA04" --description "Work in progress" 2>/dev/null || true

5.2 Create Epic Issue

gh issue create \
  --title "Epic: {Plan Title}" \
  --label "plan" \
  --body-file {plan-file-path}

• Save Epic issue number

5.3 Create Phase Issues

For each Phase:

gh issue create \
  --title "Phase {N}: {Phase Title}" \
  --label "plan" \
  --body "## Tasks\n\n{checklist from tasks}"

• Save all Phase issue numbers

5.4 Update Plan File with Issue Numbers

Update the plan file to include issue references for future runs.

---

6. Identify Design Documents

Extract design document paths from plan file:

Search patterns:

• 검증 문서: followed by file paths
• Reference: followed by file paths
• Explicit docs/ paths

Build Task → Document Mapping:

Task Mapping:
- Phase 1 Tasks → docs/frontend/00-overview.md, docs/frontend/02-design-system.md
- Phase 2 Tasks → docs/frontend/03-pages/auth.md

---

7. Execute Task Cycle

For each Phase, execute tasks in order:

7.1 Update Issue Status to "In Progress"

# Add label
gh issue edit {phase-issue-number} --add-label "in-progress"

If GitHub Project exists:

gh project item-edit --project-id {project-id} --id {item_id} \
  --field-id {status_field} --single-select-option-id {in_progress_id}

7.2 Read Design Context

Use Task tool to gather context:

subagent_type: Explore
prompt: |
  Gather implementation context for this task.

  ## Task
  {task description}

  ## Design Documents to Read
  {mapped design docs}

  ## Extract
  - Specifications and requirements
  - Validation rules
  - UI/UX patterns
  - API contracts

7.3 Execute Tasks (Parallel for Independent)

Independent tasks execute in parallel using multiple Task tool calls:

subagent_type: general-purpose
run_in_background: true
prompt: |
  Implement the following task.

  ## Task
  {task description}

  ## Design Specifications
  {extracted from design docs}

  ## Guidelines
  - Follow existing code patterns
  - Match design specifications exactly
  - Implement validation rules
  - Run lint and typecheck after changes

IMPORTANT: Multiple independent tasks MUST be executed in parallel with multiple Task calls in a single message.

7.4 Design Verification (REQUIRED)

After implementation, verify against design documents:

subagent_type: general-purpose
prompt: |
  Verify implementation against design specifications.

  ## Design Document
  {design doc content}

  ## Verification Checklist
  - [ ] Design specs match (wireframe, layout)
  - [ ] Design tokens used correctly (colors, typography)
  - [ ] Validation rules implemented
  - [ ] Responsive design working
  - [ ] Accessibility (keyboard nav, ARIA labels)

  ## Actions
  1. Compare implementation with design specs
  2. List discrepancies if any
  3. Fix any mismatches
  4. Report compliance status (pass/partial/fail)

7.5 Run Tests and Lint

# If package.json exists
npm run lint
npm run typecheck
npm test

# Or project-appropriate commands

Report and fix any errors.

7.6 Commit with Issue Reference

git add {changed-files}
git commit -m "$(cat <<'EOF'
feat({scope}): {task description}

{detailed changes}

Closes #{issue-number}
EOF
)"

7.7 Update Issue Checklist

Update the Phase issue body to mark completed tasks:

# Get current body
BODY=$(gh issue view {phase-issue-number} --json body -q '.body')

# Replace - [ ] with - [x] for completed task
# Update issue
gh issue edit {phase-issue-number} --body "{updated body}"

Add completion comment:

gh issue comment {phase-issue-number} --body "## Task Completed: {task name}

Commit: {hash}
Changes: {summary}
Verification: Passed"

---

8. Phase Completion

When all tasks in a phase are complete:

8.1 Remove In-Progress Label

gh issue edit {phase-issue-number} --remove-label "in-progress"

8.2 Close Phase Issue

gh issue close {phase-issue-number} --comment "## Phase Complete

All tasks completed successfully.
Commits: {list}"

8.3 Update Project Status (if exists)

gh project item-edit --project-id {project-id} --id {item_id} \
  --field-id {status_field} --single-select-option-id {done_id}

---

9. Completion Report

Output final summary:

Plan Workflow Complete

File: {plan-file-path}
Repository: {owner}/{repo}

## Summary
- Phases Completed: {N}/{total}
- Tasks Completed: {M}/{total}
- Design Verification: {pass_rate}%
- Failed Tasks: {count}

## Per-Phase Results
- Phase 1: {name} ✓
  - Tasks: {completed}/{total}
  - Issue: #{number} (closed)
- Phase 2: {name} ✓
  ...

## Commits
- {short_hash}: {message}
- {short_hash}: {message}
...

## Next Steps
{remaining phases if any, or "All phases complete!"}

---

10. Update Plan File (Optional)

Mark completed items in plan file:

• - [ ] → - [x]

This allows resuming from where you left off in future sessions.

---

Offline Mode (No GitHub)

If user selects "Local Only" in Step 4:

1. Skip all gh commands
2. Track progress in plan file only (- [ ] → - [x])
3. Use commit messages without issue references
4. Still perform design verification

---

Error Handling

Error	Solution
gh auth failed	Run gh auth login
Project scope missing	Run gh auth refresh -s project,read:project
Issue not found	Create new issue or continue without
Design doc not found	Ask user to specify path
Test/lint failure	Report errors, ask to fix or skip
Task execution failed	Report, ask to retry or skip

---

Task Tool Usage Summary

Timing	subagent_type	Purpose
Context gathering	Explore	Read design docs, understand patterns
Task execution	general-purpose	Implementation (parallel, run_in_background)
Verification	general-purpose	Design compliance check
Code review	general-purpose	Quality verification

---

IMPORTANT

• Steps 4, 7.4, 7.6, 7.7 MUST be executed - These are critical for tracking
• Design verification is REQUIRED before committing
• Independent tasks MUST execute in parallel for efficiency
• Plan file updates enable resumable workflows
• Always close issues after phase completion