issues

name

issues

description

Manages the persistent file-based work tracker at overlay/issues/. Use when the user says: "what's next", "what should I work on", "show backlog", "track this", "create an issue", "add to backlog", "mark done", "close issue", "show tasks", "triage issues", "update status", "show roadmap", "priorities", "what's in progress", "move to done", or discusses work item tracking. Not for debugging problems ("I have an issue with X") or one-off planning.

Issue Management

Manage the project's persistent work tracker in overlay/issues/.

Issue & Plan Storage

Issues and plans are tracked in ./overlay/issues/ with numbered phases:

./overlay/issues/
├── 10-phase-name/           # Single issue = flat folder
│   └── plan.md
├── 20-another-phase/
│   ├── plan.md
│   └── design.md          # Optional
├── 30-multi-issue-phase/    # Multiple parallel issues = nested
│   ├── feature-a/
│   │   ├── plan.md
│   │   └── design.md
│   └── feature-b/
│       └── plan.md
└── done/                    # Completed issues moved here

Conventions:

• Single issue phase → NN-phase-name/ (flat)
• Multi-issue phase → NN-phase/issue-name/ (nested, all parallel)
• Gaps in numbers (10, 20...) = room to insert phases later
• Each issue has plan.md + optional design.md
• Completed issues → move to done/

Workflow:

1. Work through phases in order (10 → 20 → 30...)
2. Within a phase folder, pick any issue - they're independent
3. Read issue's plan.md for scope

Commands

List Active Issues

ls -1d overlay/issues/*/ 2>/dev/null | grep -v done/

Show What's Next

ls -1d overlay/issues/*/ 2>/dev/null | grep -v done/ | head -1

Create Issue

1. Check existing phases: ls overlay/issues/
2. Pick phase number (use gaps like 10, 20, 30 for flexibility)
3. Create folder:
   • Single issue: overlay/issues/NN-issue-name/
   • Multi-issue phase: overlay/issues/NN-phase/issue-name/
4. Add plan.md with scope and implementation details
5. Optionally add design.md for design notes

Complete Issue

Move to done when fully implemented:

mkdir -p overlay/issues/done
mv overlay/issues/NN-issue-name overlay/issues/done/

Show Progress

echo "Active:" && ls -1d overlay/issues/*/ 2>/dev/null | grep -v done/ | wc -l
echo "Done:" && ls -1d overlay/issues/done/*/ 2>/dev/null | wc -l

Triage/Prioritize

1. Review all phases: ls -la overlay/issues/
2. Check recent work to identify completed issues:

   git log --oneline -20
   git diff main~10..main --stat
   

3. Move completed issues to done
4. Renumber folders to reorder priority
5. Move items between phases as needed
6. Update any plan.md files with new scope

$ARGUMENTS