if [ -d ".planning/todos/pending" ] && [ ! -d ".planning/todos/_archived" ]; then
  # Create new structure
  mkdir -p .planning/issues/open .planning/issues/in-progress .planning/issues/closed

  # Copy pending todos to open issues
  cp .planning/todos/pending/*.md .planning/issues/open/ 2>/dev/null || true

  # Copy done todos to closed issues
  cp .planning/todos/done/*.md .planning/issues/closed/ 2>/dev/null || true

  # Archive originals
  mkdir -p .planning/todos/_archived
  mv .planning/todos/pending .planning/todos/_archived/ 2>/dev/null || true
  mv .planning/todos/done .planning/todos/_archived/ 2>/dev/null || true

  echo "Migrated todos to issues format"
fi

Migration is idempotent: presence of `_archived/` indicates already migrated.
</step>

<step name="check_exist">
```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"

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)

undefined

**3. Query GitHub Issues (if enabled):**
```bash
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

for file in .planning/issues/in-progress/*.md; do
  [ -f "$file" ] || continue
  created=$(grep "^created:" "$file" | cut -d' ' -f2)
  title=$(grep "^title:" "$file" | cut -d':' -f2- | xargs)
  area=$(grep "^area:" "$file" | cut -d' ' -f2)
  echo "$created|$title|$area|$file|in-progress"
done | sort

for file in .planning/issues/open/*.md; do
  [ -f "$file" ] || continue
  created=$(grep "^created:" "$file" | cut -d' ' -f2)
  title=$(grep "^title:" "$file" | cut -d':' -f2- | xargs)
  area=$(grep "^area:" "$file" | cut -d' ' -f2)
  echo "$created|$title|$area|$file|open"
done | sort

Issues:

--- In Progress ---
1. [IN PROGRESS] Fix auth token refresh (api, 2d ago)

--- Open (Backlog) ---
2. Add modal z-index fix (ui, 1d ago)
3. Fix login bug [GH] (bug, 3d ago)
4. Refactor database connection pool (database, 5h ago)

---

Reply with a number to view details, or:
- `/kata-check-issues [area]` to filter by area
- `q` to exit

undefined

If `files` field has entries, read and briefly summarize each.

**If GitHub-only issue (has [GH] indicator):**
Fetch full issue details from GitHub:
```bash
gh issue view $ISSUE_NUMBER --json title,body,createdAt,labels

undefined

Note: This issue exists only in GitHub, not yet pulled to local.
</step>

<step name="check_roadmap">
```bash
ls .planning/ROADMAP.md 2>/dev/null && echo "Roadmap exists"

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]"

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

2. Display:

3. Route to execute-quick-task with issue context:

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
  - "Put it back" — Return to issue list

**If "Create new phase" selected:**

1. Extract issue context for phase creation:
```bash
ISSUE_TITLE=$(grep "^title:" "$ISSUE_FILE" | cut -d':' -f2- | xargs)
PROVENANCE=$(grep "^provenance:" "$ISSUE_FILE" | cut -d' ' -f2)
ISSUE_NUMBER=""
if echo "$PROVENANCE" | grep -q "^github:"; then
  ISSUE_NUMBER=$(echo "$PROVENANCE" | grep -oE '#[0-9]+' | tr -d '#')
fi

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.

---

3. Keep issue in open/ (do NOT move to in-progress yet).

**If "Link to existing phase" selected:**

1. Find upcoming phases that might match:
```bash

2. If matching phases found, present selection:

3. If phase selected:

**Check if issue already linked to a phase:**
```bash
EXISTING_LINKAGE=$(grep "^linked_phase:" "$ISSUE_FILE" 2>/dev/null | cut -d' ' -f2)

This issue is already linked to phase: ${EXISTING_LINKAGE}

Options:
- Override — Link to ${SELECTED_PHASE} instead
- Cancel — Keep existing linkage

ISSUE_FILE="[path to issue file]"
PHASE_NAME="[selected phase name, e.g., '03-issue-roadmap-integration']"

**Step 3b: Update STATE.md with linkage entry:**

```bash
STATE_FILE=".planning/STATE.md"

**Step 3c: Display confirmation:**

   - Keep issue in open/

4. If no phases found:

**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):
```bash
mv ".planning/issues/open/[filename]" ".planning/issues/in-progress/"

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}"
fi

Display confirmation:

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:**

1. Pull to local (creates file at `.planning/issues/open/${date_prefix}-${slug}.md`)
2. Move to in-progress:
```bash
mv ".planning/issues/open/${date_prefix}-${slug}.md" ".planning/issues/in-progress/"
ISSUE_FILE=".planning/issues/in-progress/${date_prefix}-${slug}.md"

3. Display:

4. Route to execute-quick-task with issue context:

**If "Planned" mode selected:**

1. Pull to local (creates file at `.planning/issues/open/${date_prefix}-${slug}.md`)
2. 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):**

1. Extract issue context (already have from pull-to-local):
```bash
ISSUE_FILE=".planning/issues/open/${date_prefix}-${slug}.md"
ISSUE_TITLE=$(grep "^title:" "$ISSUE_FILE" | cut -d':' -f2- | xargs)

2. Display routing guidance:

3. Keep issue in open/ (do NOT move to in-progress yet).

**If "Link to existing phase" selected (GitHub-only issue):**

1. Find upcoming phases (same logic as local issue path):
```bash
UPCOMING_PHASES=""
ALL_PHASE_DIRS=""
for state in active pending completed; do
  for d in .planning/phases/${state}/*/; do
    [ -d "$d" ] && ALL_PHASE_DIRS="$ALL_PHASE_DIRS $d"
  done
done

2. If matching phases found, present selection:

3. 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).

**Check if issue already linked to a phase:**
```bash
ISSUE_FILE=".planning/issues/open/${date_prefix}-${slug}.md"
EXISTING_LINKAGE=$(grep "^linked_phase:" "$ISSUE_FILE" 2>/dev/null | cut -d' ' -f2)

awk -v phase="$PHASE_NAME" '
  /^---$/ && !found {
    print
    print "linked_phase: " phase
    found=1
    next
  }
  { print }
' "$ISSUE_FILE" > "$ISSUE_FILE.tmp" && mv "$ISSUE_FILE.tmp" "$ISSUE_FILE"

STATE_FILE=".planning/STATE.md"
ISSUE_TITLE=$(grep "^title:" "$ISSUE_FILE" | cut -d':' -f2- | xargs)
GITHUB_REF="GitHub: #${ISSUE_NUMBER}"
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

**Step 3c: Display confirmation:**

   - Keep issue in open/

4. If no phases found:

**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:

```bash
mv ".planning/issues/open/${date_prefix}-${slug}.md" ".planning/issues/in-progress/"

Display confirmation:

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:
```bash
mv ".planning/issues/in-progress/[filename]" ".planning/issues/closed/"

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}"
fi

Display confirmation:

Update STATE.md issue count.

**Put back to open (in-progress issue):**
Move from in-progress back to open:
```bash
mv ".planning/issues/in-progress/[filename]" ".planning/issues/open/"

gh issue view $ISSUE_NUMBER --web

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 ' ')
CLOSED_COUNT=$(find .planning/issues/closed -maxdepth 1 -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
echo "Open: $OPEN_COUNT, In Progress: $IN_PROGRESS_COUNT, Closed: $CLOSED_COUNT"

COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false

git add .planning/issues/in-progress/[filename]
git rm --cached .planning/issues/open/[filename] 2>/dev/null || true
[ -f .planning/STATE.md ] && git add .planning/STATE.md

git commit -m "$(cat <<EOF
docs: start work on issue - [title]

Moved to in-progress.
EOF
)"

git add .planning/issues/closed/[filename]
git rm --cached .planning/issues/in-progress/[filename] 2>/dev/null || true
[ -f .planning/STATE.md ] && git add .planning/STATE.md

Confirm: "Committed: docs: complete issue - [title]"

**If moved back to open (Put back to open):**
```bash
git add .planning/issues/open/[filename]
git rm --cached .planning/issues/in-progress/[filename] 2>/dev/null || true
[ -f .planning/STATE.md ] && git add .planning/STATE.md

git commit -m "docs: return issue to backlog - [title]"

open/        → Backlog (not started)
in-progress/ → Actively being worked on
closed/      → Completed