---
description: Plan and track work using Forgejo milestones and issues. Creates milestones for phases, issues for tasks, and labels for status. Use for any multi-step feature, epic, or sprint planning.
---

# Tawa PM — Project Planning with Forgejo

Plan and execute work using Forgejo as the source of truth. No local markdown files to overwrite — everything lives in the repo's milestones and issues.

## Core Principles

1. **Forgejo is the system of record** — milestones, issues, comments. Never local markdown.
2. **Re-read before deciding** — always fetch milestone status before major decisions (prevents stale context).
3. **Log as you go** — after every 2 significant actions, post a progress comment on the active task issue.
4. **Never repeat failures** — if an approach fails, log it as an issue comment before trying a different approach.
5. **Ready means ready** — a task is only `ready` when ALL its dependencies are closed AND its phase is active.

## How It Works

| Concept | Forgejo Backing | Example |
|---------|----------------|---------|
| Epic/Project | Milestone | `PolicyEco Versioning v1` |
| Phase | Issue with `phase` label | `Phase 1: SDK Consolidation` |
| Task | Issue linked to milestone | `Add tawa/testing export path` |
| Status | Labels | `status:backlog`, `status:in-progress`, `status:review` |
| Decisions | Issue comments | Architecture decision logged as comment |
| Progress | Milestone % complete | 4/12 issues closed = 33% |
| Discovery | New issue with `discovered-from: #N` | Found during work on #16 |

## Workflow

### 1. PLAN — Break work into a milestone + issues

When the user says `/tawa-pm plan <description>`:

1. **Identify the target repo** — ask if not obvious from the working directory
2. **Check existing milestones** — `mcp__jci-mcp__git_milestone_list` to avoid duplicates
3. **Create a milestone** — `mcp__jci-mcp__git_milestone_create` with title, description, optional due date
4. **Break into phases** — create one issue per phase with the `phase` label, assigned to the milestone
5. **Break phases into tasks** — create issues for each task, assigned to the milestone, labeled by type
6. **Present the plan** — show the milestone URL and issue list
7. **CHECKPOINT** — WAIT for user confirmation before creating any code. Show:
   - Total phases and tasks created
   - Dependency graph summary
   - Estimated scope (small/medium/large per phase)
   - Ask: "Ready to start Phase 1, or want to adjust?"

Phase issues should use this body format:
```markdown
## Objective
What this phase achieves.

## Tasks
- [ ] Task 1 (#N)
- [ ] Task 2 (#N)

## Depends On
- Phase X (#N)

## Acceptance Criteria
- [ ] Criteria 1
- [ ] Criteria 2

## Checkpoint
Before moving to the next phase, confirm:
- [ ] All task issues closed
- [ ] Tests passing
- [ ] No regressions in previous phases
```

Task issues should use this body format:
```markdown
## What
Brief description of the task.

## Why
How this connects to the phase/milestone goal.

## Acceptance Criteria
- [ ] Criteria 1

## Files Likely Affected
- `src/path/to/file.ts`

## Depends On
- #N (must be closed before this is ready)
```

### 2. STATUS — Check progress on a milestone

When the user says `/tawa-pm status [repo]`:

1. **List open milestones** — `mcp__jci-mcp__git_milestone_list`
2. **For each milestone** — `mcp__jci-mcp__git_milestone_issues` to get open/closed counts
3. **Resolve readiness** — for each open task, check if dependencies are met
4. **Show progress** — milestone name, % complete, ready tasks, blockers, next actions

Output format:
```
## PolicyEco Versioning v1 (4/12 tasks, 33%)

Phase 1: SDK Consolidation — IN PROGRESS (2/4 tasks)
  ✓ #14 Create src/testing/ directory
  ✓ #15 Add exports map to package.json
  → #16 Migrate three-tier routing [in-progress]
  ○ #17 Update scaffold imports [blocked by #16]

Phase 2: Binary Compilation — PENDING (0/3 tasks)
  ◆ #18 Research bun compile [ready — no blockers]
  ○ #19 Set up build pipeline [blocked by #18]
  ○ #20 Test cross-compilation [blocked by #19]

Ready now: #18 (Phase 2 can start in parallel)
Blocked: #17 (waiting on #16), #19 (waiting on #18)
```

### 3. NEXT — Pick up the next ready task

When the user says `/tawa-pm next [repo]`:

1. **Re-read milestone status** — always fetch fresh state first
2. **Resolve the dependency graph** — find all open tasks, check which have ALL dependencies closed
3. **Pick the highest-priority ready task** — priority order:
   - Tasks in the earliest incomplete phase
   - Tasks with no dependencies (can start immediately)
   - Tasks that unblock the most other tasks
4. **Set it to in-progress** — remove `status:backlog`, add `status:in-progress`
5. **Present the task** — show the issue body, acceptance criteria, and what this unblocks
6. **Optionally start work** — if user confirms, begin implementation

A task is **ready** when:
- All issues listed in its "Depends On" section are closed
- Its parent phase is the current or an earlier phase
- It is not already `status:in-progress` by someone else

### 4. DONE — Complete a task

When the user says `/tawa-pm done [#issue]`:

1. **Close the issue** — `mcp__jci-mcp__git_issue_update` with state: closed
2. **Remove status labels** — clear `status:in-progress`
3. **Check newly unblocked tasks** — find tasks that depended on this one, mark them ready
4. **Update phase progress** — check if all tasks in the phase are done
5. **If phase complete** — close the phase issue, run phase checkpoint:
   - Post a comment on the phase issue summarizing what was done
   - Ask: "Phase N complete. Move to Phase N+1?" (CHECKPOINT)
6. **Show updated status** — milestone progress with newly ready tasks highlighted

### 5. DECISION — Log an architecture decision

When the user says `/tawa-pm decision <description>`:

1. **Find the active milestone**
2. **Create a comment on the milestone's parent issue** (or a dedicated decisions issue)
3. **Format as ADR-lite**:
```markdown
### Decision: [Title]
**Date:** 2026-03-15
**Status:** Accepted

**Context:** Why this decision was needed.
**Decision:** What we decided.
**Rationale:** Why this over alternatives.
**Consequences:** What changes as a result.
```

### 6. DISCOVER — Log work found during implementation

When new work is discovered while implementing a task, don't just silently add it — track the lineage:

1. **Create a new issue** with `discovered-from: #N` in the body (where N is the task you were working on)
2. **Assign to the current milestone** (or a future one if out of scope)
3. **Add a comment on the source issue** — "Discovered #M while working on this"
4. **Label appropriately** — `feature`, `bug`, `debt`, etc.

This preserves the "why" — future you (or Chaac) can trace how work emerged.

### 7. EXPLORE — Ephemeral investigation (wisp)

When the user says `/tawa-pm explore <question>`:

For time-boxed investigation that may or may not produce a task:

1. **Create a comment on the active task** — "Exploring: <question>"
2. **Do the investigation** (read code, search, prototype)
3. **Post findings as a comment** — what you learned, whether it spawns new work
4. **If new work found** — use DISCOVER flow above
5. **If dead end** — post "Explored <question> — no action needed. Reason: ..."

Explorations are ephemeral — they live as comments, not issues, unless they produce actionable work.

## Progress Logging Protocol

During implementation, keep the issue thread as a living log:

- **After every 2 significant actions** (file edits, test runs, discoveries): post a brief progress comment on the active issue
- **On errors or wrong turns**: post what happened and what you'll try instead — this prevents repeating failures across sessions
- **Before major decisions**: re-read the milestone and phase issues to refresh context

Comment format:
```markdown
**Progress:** Completed X, working on Y.
**Files touched:** `src/foo.ts`, `src/bar.ts`
**Next:** Z
```

Or for errors:
```markdown
**Attempted:** X approach
**Result:** Failed because Y
**Next:** Trying Z instead
```

## Labels Used

Create these labels if they don't exist:

| Label | Color | Purpose |
|-------|-------|---------|
| `phase` | `#6366f1` | Marks an issue as a phase (parent of tasks) |
| `feature` | `#22c55e` | New functionality |
| `bug` | `#ef4444` | Something broken |
| `infra` | `#8b5cf6` | DevOps, config, deployment |
| `debt` | `#f59e0b` | Technical debt cleanup |
| `status:backlog` | `#64748b` | Not started |
| `status:in-progress` | `#2563eb` | Currently working |
| `status:review` | `#d97706` | In review |
| `status:blocked` | `#dc2626` | Blocked by dependency |

## Cross-Repo Planning

For work spanning multiple repos (like PolicyEco which touches tawa-cli, iec-koko, iec-builder, iec-test):

1. **Create milestone in the primary repo** (where most code changes happen)
2. **Create issues in the repo where the code lives** — reference the primary milestone in the issue body
3. **Use cross-references** — `insureco/iec-koko#5` syntax to link across repos
4. **Track in primary milestone description** — list all cross-repo issues

## Anti-Patterns

| Don't | Do Instead | Why |
|-------|-----------|-----|
| Start coding without an issue | `/tawa-pm next` or create issue first | No traceability, work gets lost |
| Skip the phase checkpoint | Confirm before moving phases | Regressions compound across phases |
| Create tasks without "Depends On" | Always declare dependencies | `/next` can't resolve readiness without them |
| Silently fix a discovered bug | Use DISCOVER flow | Lineage is lost, scope creep is invisible |
| Retry same failed approach | Log the failure, try different approach | Wastes time, no learning captured |
| Plan in local markdown files | Everything in Forgejo issues | Local files get overwritten, no collaboration |
| Put 20+ tasks in one phase | Max 7 tasks per phase | Phases should be completable in 1-2 sessions |
| Create issues without acceptance criteria | Every issue needs "done" definition | No way to verify completion |

## Integration with Other Skills

| After planning | Use |
|---------------|-----|
| Starting a task | `/tdd` for test-driven development |
| Code written | `/code-review` for review |
| Build fails | `/build-fix` to resolve |
| Ready to deploy | `tawa deploy --prod` |
| Task complete | `/tawa-pm done #N` |

## Example Usage

```
User: /tawa-pm plan PolicyEco versioning for tawa-cli

Claude: Creates milestone "PolicyEco Versioning v1" in tawa-cli repo,
        creates phase issues and task issues, presents the full plan.
        CHECKPOINT: "5 phases, 18 tasks created. Ready to start Phase 1?"

User: /tawa-pm next

Claude: Resolves dependency graph, finds highest-priority ready task,
        shows acceptance criteria and what completing it unblocks.

User: /tawa-pm status

Claude: Shows all milestones with progress, ready tasks, and blockers.

User: /tawa-pm done #16

Claude: Closes issue, finds newly unblocked tasks, checks phase completion.
        If phase done: CHECKPOINT before moving to next phase.

User: /tawa-pm explore "Can bun compile handle dynamic imports?"

Claude: Investigates, posts findings as comment on active task.
        If actionable: creates new issue with discovered-from link.

User: /tawa-pm decision "Use bun compile over pkg for binary"

Claude: Posts ADR-lite comment on the milestone's phase issue.
```