Review open issues, selecting an issue to work on, filtering issues by area, pulling GitHub issues, or deciding what to work on next. Triggers include "check issues", "list issues", "what issues", "open issues", "show issues", "view issues", "select issue to work on", "github issues", "backlog issues", "pull issues", "check todos" (deprecated), "list todos" (deprecated), "pending todos" (deprecated).
Review open issues, selecting an issue to work on, filtering issues by area, pulling GitHub issues, or deciding what to work on next. Triggers include "check issues", "list issues", "what issues", "open issues", "show issues", "view issues", "select issue to work on", "github issues", "backlog issues", "pull issues", "check todos" (deprecated), "list todos" (deprecated), "pending todos" (deprecated).
metadata
{"version":"0.2.0"}
List all open issues, allow selection, load full context for the selected issue, and route to appropriate action.
Enables reviewing captured ideas and deciding what to work on next.
@.planning/STATE.md
@.planning/ROADMAP.md
**If the user invoked with "todo" vocabulary** (e.g., "check todos", "list todos", "pending todos"):
Display:
Note: "todos" is now "issues". Using /kata-check-issues.
Then proceed with the action (non-blocking).
Check if legacy `.planning/todos/` exists and needs migration:
if [ -d ".planning/todos/pending" ] && [ ! -d ".planning/todos/_archived" ]; then# Create new structuremkdir -p .planning/issues/open .planning/issues/in-progress .planning/issues/closed
# Copy pending todos to open issuescp .planning/todos/pending/*.md .planning/issues/open/ 2>/dev/null || true# Copy done todos to closed issues
.planning/todos/done/*.md .planning/issues/closed/ 2>/dev/null ||
-p .planning/todos/_archived
.planning/todos/pending .planning/todos/_archived/ 2>/dev/null ||
.planning/todos/done .planning/todos/_archived/ 2>/dev/null ||
-p .planning/issues/in-progress
```bash
OPEN_COUNT=$(find .planning/issues/open -maxdepth 1 -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
IN_PROGRESS_COUNT=$(find .planning/issues/in-progress -maxdepth 1 -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
echo "Open issues: $OPEN_COUNT"
echo "In progress: $IN_PROGRESS_COUNT"
```
Check for area filter in arguments:
- `/kata-check-issues` → show all
- `/kata-check-issues api` → filter to area:api only
**1. Check GitHub config:**
```bash
GITHUB_ENABLED=$(node "${CLAUDE_PLUGIN_ROOT}/skills/kata-check-issues/scripts/kata-lib.cjs" read-config "github.enabled" "false")
```
Wait for user to reply with a number.
**If local issue (has file path):**
Read the issue file completely. Display:
```bash
ls .planning/ROADMAP.md 2>/dev/null && echo "Roadmap exists"
```
**If in-progress issue:**
**Pull to local (GitHub-only issues):**
Create local file from GitHub Issue:
```bash
# Get issue details
ISSUE_DATA=$(gh issue view $ISSUE_NUMBER --json title,body,createdAt,labels)
TITLE=$(echo "$ISSUE_DATA" | jq -r '.title')
BODY=$(echo "$ISSUE_DATA" | jq -r '.body')
CREATED=$(echo "$ISSUE_DATA" | jq -r '.createdAt')
After any action that changes issue count:
If issue state changed, commit the change:
- Moved issue to `.planning/issues/in-progress/` (if "Work on it now" with mode selection)
- Moved issue to `.planning/issues/closed/` (if "Mark complete")
- Moved issue to `.planning/issues/open/` (if "Put back to open")
- Created `.planning/issues/open/` file (if "Pull to local" from GitHub)
- Updated `.planning/STATE.md` (if issue count changed)
- Routed to `/kata-execute-quick-task` (if "Quick task" mode selected)
- Displayed planned execution guidance (if "Planned" mode selected)
cp
true
# Archive originals
mkdir
mv
true
mv
true
echo
"Migrated todos to issues format"
fi
# Ensure in-progress directory exists
mkdir
Migration is idempotent: presence of _archived/ indicates already migrated.
If both counts are 0:
No open or in-progress issues.
Issues are captured during work sessions with /kata-add-issue.
---
Would you like to:
1. Continue with current phase (/kata-track-progress)
2. Add an issue now (/kata-add-issue)
Exit.
2. Build dedupe list from local files' provenance fields:
# Get all GitHub issue numbers already tracked locally (from open and in-progress)
LOCAL_PROVENANCE=$(grep -h "^provenance: github:" .planning/issues/open/*.md .planning/issues/in-progress/*.md 2>/dev/null | grep -oE '#[0-9]+' | tr -d '#' | sort -u)
3. Query GitHub Issues (if enabled):
if [ "$GITHUB_ENABLED" = "true" ]; then# Get GitHub Issues with backlog label, excluding those already tracked locally# Note: --label flag has issues in some gh CLI versions, use jq filter instead
GITHUB_ISSUES=$(gh issue list --state open --json number,title,createdAt,labels --jq '.[] | select(.labels[].name == "backlog") | "\(.createdAt)|\(.title)|github|\(.number)"' 2>/dev/null)
fi
created: ${timestamp}
title: ${TITLE}
area: general
provenance: github:${OWNER_REPO}#${ISSUE_NUMBER}
files: []
Problem
${BODY}
Solution
TBD
EOF
The `provenance` field enables deduplication on subsequent checks.
Confirm: "Pulled GitHub Issue #[number] to local: .planning/issues/open/[filename]"
Return to list or offer to work on it.
**Work on it now (open local issue):**
**Based on mode selection from offer_actions step:**
**If "Quick task" mode selected:**
1. Move from open to in-progress:
```bash
mv ".planning/issues/open/[filename]" ".planning/issues/in-progress/"
ISSUE_FILE=".planning/issues/in-progress/[filename]"
# Add in-progress label to GitHub Issue if linked
PROVENANCE=$(grep "^provenance:" "$ISSUE_FILE" | cut -d' ' -f2)
if echo "$PROVENANCE" | grep -q "^github:"; then
ISSUE_NUMBER=$(echo "$PROVENANCE" | grep -oE '#[0-9]+' | tr -d '#')
if [ -n "$ISSUE_NUMBER" ]; then
GITHUB_ENABLED=$(node "${CLAUDE_PLUGIN_ROOT}/skills/kata-check-issues/scripts/kata-lib.cjs" read-config "github.enabled" "false")
if [ "$GITHUB_ENABLED" = "true" ]; then
gh label create "in-progress" --description "Issue is actively being worked on" --color "FFA500" 2>/dev/null || true
gh issue edit "$ISSUE_NUMBER" --add-label "in-progress" 2>/dev/null || true
gh issue edit "$ISSUE_NUMBER" --add-assignee @me 2>/dev/null || true
fi
fi
fi
Display:
Starting quick task execution for issue: [title]
Route to execute-quick-task with issue context:
/kata-execute-quick-task --issue "$ISSUE_FILE"
The execute-quick-task skill will handle planning, execution, and PR creation.
If "Planned" mode selected:
Do NOT move issue to in-progress yet. Present planned execution options:
Use AskUserQuestion:
header: "Planned Execution"
question: "How should this issue be planned?"
options:
"Create new phase" — Add a phase to the roadmap for this issue
"Link to existing phase" — Associate with an upcoming phase
Creating phase from issue: ${ISSUE_TITLE}
${ISSUE_NUMBER:+GitHub Issue: #${ISSUE_NUMBER}}
The new phase will be linked to this issue.
When the phase PR merges, the issue will close automatically.
---
## ▶ Next Up
**Create Phase:** ${ISSUE_TITLE}
`/kata-add-phase --issue ${ISSUE_FILE}`
<sub>`/clear` first → fresh context window</sub>
---
Note: Issue remains in open/ until phase work begins.
When phase planning starts, move issue to in-progress manually
or use /kata-check-issues to update status.
Keep issue in open/ (do NOT move to in-progress yet).
If "Link to existing phase" selected:
Find upcoming phases that might match:
# Get phase directories that are not yet complete (no SUMMARY.md for all plans)# This is a heuristic - phases with incomplete plans
UPCOMING_PHASES=""# Scan all phase directories across states
ALL_PHASE_DIRS=""for state in active pending completed; do
[ -d ".planning/phases/${state}" ] && ALL_PHASE_DIRS="${ALL_PHASE_DIRS}$(find .planning/phases/${state} -maxdepth 1 -type d -not -name "${state}" 2>/dev/null)"done# Fallback: include flat directories (backward compatibility)
FLAT_DIRS=$(find .planning/phases -maxdepth 1 -type d -name "[0-9]*" 2>/dev/null)
[ -n "$FLAT_DIRS" ] && ALL_PHASE_DIRS="${ALL_PHASE_DIRS}${FLAT_DIRS}"for phase_dir in$ALL_PHASE_DIRS; do
[ -d "$phase_dir" ] || continue
phase_name=$(basename"$phase_dir")
# Check if phase has at least one PLAN.md but missing at least one SUMMARY.md
plan_count=$(find "$phase_dir" -maxdepth 1 -name "*-PLAN.md" 2>/dev/null | wc -l)
summary_count=$(find "$phase_dir" -maxdepth 1 -name "*-SUMMARY.md" 2>/dev/null | wc -l)
if [ "$plan_count" -gt 0 ] && [ "$plan_count" -gt "$summary_count" ]; then# Extract phase goal from roadmap
phase_num=$(echo"$phase_name" | grep -oE '^[0-9]+')
phase_goal=$(grep -A2 "### Phase ${phase_num}:" .planning/ROADMAP.md | grep "Goal:" | cut -d':' -f2- | xargs)
UPCOMING_PHASES="${UPCOMING_PHASES}\n- ${phase_name}: ${phase_goal}"fidone
If matching phases found, present selection:
Upcoming phases that could include this issue:
${UPCOMING_PHASES}
To link this issue to a phase:
1. Note the issue reference when planning that phase
2. Include issue context in the phase PLAN.md
3. The issue PR will close the issue when merged
Which phase? (Enter phase name or "none" to go back)
Issue linked to phase: ${PHASE_NAME}
${ISSUE_TITLE}
File: ${ISSUE_FILE}
${GITHUB_REF:+GitHub: ${GITHUB_REF}}
The issue will be included when planning this phase.
Issue remains in open/ until phase work begins.
Keep issue in open/
If no phases found:
No upcoming phases found.
Options:
- /kata-add-phase --issue ${ISSUE_FILE} — Create a new phase
- /kata-track-progress — View current roadmap status
- Put it back — Return to issue list
If "Put it back" selected from planned execution:
Return to list_issues step.
If "Put it back" selected from mode selection:
Return to list_issues step.
Legacy behavior (no mode selection, direct work):
If proceeding without mode selection (e.g., for in-progress issues):
Move from open to in-progress (does NOT close GitHub Issue):
mv".planning/issues/open/[filename]"".planning/issues/in-progress/"# Add in-progress label to GitHub Issue if linked
PROVENANCE=$(grep "^provenance:"".planning/issues/in-progress/[filename]" | cut -d' ' -f2)
ifecho"$PROVENANCE" | grep -q "^github:"; then
ISSUE_NUMBER=$(echo"$PROVENANCE" | grep -oE '#[0-9]+' | tr -d '#')
if [ -n "$ISSUE_NUMBER" ]; then
GITHUB_ENABLED=$(node "${CLAUDE_PLUGIN_ROOT}/skills/kata-check-issues/scripts/kata-lib.cjs" read-config "github.enabled""false")
if [ "$GITHUB_ENABLED" = "true" ]; then# Create in-progress label idempotently (ignore error if exists)
gh label create "in-progress" --description "Issue is actively being worked on" --color "FFA500" 2>/dev/null || true# Add in-progress label (keeps backlog label)
gh issue edit "$ISSUE_NUMBER" --add-label "in-progress" 2>/dev/null \
&& echo"Added in-progress label to GitHub Issue #${ISSUE_NUMBER}" \
|| echo"Warning: Failed to add in-progress label to GitHub Issue #${ISSUE_NUMBER}"# Assign issue to self
gh issue edit "$ISSUE_NUMBER" --add-assignee @me 2>/dev/null \
&& echo"Assigned GitHub Issue #${ISSUE_NUMBER} to @me" \
|| echo"Warning: Failed to assign GitHub Issue #${ISSUE_NUMBER}"fififi
Display confirmation:
Issue moved to in-progress: [filename]
[title]
Area: [area]
GitHub: Linked to #[number], added in-progress label, assigned to @me
-or- Not linked (if no provenance)
Ready to begin work.
When complete, use `/kata-check-issues` and select "Mark complete".
Update STATE.md issue count. Present problem/solution context. Begin work or ask how to proceed.
Work on it now (GitHub-only issue):
First execute "Pull to local" action to create local file, then proceed based on mode selection.
Based on mode selection from offer_actions step:
If "Quick task" mode selected:
Pull to local (creates file at .planning/issues/open/${date_prefix}-${slug}.md)
Move to in-progress:
mv".planning/issues/open/${date_prefix}-${slug}.md"".planning/issues/in-progress/"
ISSUE_FILE=".planning/issues/in-progress/${date_prefix}-${slug}.md"# Add in-progress label to GitHub Issue (we know it's GitHub-linked)
GITHUB_ENABLED=$(node "${CLAUDE_PLUGIN_ROOT}/skills/kata-check-issues/scripts/kata-lib.cjs" read-config "github.enabled""false")
if [ "$GITHUB_ENABLED" = "true" ]; then
gh label create "in-progress" --description "Issue is actively being worked on" --color "FFA500" 2>/dev/null || true
gh issue edit "$ISSUE_NUMBER" --add-label "in-progress" 2>/dev/null || true
gh issue edit "$ISSUE_NUMBER" --add-assignee @me 2>/dev/null || truefi
Display:
Starting quick task execution for issue: [title]
Route to execute-quick-task with issue context:
/kata-execute-quick-task --issue "$ISSUE_FILE"
If "Planned" mode selected:
Pull to local (creates file at .planning/issues/open/${date_prefix}-${slug}.md)
Do NOT move to in-progress. Present planned execution options:
Use AskUserQuestion:
header: "Planned Execution"
question: "How should this issue be planned?"
options:
"Create new phase" — Add a phase to the roadmap for this issue
"Link to existing phase" — Associate with an upcoming phase
"Put it back" — Return to issue list
If "Create new phase" selected (GitHub-only issue):
Extract issue context (already have from pull-to-local):
ISSUE_FILE=".planning/issues/open/${date_prefix}-${slug}.md"
ISSUE_TITLE=$(grep "^title:""$ISSUE_FILE" | cut -d':' -f2- | xargs)
# ISSUE_NUMBER already available from the GitHub-only flow
Display routing guidance:
Creating phase from issue: ${ISSUE_TITLE}
GitHub Issue: #${ISSUE_NUMBER}
The new phase will be linked to this issue.
When the phase PR merges, the issue will close automatically.
---
## ▶ Next Up
**Create Phase:** ${ISSUE_TITLE}
`/kata-add-phase --issue ${ISSUE_FILE}`
<sub>`/clear` first → fresh context window</sub>
---
Note: Issue remains in open/ until phase work begins.
When phase planning starts, move issue to in-progress manually
or use /kata-check-issues to update status.
Keep issue in open/ (do NOT move to in-progress yet).
If "Link to existing phase" selected (GitHub-only issue):
Find upcoming phases (same logic as local issue path):
UPCOMING_PHASES=""
ALL_PHASE_DIRS=""for state in active pending completed; dofor d in .planning/phases/${state}/*/; do
[ -d "$d" ] && ALL_PHASE_DIRS="$ALL_PHASE_DIRS$d"donedone# Flat directory fallback (unmigrated projects)for d in .planning/phases/[0-9]*/; do
[ -d "$d" ] && ALL_PHASE_DIRS="$ALL_PHASE_DIRS$d"donefor phase_dir in$ALL_PHASE_DIRS; do
phase_name=$(basename"$phase_dir")
plan_count=$(find "$phase_dir" -maxdepth 1 -name "*-PLAN.md" 2>/dev/null | wc -l)
summary_count=$(find "$phase_dir" -maxdepth 1 -name "*-SUMMARY.md" 2>/dev/null | wc -l)
if [ "$plan_count" -gt 0 ] && [ "$plan_count" -gt "$summary_count" ]; then
phase_num=$(echo"$phase_name" | grep -oE '^[0-9]+')
phase_goal=$(grep -A2 "### Phase ${phase_num}:" .planning/ROADMAP.md | grep "Goal:" | cut -d':' -f2- | xargs)
UPCOMING_PHASES="${UPCOMING_PHASES}\n- ${phase_name}: ${phase_goal}"fidone
If matching phases found, present selection:
Upcoming phases that could include this issue:
${UPCOMING_PHASES}
To link this issue to a phase:
1. Note the issue reference when planning that phase
2. Include issue context in the phase PLAN.md
3. The issue PR will close the issue when merged
Which phase? (Enter phase name or "none" to go back)
If phase selected (GitHub-only issue):
Note: For GitHub-only issues, the local file was just created by "Pull to local" step.
Use the same linkage logic as local issues (see above for full implementation).
Issue linked to phase: ${PHASE_NAME}
${ISSUE_TITLE}
File: ${ISSUE_FILE}
GitHub: #${ISSUE_NUMBER}
The issue will be included when planning this phase.
Issue remains in open/ until phase work begins.
Keep issue in open/
If no phases found:
No upcoming phases found.
Options:
- /kata-add-phase --issue ${ISSUE_FILE} — Create a new phase
- /kata-track-progress — View current roadmap status
- Put it back — Return to issue list
If "Put it back" selected from planned execution:
Return to list_issues step (do not pull to local).
If "Put it back" selected from mode selection:
Return to list_issues step (do not pull to local).
Legacy behavior (no mode selection):
If proceeding without mode selection:
mv".planning/issues/open/${date_prefix}-${slug}.md"".planning/issues/in-progress/"# Add in-progress label to GitHub Issue (we know it's GitHub-linked since this is the GitHub-only path)
GITHUB_ENABLED=$(node "${CLAUDE_PLUGIN_ROOT}/skills/kata-check-issues/scripts/kata-lib.cjs" read-config "github.enabled""false")
if [ "$GITHUB_ENABLED" = "true" ]; then# Create in-progress label idempotently (ignore error if exists)
gh label create "in-progress" --description "Issue is actively being worked on" --color "FFA500" 2>/dev/null || true# Add in-progress label (keeps backlog label)# Note: $ISSUE_NUMBER is already available from the pull-to-local step
gh issue edit "$ISSUE_NUMBER" --add-label "in-progress" 2>/dev/null \
&& echo"Added in-progress label to GitHub Issue #${ISSUE_NUMBER}" \
|| echo"Warning: Failed to add in-progress label to GitHub Issue #${ISSUE_NUMBER}"# Assign issue to self
gh issue edit "$ISSUE_NUMBER" --add-assignee @me 2>/dev/null \
&& echo"Assigned GitHub Issue #${ISSUE_NUMBER} to @me" \
|| echo"Warning: Failed to assign GitHub Issue #${ISSUE_NUMBER}"fi
Display confirmation:
Issue moved to in-progress: [filename]
[title]
Area: [area]
GitHub: Linked to #[number], added in-progress label, assigned to @me
Ready to begin work.
When complete, use `/kata-check-issues` and select "Mark complete".
Update STATE.md issue count. Present problem/solution context. Begin work or ask how to proceed.
Mark complete (in-progress issue):
Move from in-progress to closed and close GitHub Issue if linked:
mv".planning/issues/in-progress/[filename]"".planning/issues/closed/"# Check if issue has GitHub provenance
PROVENANCE=$(grep "^provenance:"".planning/issues/closed/[filename]" | cut -d' ' -f2)
ifecho"$PROVENANCE" | grep -q "^github:"; then# Extract issue number from provenance (format: github:owner/repo#N)
ISSUE_NUMBER=$(echo"$PROVENANCE" | grep -oE '#[0-9]+' | tr -d '#')
if [ -n "$ISSUE_NUMBER" ]; then# Check github.enabled (may have changed since issue was created)
GITHUB_ENABLED=$(node "${CLAUDE_PLUGIN_ROOT}/skills/kata-check-issues/scripts/kata-lib.cjs" read-config "github.enabled""false")
if [ "$GITHUB_ENABLED" = "true" ]; then# Close GitHub Issue with comment
gh issue close "$ISSUE_NUMBER" --comment "Completed via Kata workflow" 2>/dev/null \
&& echo"Closed GitHub Issue #${ISSUE_NUMBER}" \
|| echo"Warning: Failed to close GitHub Issue #${ISSUE_NUMBER}"fififi
Display confirmation:
Issue completed: [filename]
[title]
Area: [area]
GitHub: Closed #[number] (if provenance exists and close succeeded)
-or- Not linked (if no provenance)
-or- Failed to close #[number] (if close failed)
Issue closed.
Update STATE.md issue count.
Put back to open (in-progress issue):
Move from in-progress back to open:
