# Backend Phase Workflow Skill

Manage the phased backend development workflow for Mantimon TCG.

## Usage

```
/backend-phase              # Show current phase status and next task
/backend-phase status       # Same as above
/backend-phase next         # Show detailed info about next incomplete task
/backend-phase start <id>   # Mark task as in-progress
/backend-phase done <id>    # Mark task as complete (with tests)
/backend-phase plan         # Create plan for next NOT_STARTED phase
```

## Files

- **Master Plan:** `backend/PROJECT_PLAN_MASTER.json`
- **Phase Plans:** `backend/project_plans/PHASE_N_*.json`

## Workflow

### Starting a New Phase

1. Run `/backend-phase plan` to create the detailed plan for the next NOT_STARTED phase
2. Review and adjust the generated plan
3. Run `/backend-phase next` to see the first task

### Working on Tasks

1. Run `/backend-phase next` to see task details
2. Run `/backend-phase start <task-id>` to mark it in-progress
3. Implement the task following the details in the plan
4. Write tests with docstrings explaining "what" and "why"
5. Run `/backend-phase done <task-id>` when complete with passing tests

### Completing a Phase

When all tasks are complete:
1. Update master plan status to "COMPLETE"
2. Add completedDate
3. Increment completedPhases count

## Instructions

When `/backend-phase` or `/backend-phase status` is invoked:

1. **Read Master Plan**
   ```
   backend/PROJECT_PLAN_MASTER.json
   ```

2. **Find Current Phase**
   - Look for first phase with `status: "in_progress"` or `status: "IN_PROGRESS"`
   - If none, look for first phase with `status: "NOT_STARTED"`

3. **Read Phase Plan**
   ```
   backend/project_plans/PHASE_N_*.json
   ```

4. **Display Status**
   ```
   ## Phase N: [Phase Name]

   Status: IN_PROGRESS
   Progress: X/Y tasks complete

   ### Completed Tasks
   - [x] TASK-001: Task name
   - [x] TASK-002: Task name

   ### Next Task
   **TASK-003: Task name**
   Category: services | Priority: 3
   Dependencies: [TASK-001, TASK-002]

   [Brief description from plan]

   Run `/backend-phase next` for full details.
   ```

---

When `/backend-phase next` is invoked:

1. Find the first task where `completed: false` and all dependencies are met
2. Display full task details:
   ```
   ## TASK-003: Task Name

   **Category:** services
   **Priority:** 3
   **Estimated Hours:** 2
   **Dependencies:** TASK-001, TASK-002 (all complete)

   ### Description
   [Full description from plan]

   ### Implementation Details
   - Detail 1
   - Detail 2
   - Detail 3

   ### Files to Create/Modify
   - `app/services/foo.py` (create)
   - `app/main.py` (modify)

   ### Notes
   [Any notes from the plan]

   ---
   Run `/backend-phase start TASK-003` to begin work.
   ```

---

When `/backend-phase start <task-id>` is invoked:

1. Verify task exists and dependencies are met
2. Log that work is starting (no file modification needed)
3. Display the task details for reference
4. Create Claude Code tasks using TaskCreate if task has multiple sub-items

---

When `/backend-phase done <task-id>` is invoked:

1. Verify tests exist and pass for the task
2. Update the phase plan JSON:
   - Set `completed: true`
   - Set `tested: true`
3. Update `completedTasks` count in meta
4. Check if phase is complete (all tasks done)
5. If phase complete, prompt to update master plan

---

When `/backend-phase plan` is invoked:

1. Find next NOT_STARTED phase in master plan
2. Read existing phase plans for format reference
3. Generate detailed plan based on:
   - Phase description and deliverables from master plan
   - Architecture patterns from CLAUDE.md
   - Existing code patterns in the codebase
4. Write to `backend/project_plans/PHASE_N_*.json`
5. Update master plan status to "in_progress"

## Task Schema

```json
{
  "id": "GS-001",
  "name": "Short task name",
  "description": "What this task accomplishes",
  "category": "services|schemas|infrastructure|auth|api|tests",
  "priority": 1,
  "completed": false,
  "tested": false,
  "dependencies": ["WS-001"],
  "files": [
    {"path": "app/services/game_service.py", "status": "create|modify"}
  ],
  "details": [
    "Specific implementation step 1",
    "Specific implementation step 2"
  ],
  "estimatedHours": 3,
  "notes": "Optional implementation notes"
}
```

## Rules

1. **Dependencies First** - Never start a task with incomplete dependencies
2. **Tests Required** - Every task must have tests before marking complete
3. **Docstrings Required** - Test docstrings explain "what" and "why"
4. **Commit Approval** - Never commit without user approval
5. **One Task at a Time** - Focus on completing current task before starting next
6. **Update Plans** - Keep plan files in sync with actual progress

## Memory Integration

After completing a task or phase, consider storing learnings:
```bash
python ~/.claude/skills/memorygraph/client.py store \
  --type solution \
  --title "Completed PHASE_4 GS-003" \
  --content "Implemented forced action handling..." \
  --tags "mantimon,backend,game-service" \
  --importance 0.6
```
