Do Issue

Table of Contents

• Key Features
• Workflow Overview
• Required TodoWrite Items
• Configuration
• Detailed Resources

Fix Issue(s)

Retrieves issue content from the detected git platform (GitHub, GitLab, or Bitbucket) and uses subagent-driven-development to systematically address requirements, executing tasks in parallel where dependencies allow.

Platform detection is automatic via the leyline:git-platform SessionStart hook. Check session context for git_platform: to determine which CLI to use.

Key Features

• Cross-Platform: Automatically detects GitHub/GitLab/Bitbucket and uses appropriate CLI
• Flexible Input: Single issue number, platform URL, or space-delimited list
• Parallel Execution: Independent tasks run concurrently via subagents
• One PR: All issues produce one consolidated PR (never per-issue PRs)
• Quality Gates: Code review between task groups
• Fresh Context: Each subagent starts with clean context for focused work

Workflow Overview

Required TodoWrite Items

1. do-issue:discovery-complete 2. do-issue:tasks-planned 3. do-issue:parallel-batch-complete 4. do-issue:review-passed 5. do-issue:sequential-complete 6. do-issue:issues-updated

Forge CLI Commands

Use the platform detected in session context (git_platform:). See Skill(leyline:git-platform) for full mapping.

Verification: Run the command with --help flag to verify availability.

Agent Teams (Default Execution Mode)

Agent teams is the default parallel execution backend for do-issue. Teammates coordinate via filesystem-based messaging, enabling real-time communication when shared files or dependencies are discovered mid-implementation.

Automatic downgrade: For single issues with --scope minor, agent teams is skipped (Task tool or inline execution is used instead). Use --no-agent-teams to force Task tool dispatch for any invocation.

Requires: Claude Code 2.1.32+, tmux, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. If prerequisites are missing, silently falls back to Task tool dispatch.

# Agent teams configuration
fix_issue:
  agent_teams:
    enabled: true           # on by default; --no-agent-teams to disable
    max_teammates: 4        # limit concurrent workers
    model: sonnet           # teammate model (lead uses current model)
    auto_downgrade: true    # skip agent teams for --scope minor

See modules/parallel-execution.md for detailed agent teams patterns.

Configuration

fix_issue:
  parallel_execution: true
  max_parallel_subagents: 3
  review_between_batches: true
  auto_close_issues: false
  commit_per_task: true

Verification: Run the command with --help flag to verify availability.

Detailed Resources

• Phase 1: See modules/issue-discovery.md for input parsing and requirement extraction
• Phase 2: See modules/task-planning.md for dependency analysis
• Phase 3: See modules/parallel-execution.md for subagent dispatch
• Phase 4: See modules/quality-gates.md for review patterns
• Phase 5-6: See modules/completion.md for finalization
• Errors: See modules/troubleshooting.md for common issues

Phases 5-6: Completion

Execute sequential tasks and finalize the workflow.

Phase 5: Sequential Tasks

For tasks with dependencies, execute sequentially:

Task tool (general-purpose):
  description: "Issue #42 - Task 2: Add login endpoint"
  prompt: |
    You are implementing Task 2 from Issue #42.

    This task depends on completed Task 1 (auth middleware).

    [Task requirements]

    Verify Task 1's middleware works before building on it.

Review after each sequential task following the subagent-driven-development pattern.

Phase 6: Final Review

Dispatch detailed review of all changes:

Task tool (superpowers:code-reviewer):
  description: "Final review: Issues #42, #43, #44"
  prompt: |
    Review complete implementation for issues: #42, #43, #44

    Verify:
    - All acceptance criteria met
    - Tests detailed and passing
    - No regressions introduced
    - Code quality meets standards
    - Documentation updated if needed

Update Issue Status

For each completed issue:

# Add completion comment
gh issue comment 42 --body "Fixed in commit $(git rev-parse --short HEAD)

Changes:
- Implemented auth middleware
- Added login endpoint
- Added detailed tests

Ready for review."

# Optionally close issue
gh issue close 42 --comment "Completed via automated fix workflow"

Pre-PR Consolidation Check

Before creating the PR, verify all work is on ONE branch:

# Confirm current branch contains all issue commits
git log --oneline --grep="Fixes #42" --grep="Fixes #43" \
  --all-match HEAD
# If commits are on separate branches, cherry-pick or
# rebase them onto the shared branch first.

Finish Development

Use superpowers:finishing-a-development-branch to:

• Verify all tests pass
• Present merge options
• Execute chosen completion path

One PR rule: Always create exactly ONE pull request that references all issues via Fixes #N lines in the body. See Step 6.2 in the do-issue command for the template. Never create separate PRs per issue.

Tooling Reflection (Night-Market Feedback Loop)

After completing the workflow, reflect on the tooling itself (skills, agents, commands, hooks) rather than the repo code:

• Did any skill behave unexpectedly or have unclear guidance?
• Was a subagent slow, redundant, or missing context?
• Did the do-issue command skip steps or require unnecessary

manual intervention?

• Did a hook fire incorrectly or miss a case?

If yes, post to https://github.com/athola/claude-night-market/discussions (Learnings category) using the pattern from fix-pr Step 6.7. Always target the night-market repo, not the current working repo.

If no observations, skip this step silently.

Repo-specific learnings stay in the current repo. Tooling

learnings always go to

https://github.com/athola/claude-night-market/discussions

so the framework can improve.

Record Lessons Learned (decision journal)

If this work involved rework, a failed approach, or a blocker, record it to docs/lessons-learned.md so the insight survives past the session (draft and confirm):

• If leyline is installed, invoke Skill(leyline:decision-journal) and append

a lesson entry (what_happened, what_didnt_work, root_cause, action; set phase to execute). Show the draft; append on confirmation.

• Fallback (leyline absent): append to docs/lessons-learned.md using the

in-file ENTRY TEMPLATE; assign the next LL-NNN id.

Example Final Output

Final Review: All requirements met

Issues Summary:
  #42: 3 tasks completed, all tests passing
  #43: 2 tasks completed, all tests passing
  #44: 1 task completed, all tests passing

PR: fix(auth): add middleware and login endpoint (#42, #43, #44)
  - Fixes #42, Fixes #43, Fixes #44
  - All issues consolidated in single PR

Phase 1: Issue Discovery

Parse input arguments and retrieve issue content from the detected git platform. Check session context for git_platform: to determine which CLI to use.

Input Formats

The command accepts flexible input:

# Single issue number
/do-issue 42

# Platform URL (GitHub or GitLab)
/do-issue https://github.com/owner/repo/issues/42
/do-issue https://gitlab.com/owner/repo/-/issues/42

# Multiple issues (space-delimited)
/do-issue 42 43 44

# Mixed formats
/do-issue 42 https://github.com/owner/repo/issues/43

Retrieve Issue Content

For each issue, fetch the full content using the platform-appropriate CLI:

# GitHub
gh issue view 42 --json title,body,labels,assignees,comments
gh issue view https://github.com/owner/repo/issues/42 --json title,body,labels,assignees,comments

# GitLab
glab issue view 42

Extract Requirements

From each issue body, identify:

Example Output

Fetching issue #42...
Title: Add user authentication
Requirements identified: 4
  - Acceptance Criteria: 2
  - Technical Requirements: 1
  - Test Expectations: 1
Tasks will be generated: 3

Next Phase

After discovery, proceed to task-planning.md for dependency analysis and task breakdown.

Phase 3: Parallel Execution

Dispatch subagents for independent tasks concurrently.

Important: Plan Before Large Dispatch

When dispatching 4+ agents, enter plan mode first:

Why This Threshold Exists

Large agent dispatches (4+ agents) create:

• Observability loss: Too many concurrent outputs to track
• Context overflow: Research agents produce large results, triggering continuation agents that lose state
• Recovery difficulty: If 2 of 7 agents fail, there's no plan to resume from
• Wasted compute: Without user alignment, agents may research the wrong things

Plan-Before-Dispatch Checklist

Before launching 4+ agents, your plan should specify:

1. Agent roster: Name, type (general-purpose/Explore/specialized), and model (sonnet/haiku/opus) for each 2. Scope per agent: Exactly what each agent investigates (files, topics, questions) 3. Output contract: What each agent should return (format, length, key questions to answer) 4. Result integration: How you'll combine agent outputs into a coherent response 5. Failure strategy: What happens if an agent hits context limits or returns incomplete results

Example Plan Structure

## Agent Dispatch Plan: [Goal]

### Agents (N total)

| # | Agent Type | Model | Scope | Output Contract |
|---|-----------|-------|-------|-----------------|
| 1 | Explore | haiku | Search plugins/ for X | File paths + summaries |
| 2 | general-purpose | sonnet | Research Y via web | Key findings, 500 words max |
| 3 | general-purpose | sonnet | Analyze Z files | Structured assessment |

### Integration Strategy
[How results combine into final answer]

### Failure Handling
- Agent timeout/overflow: [strategy]
- Incomplete results: [strategy]

Enforcement

This rule applies to ALL multi-agent dispatches, including:

• Research/audit missions (web + codebase analysis)
• Large refactoring across many files
• Thorough review tasks
• Any task requiring continuation agents

WARNING: Remote Control / Headless Limitations

Avoid running parallel subagent dispatches via `/remote-control` or headless SDK sessions.

The Task tool blocks the main thread while awaiting subagent completion. If any subagent hangs (a known upstream bug), the parent session becomes unrecoverable because remote-control has no programmatic equivalent of the Esc interrupt.

Safe alternatives for remote-control use:

• Use run_in_background: true on Agent calls
• Run with --scope minor (inline execution, no

subagent dispatch)

• Use a local terminal with remote-control as a

monitoring-only window

See troubleshooting.md for recovery steps if a subagent hangs.

Execute Nonconflicting Tasks in Parallel

When you have multiple nonconflicting tasks, invoke all Task tools in a single response.

Parallel execution is the default for nonconflicting tasks.

Identify Nonconflicting Tasks

Tasks can run in parallel only when all conditions are met:

✅ Safe for parallel execution:

• Tasks modify different files (no overlap)
• Tasks have no shared state (independent data)
• Tasks don't modify same code paths (no merge conflicts)
• Tasks have satisfied dependencies (no blocking)
• Tasks don't depend on each other's outputs

❌ Not safe for parallel execution:

• Tasks modify the same file or related files
• Tasks share configuration or global state
• Tasks have sequential dependencies
• Tasks touch overlapping code paths that could conflict
• Tasks need results from each other
• Both tasks are [R:RED] (compounding risk prohibited)
• Either task is [R:CRITICAL] (always executes solo)

Analyze Task Conflicts BEFORE Dispatching

Required: Perform conflict analysis before parallel execution:

Analyzing tasks for parallel execution:

Task 1 (Issue #42): Create auth middleware in src/auth/middleware.py
Task 2 (Issue #43): Fix validation bug in src/validators/schema.py
Task 3 (Issue #44): Add logging to src/utils/logger.py

Conflict Check:
- Files: ✅ No overlap (middleware.py, schema.py, logger.py are different)
- Dependencies: ✅ No sequential dependencies between tasks
- State: ✅ No shared configuration or database schema
- Code paths: ✅ Independent modules, no import conflicts

Decision: Execute Tasks 1, 2, 3 in PARALLEL (3 Task tool invocations in single response)

COUNTER-EXAMPLE - Sequential execution required:

Task A (Issue #50): Refactor User model in models/user.py
Task B (Issue #51): Add authentication using User model

Conflict Check:
- Files: ❌ Task B depends on Task A's User model changes
- Dependencies: ❌ Task B needs Task A's output
- Code paths: ❌ Both touch authentication flow

Decision: Execute SEQUENTIALLY (Task A first, then Task B)

Risk-Tier Parallel Safety

When tasks have [R:TIER] markers (from leyline:risk-classification), apply these additional constraints:

Tasks without [R:TIER] markers are treated as GREEN (backward compatible).

Dispatch Parallel Subagents

All subagents commit to the SAME branch. The parent creates one shared branch before dispatch (Step 4.1) and all work lands there. Do not create per-issue branches. This produces one PR at completion.

CORRECT PATTERN - Multiple Task tool invocations in ONE response:

I'll execute these 3 nonconflicting tasks in parallel:

Task(description: "Issue #42 - Create auth middleware")
Task(description: "Issue #43 - Fix validation bug")
Task(description: "Issue #44 - Add logging feature")

Each task will:
1. Work on the current branch (fix/issues-42-43-44)
2. Implement in its designated file (no conflicts)
3. Follow TDD - write failing test first
4. Verify no regressions
5. Commit with conventional format

WRONG PATTERN - Sequential invocations:

❌ Task(description: "Issue #42")
   [wait for result]
   Task(description: "Issue #43")
   [wait for result]

This wastes time when tasks are nonconflicting!

Await Parallel Results

Collect results from all parallel subagents before proceeding:

Parallel Batch 1: Issues #42, #43, #44 (3 tasks)
  [3 subagents running in parallel...]

  ✅ #42: Complete (auth middleware in src/auth/middleware.py)
  ✅ #43: Complete (validation fix in src/validators/schema.py)
  ✅ #44: Complete (logging in src/utils/logger.py)

All tasks completed without conflicts.

Key Principles

Agent Teams (Default Execution Backend)

Agent teams is the default for parallel execution in do-issue. Teammates coordinate via filesystem-based messaging, which prevents merge conflicts and duplicate work that Task tool batches would only catch at the review gate.

Use --no-agent-teams to fall back to Task tool dispatch when coordination overhead isn't justified.

Automatic Downgrade

Agent teams is skipped (Task tool or inline used instead) when:

• Single issue with --scope minor (no parallelism needed)
• tmux is not installed or CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS is unset
• --no-agent-teams flag is explicitly passed

When Task Tool Is Better

Agent Teams Execution Pattern

Lead agent creates team: do-issue-{timestamp}
  Spawns: worker-1 (Sonnet), worker-2 (Sonnet), worker-3 (Sonnet)

Lead assigns tasks via inbox:
  worker-1: "Implement #42 (auth middleware) in src/auth/"
  worker-2: "Fix #43 (validation bug) in src/validators/"
  worker-3: "Add #44 (logging) in src/utils/"

Mid-execution coordination:
  worker-1 → worker-3: "I added auth logging to src/auth/log.py —
    don't duplicate in your logging task"
  worker-3 → worker-1: "Acknowledged, will import from your module"

Lead collects completion messages, runs quality gates, shuts down team.

Key Difference from Task Tool

Task tool subagents are fire-and-forget: they can't communicate mid-execution. Agent teams teammates can send messages to each other when they discover shared concerns. This prevents merge conflicts and duplicate work that Task tool batches would catch only at the review gate.

Fallback

If tmux is unavailable or CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS is not set, --agent-teams silently falls back to standard Task tool dispatch.

Worktree Isolation for Parallel Safety (Claude Code 2.1.49+)

Subagents with isolation: "worktree" run in a temporary git worktree, providing filesystem-level isolation.

When to Use Worktree Isolation

Worktree Behavior

• Agents with worktree isolation get a separate checkout
• Empty worktrees are auto-cleaned; worktrees with

changes return worktreePath and worktreeBranch

• If worktreePath is NOT in the agent result, changes

either landed in the main workdir or were lost

Post-Dispatch Verification (MANDATORY)

After ALL parallel agents complete, verify before proceeding:

## Post-Dispatch Checklist

1. [ ] Check `git worktree list` for remaining worktrees
2. [ ] Check `git diff --stat` in main workdir for changes
3. [ ] For each agent with worktree output:
   - Verify worktree changes via `git diff` in worktree
   - Merge or cherry-pick into main branch
   - Remove worktree: `git worktree remove <path>`
4. [ ] For agents that deleted + recreated files:
   - Verify new files exist: `ls <expected-paths>`
   - Verify imports work: `python -c "from X import Y"`
   - If directory exists but is empty, restore original:
     `git checkout HEAD -- <original-path>`
5. [ ] Run affected tests before committing

Never Mix Worktree and Direct Agents on Same Files

When agents A (worktree) and B (direct) both modify foo.py, only one set of changes survives. Either:

• Use worktree isolation for ALL agents in the batch, or
• Use direct (no isolation) for ALL agents in the batch

Mixing isolation modes on overlapping files causes silent data loss.

Agent Path Confusion

Agents in worktrees or with cd in their prompts can write files to wrong paths. Common failure modes:

• Creates ./foo/ instead of ./plugins/bar/foo/
• Deletes original but new directory is empty (agent

hit context limit mid-operation)

Mitigation: include absolute paths in agent prompts and verify file existence after completion.

Next Phase

After parallel execution completes, proceed to quality-gates.md for batch review.

Phase 4: Quality Gates

Code review between task batches to catch issues early.

Batch Code Review

After parallel batch completes, review all changes:

Task tool (superpowers:code-reviewer):
  description: "Review parallel batch: Issues #42, #43"
  prompt: |
    Review changes from parallel implementation batch.

    Issues addressed:
    - #42 Task 1: Auth middleware
    - #43 Task 1: Validation fix

    BASE_SHA: [sha before batch]
    HEAD_SHA: [current sha]

    Focus on:
    - Correct implementation per issue requirements
    - No conflicts between parallel changes
    - Test coverage adequate
    - No security vulnerabilities introduced

Review Feedback Categories

Example Review Output

Batch Review...
  All changes valid, no conflicts

Strengths:
  - Good test coverage
  - Follows existing patterns

Issues: None

Proceeding to sequential phase...

Handling Critical Feedback

When critical issues are found:

Task tool (general-purpose):
  description: "Fix critical issue in auth middleware"
  prompt: |
    The code review found a critical issue:
    [Issue description]

    Fix this before proceeding.

Next Phase

After review passes, proceed to completion.md for sequential tasks and finalization.

Phase 2: Task Planning

Analyze issue dependencies and create structured task breakdown.

Dependency Analysis

Identify which issues can be worked in parallel:

def analyze_dependencies(issues):
    """
    Identify which issues can be worked in parallel.
    """
    independent = []
    dependent = []

    for issue in issues:
        if issue.has_no_blockers(issues):
            independent.append(issue)
        else:
            dependent.append({
                'issue': issue,
                'blocked_by': issue.get_blockers(issues)
            })

    return independent, dependent

Task Breakdown

For each issue, generate tasks following superpowers:writing-plans structure:

## Issue #42: Add user authentication

### Task 1: Create auth middleware
- [ ] Implement JWT validation
- [ ] Add route protection decorator
- [ ] Write unit tests

### Task 2: Add login endpoint
- [ ] Create POST /auth/login
- [ ] Implement password verification
- [ ] Return JWT on success
- [ ] Write integration tests

Initialize TodoWrite

Create todos for all tasks across all issues:

- [ ] Issue #42 - Task 1: Create auth middleware
- [ ] Issue #42 - Task 2: Add login endpoint
- [ ] Issue #43 - Task 1: Fix validation bug

Dependency Graph Example

Dependency Graph:
  #42: Independent
  #43: Independent
  #44: Depends on #42

Parallel Batch 1: Issues #42, #43
Sequential Phase: Issue #44

Risk Classification

After task breakdown, classify each task's risk tier using leyline:risk-classification heuristics. Run the heuristic classifier against each task's affected files and append a [R:TIER] marker.

Classification Process

1. For each task, identify the files it will modify 2. Apply leyline:risk-classification/modules/heuristic-classifier.md pattern matching 3. Append [R:TIER] marker to the task line

Task Format with Risk Markers

- [ ] T001 Create project structure per implementation plan
- [ ] T005 [P] [R:YELLOW] Implement authentication middleware in src/middleware/auth.py
- [ ] T012 [P] [US1] [R:YELLOW] Create LoginForm component in src/components/LoginForm.tsx
- [ ] T015 [US2] [R:RED] Add user migration in migrations/002_add_users.py

Tasks without [R:TIER] markers default to GREEN. Markers are additive: existing task formats remain valid without them.

Next Phase

After planning, proceed to parallel-execution.md to dispatch subagents.

Troubleshooting

Common issues and solutions when using do-issue.

Error: Issue Not Found

Error: Issue #42 not found
Verify:
  - Issue exists in current repository
  - You have access to the repository
  - Issue number is correct

Error: Subagent Failure

Error: Subagent failed on Issue #42 Task 2
Cause: Test failures after implementation

Options:
  1. Dispatch fix subagent (recommended)
  2. Skip task and continue
  3. Abort workflow

[Selecting option 1...]
Dispatching fix subagent...

Warning: Merge Conflicts

Warning: Parallel changes created conflicts
Files: src/auth/middleware.ts

Resolution:
  1. Pausing parallel execution
  2. Resolving conflicts via dedicated subagent
  3. Resuming after resolution

Subagent Not Following Requirements

Problem: Subagent implemented feature differently than specified
Solution: Re-dispatch with more explicit prompt including:
  - Exact acceptance criteria from issue
  - Code examples if provided
  - Links to related files

Too Many Parallel Conflicts

Problem: Multiple subagents modifying same files
Solution: Use --no-parallel or manually group tasks to avoid overlap

Review Taking Too Long

Problem: Code review subagent taking excessive time
Solution: Split large batches into smaller groups

Subagent Hangs (Remote Control / Headless)

When running do-issue through /remote-control or headless SDK sessions, subagents can hang indefinitely with no recovery path. This is a known upstream bug (#28482).

Symptoms:

• Task status shows "In progress" forever
• No output, no tool calls, no error from the subagent
• Remote control web UI shows "philosophizing/tinkering"

indefinitely

• New prompts are queued but never processed

Recovery: 1. If you have local terminal access, press Esc to interrupt the hung subagent 2. If headless: kill -SIGINT <claude_pid> to interrupt 3. Start a fresh session rather than trying to resume

Prevention:

• Run subagent-heavy workflows locally, not via

remote-control (Esc is the only recovery mechanism)

• Use run_in_background: true on Agent calls so the

parent can continue processing if a subagent stalls

• Limit concurrent subagents to reduce hang probability
• Monitor from a local terminal even when using remote

control

Related issues:

• #28482 - Agent hang, no headless recovery
• #33232 - Remote-control WebSocket instability
• #13240 - Master freeze/hang bug

Best Practices

Before Running

1. validate clean working directory (git status shows no changes) 2. Pull latest from remote 3. Verify GitHub CLI is authenticated (gh auth status) 4. Review issues briefly to confirm they're ready for implementation

During Execution

1. Monitor subagent progress via TodoWrite 2. Don't manually edit files while subagents are working 3. Let code reviews complete before proceeding 4. Address Critical issues immediately

After Completion

1. Review final changes before merging 2. Verify all tests pass 3. Update issue comments with implementation notes 4. Create PR if working on branch