issues
Manages the persistent file-based work tracker at thoughts/shared/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.
When & Why to Use This Skill
This Claude skill provides a robust, file-based system for managing project issues, backlogs, and roadmaps. It enables agents to persistently track work items, prioritize tasks through a structured phase-based directory, and maintain detailed implementation plans, ensuring seamless project continuity and organized task execution within a development environment.
Use Cases
- Backlog Triage: Automatically organizing and prioritizing user requests or technical debt into a structured backlog using numbered phases for clear execution order.
- Workflow Automation: Helping the agent identify 'what's next' by scanning the prioritized directory to maintain development momentum without manual intervention.
- Progress Tracking: Monitoring the status of active tasks and moving completed items to a 'done' repository to maintain a clean and up-to-date workspace.
- Structured Planning: Creating and maintaining 'plan.md' and 'design.md' files for each issue to ensure all technical tasks have documented scope and implementation details.
| name | issues |
|---|---|
| description | | |
| Use when the user says | "what's next", "what should I work on", "show backlog", |
Issue Management
Manage the project's persistent work tracker in thoughts/shared/issues/.
Issue & Plan Storage
Issues and plans are tracked in thoughts/shared/issues/ with numbered phases:
thoughts/shared/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+ optionaldesign.md - Completed issues → move to
done/
Workflow:
- Work through phases in order (10 → 20 → 30...)
- Within a phase folder, pick any issue - they're independent
- Read issue's
plan.mdfor scope
Commands
List Active Issues
ls -1d thoughts/shared/issues/*/ 2>/dev/null | grep -v done/
Show What's Next
ls -1d thoughts/shared/issues/*/ 2>/dev/null | grep -v done/ | head -1
Create Issue
- Check existing phases:
ls thoughts/shared/issues/ - Pick phase number (use gaps like 10, 20, 30 for flexibility)
- Create folder:
- Single issue:
thoughts/shared/issues/NN-issue-name/ - Multi-issue phase:
thoughts/shared/issues/NN-phase/issue-name/
- Single issue:
- Add
plan.mdwith scope and implementation details - Optionally add
design.mdfor design notes
Complete Issue
Move to done when fully implemented:
mkdir -p thoughts/shared/issues/done
mv thoughts/shared/issues/NN-issue-name thoughts/shared/issues/done/
Show Progress
echo "Active:" && ls -1d thoughts/shared/issues/*/ 2>/dev/null | grep -v done/ | wc -l
echo "Done:" && ls -1d thoughts/shared/issues/done/*/ 2>/dev/null | wc -l
Triage/Prioritize
- Review all phases:
ls -la thoughts/shared/issues/ - Check recent work to identify completed issues:
git log --oneline -20 git diff main~10..main --stat - Move completed issues to done
- Renumber folders to reorder priority
- Move items between phases as needed
- Update any
plan.mdfiles with new scope
$ARGUMENTS