Autonomous Dev Flow

# /autonomous-dev-flow

Orchestrate long-running autonomous dev sessions — work through GitHub issues sequentially with TDD, create PRs, run /full-review, and continue to the next issue. The user reviews and merges PRs asynchronously while work continues.

## Arguments

- `$ARGUMENTS` - Issue source and options. Examples:
  - `label:ready-to-build` (all open issues with this label)
  - `milestone:"v1.2"` (all open issues in milestone)
  - `#12 #15 #18` or `12 15 18` (specific issues by number)
  - `label:ready-to-build max:5 sort:created-asc` (with options)
  - If empty, auto-detect: scan open issues sorted by complexity (low first, then medium, skip high)
  - Options: `max:N` (default 10, hard cap 15), `sort:created-asc` (default) or `sort:created-desc`

## Instructions

### Phase 0: Queue Setup

```bash
REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)

BRANCH_PREFIX="auto/"

Parse $ARGUMENTS to determine the issue source:

• Explicit list: Strip # prefixes, run gh issue view ${NUM} --json number,title,state,labels,body,assignees for each
• Label: gh issue list --label "${LABEL}" --state open --json number,title,labels,assignees --limit ${MAX}
• Milestone: gh issue list --milestone "${MILESTONE}" --state open --json number,title,labels,assignees --limit ${MAX}
• Auto-detect (empty args): gh issue list --state open --json number,title,labels,assignees --limit 30 then sort by complexity label (low first, then medium, skip high)

Apply sort order and cap to max (hard cap 15 — sessions beyond this rarely maintain quality). Recommended: 3-5 issues for first use; sessions of 10+ work best with well-specified, low-complexity issues.

Filter out assigned issues — exclude issues with assignees from the working queue. Show them in the queue table as informational but don't process them.

Validate the queue before starting:

• At least 1 issue must be open and unassigned
• If all matching issues are assigned, report "All N matching issues are assigned — nothing to process" and stop
• If 0 issues match, report and stop — don't start an empty session
• Show the user the queue and get confirmation before entering the loop

## Work Queue ({N} issues, {M} skipped as assigned)

| # | Issue | Labels | Action |
|---|-------|--------|--------|
| 1 | #12 — Add retry logic to API client | enhancement | Implement |
| 2 | #15 — Add leaderboard system | complexity:high | Decompose → sub-issues |
| — | #16 — Refactor auth module | enhancement | Assigned to @user (skipped) |
| 3 | #18 — Add integration tests for auth flow | testing | Implement |

Start autonomous dev session?

Wait for user confirmation. This is the ONLY confirmation point — everything after runs autonomously.

After confirmation, create task list tracking:

For each issue in work queue:
  TaskCreate: "Issue #N — <title>" with status pending

Phase 0.5: Auto-Decompose High-Complexity Issues

When the queue contains issues that are too large to implement directly, decompose them into smaller, independently implementable sub-issues BEFORE entering the core loop.

For each high-complexity issue:

0. Check for prior decomposition — scan the issue's comments for an existing "Decomposed into #A, #B, #C" comment. If found, use those existing sub-issues instead of creating new ones.
1. Read the full issue body: gh issue view ${ISSUE_NUM} --json body,comments -q .
2. Understand the full scope — files involved, systems affected, testing needs
3. Break into 2-5 sub-issues, each low or medium complexity
4. Create sub-issues via gh issue create:

SUB_URL=$(gh issue create \
  --title "type(scope): Sub-task description" \
  --label "enhancement" \
  --body "$(cat <<'EOF'
## Summary

Specific sub-task description.

Part of #${ISSUE_NUM}

## Implementation Plan

- Files to modify: `src/path/to/file`
- Test strategy: Add tests for X behavior
- Approach: [specific implementation details]

## Acceptance Criteria

- [ ] Criterion 1
- [ ] Criterion 2
EOF
)")

SUB_NUM=$(basename "$SUB_URL")

5. Insert sub-issues at FRONT of queue (context is fresh from reading the parent)
6. Comment on parent issue: gh issue comment ${ISSUE_NUM} --body "Decomposed into #A, #B, #C — each independently implementable with TDD."
7. Parent stays open until all sub-issues merge — do NOT close it
8. After decomposition, if the total queue exceeds 15, truncate to 15 with a message: "Queue expanded to N issues after decomposition. Processing first 15."

Skip criteria — auto-skip these issues (log reason in progress table):

• Empty issue body or no identifiable acceptance criteria — needs requirements before implementation
• No code path (manual testing, design docs, decisions needed)
• Requires user input not present in the description
• Deployment/release tasks
• Issues labeled blocked or wontfix
• Issues requiring design decisions with multiple valid approaches not specified

If skipping, comment on the issue:

gh issue comment ${ISSUE_NUM} --body "Skipped during autonomous dev session — [reason]. Needs manual attention."

Phase 1: Sync Check (before EACH issue)

git checkout main
git pull origin main

Check for any PRs merged by the user since last check:

gh pr list --state merged --json number,headRefName,mergedAt --limit 20 \
  | jq --arg prefix "${BRANCH_PREFIX}" '[.[] | select(.headRefName | startswith($prefix))]'

Note any merged PRs in the progress table. If on a stale branch, switch back to main.

Check for existing branches/PRs from a previous session for the current issue:

# Check if issue already has a PR (search by title reference)
gh pr list --json number,title,headRefName,state --limit 50 \
  | jq --arg num "${ISSUE_NUM}" '[.[] | select(.title | contains("#" + $num))]'

# Also check by branch prefix
gh pr list --json number,title,headRefName,state --limit 50 \
  | jq --arg prefix "${BRANCH_PREFIX}" '[.[] | select(.headRef