/start-phase plan /path/to/task-list.md

/start-phase plan ./job-queue/prototype-build/tasks.md

Task list file: /path/to/folder/tasks.md

Derived paths:
• input_folder: /path/to/folder
• planning_folder: /path/to/folder/planning

These paths NEVER change during this phase.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎯 Mode 1: Strategic Planning
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Task list: {task_list_file}
Input folder: {input_folder}
Planning folder: {planning_folder}

Beginning strategic review...

# Initialize invocation
invocation_output=$(python3 ~/.claude/skills/start-phase/scripts/cache_wrapper.py init \
    --agent-name "start-phase-plan" \
    --purpose "Strategic planning for $(basename "$input_folder")" 2>/dev/null)

# Extract invocation_id
INVOCATION_ID=$(echo "$invocation_output" | jq -r '.invocation_id')

✅ Agent Invocation ID: $INVOCATION_ID

Cache tracking active for all file reads.

# Read with cache tracking
read_output=$(python3 ~/.claude/skills/start-phase/scripts/cache_wrapper.py read \
    --invocation-id $INVOCATION_ID \
    --file-path "$task_list_file" 2>/dev/null)

# Display cache status
cache_status=$(echo "$read_output" | jq -r '.cache_status')
tokens=$(echo "$read_output" | jq -r '.estimated_tokens')
echo "📄 Task list: $cache_status ($tokens tokens)"

# Read actual content (use Read tool for task list)
Read {task_list_file}

# Check for Documentation Hub
if [ -d "$input_folder/docs" ]; then
    echo ""
    echo "📚 Reading Documentation Hub..."
    for doc_file in "$input_folder/docs"/*.md; do
        if [ -f "$doc_file" ]; then
            read_output=$(python3 ~/.claude/skills/start-phase/scripts/cache_wrapper.py read \
                --invocation-id $INVOCATION_ID \
                --file-path "$doc_file")

            cache_status=$(echo "$read_output" | jq -r '.cache_status')
            echo "  $(basename "$doc_file"): $cache_status"

            # Read actual content (use Read tool)
            Read "$doc_file"
        fi
    done
fi

# Read Memory Bank files with cache tracking
echo ""
echo "🧠 Reading Memory Bank..."
for mb_file in memory-bank/systemPatterns.md memory-bank/activeContext.md; do
    if [ -f "$mb_file" ]; then
        read_output=$(python3 ~/.claude/skills/start-phase/scripts/cache_wrapper.py read \
            --invocation-id $INVOCATION_ID \
            --file-path "$mb_file")

        cache_status=$(echo "$read_output" | jq -r '.cache_status')
        tokens=$(echo "$read_output" | jq -r '.estimated_tokens')
        echo "  $(basename "$mb_file"): $cache_status ($tokens tokens)"

        # Read actual content (use Read tool)
        Read "$mb_file"
    fi
done

# Get invocation stats
stats_output=$(python3 ~/.claude/skills/start-phase/scripts/cache_wrapper.py stats \
    --invocation-id $INVOCATION_ID 2>/dev/null)

echo ""
echo "📊 Cache Statistics:"
echo "  Files read: $(echo "$stats_output" | jq -r '.files_read')"
echo "  Cache hits: $(echo "$stats_output" | jq -r '.cache_hits')"
echo "  Cache misses: $(echo "$stats_output" | jq -r '.cache_misses')"
echo "  Estimated tokens: $(echo "$stats_output" | jq -r '.estimated_tokens')"
echo ""

📋 Current Task List

Total tasks: 8

1. Setup authentication API
2. Create user database schema
3. Build login UI
4. Implement JWT tokens
5. Add password hashing
6. Create auth middleware
7. Write integration tests
8. Deploy to staging

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Beginning strategic analysis...

⚠️ Complexity Analysis

This task list aims for production-ready auth in one phase.

Concerns:
• Task 8 "Deploy to staging" suggests production scope
• 8 tasks is manageable BUT mixing prototype + production
• No clear MVP vs polish separation

Recommendation: Focus on working prototype first
• Phase 1: Basic auth (login/logout) - MVP
• Phase 2: Production hardening (security, deploy)

🔀 Parallelism Opportunities

Independent tasks (can run in parallel):
• Task 1: Setup auth API (backend)
• Task 3: Build login UI (frontend)
• Task 7: Write tests (QA)

Dependencies:
• Task 4 depends on Task 1 (JWT needs API)
• Task 6 depends on Task 1 (middleware needs API)
• Task 7 depends on Tasks 1, 3, 4 (integration tests)

Proposed waves:
Wave 1 (parallel): Tasks 1, 3
Wave 2 (parallel): Tasks 2, 4, 5
Wave 3 (sequential): Task 6
Wave 4 (sequential): Task 7

🤖 Sub-Agent Delegation Analysis

Feature characteristics:
• Total files impacted: 6 (3 new, 3 modified)
• Skill sets required: Backend API, Frontend UI, Testing
• Components: API endpoint, UI form, database schema, tests

Sub-agent opportunity assessment:
✅ RECOMMEND sub-agent delegation

Rationale:
• Multiple specializations: Backend (API + DB) + Frontend (UI) + QA (tests)
• Parallel execution benefit: ~30-40% time savings
• Agent expertise: Each agent has specialized knowledge base
• Progress tracking: Granular task updates per agent

Proposed delegation:
• nextjs-backend-developer: Tasks 1, 2, 4, 5, 6 (API, DB, JWT, middleware)
• ui-developer: Task 3 (Login form UI)
• qa-engineer: Task 7 (Integration tests)

Parallel waves with agents:
Wave 1 (parallel):
  • Task 1: Setup auth API (nextjs-backend-developer)
  • Task 3: Build login UI (ui-developer)

Wave 2 (parallel):
  • Tasks 2, 4, 5: DB + JWT + hashing (nextjs-backend-developer)

Wave 3 (sequential):
  • Task 6: Middleware (nextjs-backend-developer)
  • Task 7: Tests (qa-engineer)

Expected time savings: ~2h sequential → ~1.5h parallel (25% faster)

❌ Skip sub-agent delegation if:

• Single file change (documentation update, config tweak)
• <3 tasks total
• Single skill set (only backend OR only frontend, not both)
• Bug fix or hotfix (speed over tracking)
• Proof of concept / throwaway code

Use manual execution or lightweight mode instead.

🔨 Incremental Build Strategy

Current order: Setup → Build → Test → Deploy
Problem: No integration until Task 7

Proposed order:
1. Minimal API endpoint (1h) ✅ Working code
2. Minimal UI form (1h) ✅ Integration point
3. Connect UI → API (30m) ✅ End-to-end working
4. Add JWT (1h) ✅ Still working
5. Add DB schema (1h) ✅ Still working
6. Add password hashing (30m) ✅ Still working
7. Add middleware (45m) ✅ Still working
8. Integration tests (1h) ✅ Final verification

Result: Working code after EVERY task, not just at end

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📝 Proposed Refined Plan
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Changes made:
✅ Reduced scope to MVP (removed "Deploy to staging")
✅ Reorganized for early integration
✅ Identified 2 parallel waves
✅ Ensured working code after each task

Revised Task List:

Wave 1 (Parallel - Run simultaneously):
1. Create minimal auth API endpoint (POST /login)
   Agent: nextjs-backend-developer
   Duration: ~1h
   Output: Working API endpoint

2. Create minimal login UI form
   Agent: ui-developer
   Duration: ~1h
   Output: Working form component

Wave 2 (Integration):
3. Connect UI to API (end-to-end test)
   Agent: nextjs-backend-developer
   Duration: ~30m
   Output: Login flow works end-to-end

Wave 3 (Parallel - Add features):
4. Add JWT token generation
   Agent: nextjs-backend-developer
   Duration: ~1h
   Depends on: Task 1

5. Create user database schema
   Agent: nextjs-backend-developer
   Duration: ~1h
   Depends on: Task 1

6. Add password hashing (bcrypt)
   Agent: nextjs-backend-developer
   Duration: ~30m
   Depends on: Task 5

Wave 4 (Sequential - Finalize):
7. Add auth middleware (protected routes)
   Agent: nextjs-backend-developer
   Duration: ~45m
   Depends on: Task 4

8. Write integration tests
   Agent: qa-engineer
   Duration: ~1h
   Depends on: All previous tasks

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Summary:
• Total tasks: 8 (same count, better organized)
• Parallel waves: 2 (Wave 1: 2 tasks, Wave 3: 3 tasks)
• Working code after: Task 3 (end-to-end MVP)
• Estimated time: ~6-7h (vs 8h sequential)
• Time saved: ~1-2h through parallelism

Deferred to Phase 2:
• Deploy to staging
• Production security hardening
• Rate limiting
• Session management

🔑 Key Improvements

1. Scope Reduction ✅
   - Removed: Deploy to staging
   - Focus: Working prototype only
   - Reason: One phase, one clear goal

2. Early Integration ✅
   - Before: Integration at Task 7
   - After: Integration at Task 3
   - Benefit: Catch issues early, not late

3. Parallelism ✅
   - Wave 1: Backend + Frontend simultaneously
   - Wave 3: JWT + DB + Hashing simultaneously
   - Benefit: 1-2h time savings

4. Clear Dependencies ✅
   - Every task lists dependencies
   - Waves prevent conflicts
   - Integration points explicit

5. Incremental Value ✅
   - Task 3: MVP works end-to-end
   - Every task after: Still works
   - Never broken for long periods

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✋ Human Approval Required
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

This refined plan is ready for your review.

Options:
1. ✅ Approve - Proceed to Mode 2 (Execute)
2. 🔄 Revise - Suggest changes to the plan
3. ❌ Reject - Start over with different approach
4. 💬 Question - Ask about specific tasks/decisions

Which option? (1/2/3/4)

✅ Plan Approved!

Refined task list is ready for execution.

Next step:
/start-phase execute {task_list_file}

This will:
• Finalize the approved plan (write to task list file)
• Create planning directory structure
• Generate detailed planning documents
• Begin execution with quality gates

Ready to proceed? (y/n)

Great! Please run:

/start-phase execute {task_list_file}

[Mode 1 complete]

🔄 Plan Revision

What would you like to change?

Common revisions:
• Adjust task order
• Change parallel grouping
• Add/remove tasks
• Modify task descriptions
• Adjust scope (more/less ambitious)

Please describe your requested changes:

❌ Plan Rejected

Would you like to:
1. Start over with different objectives
2. Use original task list as-is (not recommended)
3. Cancel phase planning

Which option? (1/2/3)

💬 Questions Welcome

Ask about:
• Why tasks are ordered this way
• How parallelism works
• Why certain tasks are deferred
• Dependency reasoning
• Time estimates
• Agent assignments

Your question:

# Complete invocation
complete_output=$(python3 ~/.claude/skills/start-phase/scripts/cache_wrapper.py complete \
    --invocation-id $INVOCATION_ID 2>/dev/null)

duration=$(echo "$complete_output" | jq -r '.duration_seconds')
echo ""
echo "✅ Planning session complete (${duration}s)"
echo ""
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "📊 Final Cache Statistics"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "  Files read: $(echo "$complete_output" | jq -r '.total_files_read')"
echo "  Cache hits: $(echo "$complete_output" | jq -r '.cache_hits')"
echo "  Cache misses: $(echo "$complete_output" | jq -r '.cache_misses')"
echo "  Estimated tokens: $(echo "$complete_output" | jq -r '.estimated_tokens_used')"
echo ""

Planning context saved:
• task_list_file: {path}
• input_folder: {derived from task list}
• planning_folder: {input_folder}/planning
• phase_name: {extracted or inferred}
• approved_plan: {refined task list}

Ready for Mode 2 execution.

Input folder = directory containing task list file
Planning folder = {input_folder}/planning

Example:
Task list: ./job-queue/prototype/tasks.md
→ input_folder: ./job-queue/prototype
→ planning_folder: ./job-queue/prototype/planning

All Mode 2 artifacts go in planning_folder!

# User starts Mode 1
/start-phase plan ./job-queue/auth-prototype/tasks.md

# System extracts paths
Input folder: ./job-queue/auth-prototype
Planning folder: ./job-queue/auth-prototype/planning

# System reads task list
[Reads 8 tasks from file]

# System analyzes
⚠️ Complexity too high for one phase
🔀 Found parallelism opportunities
🔨 Reorganized for incremental builds

# System proposes refined plan
[Shows revised 8 tasks with waves]

# System asks for approval
Options: Approve / Revise / Reject / Question

# User approves
User: 1

# System confirms
✅ Plan approved!
Next: /start-phase execute ./job-queue/auth-prototype/tasks.md

# [Mode 1 complete]