autonomous-dev

name	autonomous-dev
description	Use when given a doc, issue, or problem to analyze and implement autonomously. Triggers when user says "work on ENG-123", provides a doc/spec to implement, or wants autonomous development from analysis through to PRs.

Autonomous Dev

Takes input (doc, issue, spec) -> analyzes -> plans -> creates tickets -> spawns parallel sub-agents in separate iTerm tabs -> each sub-agent implements one ticket autonomously -> delivers PRs.

When to Use

• User provides a doc/spec/feedback to implement
• User says "work on ENG-123" or mentions a Linear issue
• User says "implement this", "build this", "work on this"

The Pipeline

INPUT (doc, issue, or description)
  |
  +- 1. READ -------- read the doc/issue (no exploration, no questions)
  |
  +- 2. ANALYZE ----- superpowers:brainstorming
  |                    Feed FULL content. Output: design doc
  |
  +- 3. PLAN -------- superpowers:writing-plans
  |                    Feed design. Output: numbered steps
  |
  +- 4. REVIEW ------ ONLY permission gate
  |                    Show proposed tickets to user for approval
  |                    User confirms -> create all tickets at once
  |
  +- 5. DISPATCH ---- parallel sub-agents (one per ticket)
  |     |
  |     +- For EACH ticket, open a new iTerm tab:
  |     |    +- git worktree (isolated workspace)
  |     |    +- claude session with ralph-loop
  |     |    +- autonomous until done -> PR with "Closes ENG-XXX"
  |     |
  |     +- All tabs run in PARALLEL
  |
  +- 6. DONE -------- report PR links

ONE permission gate: Step 4 (ticket review). Everything else runs without asking.

Step-by-Step Recipe

Step 1: READ -- Gather Input

Input Type	Action
A file path	Read the file
A Linear issue ID	linear issue view ENG-XXX --json --no-pager
A description in chat	Use it directly
An issue with linked doc	Fetch issue + read the linked doc

No exploration. No questions. Just read the input.

Step 2: ANALYZE -- Invoke Brainstorming

Invoke superpowers:brainstorming with the full input content.

Feed the ENTIRE doc/issue content. Do not summarize. Output is a design doc saved to docs/plans/.

Step 3: PLAN -- Invoke Writing Plans

Invoke superpowers:writing-plans with the design doc.

Output: numbered implementation steps. Each step must be:

• Independently deliverable (one branch, one PR)
• Testable on its own
• Clear enough for a sub-agent to implement without further context

Step 4: REVIEW -- The Only Permission Gate

Present the proposed tickets to the user:

Proposed tickets under ENG-XXX:

1. [Step title] -- [one-line description]
2. [Step title] -- [one-line description]
3. [Step title] -- [one-line description]

Create these tickets? (y/n)

On approval, create all tickets at once:

linear issue create --title "Step 1: ..." --description "..." --parent ENG-XXX --no-pager
linear issue create --title "Step 2: ..." --description "..." --parent ENG-XXX --no-pager
linear issue create --title "Step 3: ..." --description "..." --parent ENG-XXX --no-pager

If tickets already exist (like ENG-329, ENG-331): update their descriptions instead of creating duplicates.

Step 5: DISPATCH -- Parallel Sub-Agents in iTerm Tabs

This is the core automation. For EACH ticket:

5a. Create branch and worktree

linear issue start ENG-XXX
# Creates branch, e.g. "jeremy/eng-xxx-step-title"

git worktree add .claude/worktrees/eng-xxx <branch-name>

5b. Open new iTerm tab with Claude sub-agent

For each ticket, open a new iTerm tab running Claude Code in that worktree:

osascript -e '
tell application "iTerm2"
    tell current window
        set newTab to (create tab with default profile)
        tell current session of newTab
            write text "cd /path/to/repo/.claude/worktrees/eng-xxx && claude --print \"$(cat <<'\''PROMPT'\''
## Task: [TICKET TITLE]

### Context
[Ticket description and acceptance criteria from the plan]

### Parent Issue
[One-line summary of the overall problem]

### Standards
- TDD: Write tests FIRST, then implement
- Run pdm run pytest after each change
- Run pdm run pre-commit run --all-files before claiming done
- Run pdm run mypy src/ for type checking
- Follow project CLAUDE.md standards

### When Done
- All acceptance criteria met
- All tests passing, pre-commit passing, mypy passing
- Code committed
- Create PR with gh pr create --title \"...\" --body \"Closes ENG-XXX\"
PROMPT
)\""
        end tell
    end tell
end tell
'

5c. All tabs run in parallel

Each sub-agent:

• Works in its own worktree (isolated)
• Has its own branch (linked to Linear)
• Runs autonomously (ralph-loop or --print mode)
• Creates its own PR when done

The orchestrator (main session) just monitors.

Step 6: DONE

Report back:

• Which tickets got PRs (check with gh pr list)
• Links to each PR
• Any tickets that failed

Single-Ticket Mode

When the work fits in one PR, skip Steps 3-5 and go directly:

READ -> ANALYZE -> WORKTREE -> RALPH-LOOP -> PR

No sub-agents, no parallel tabs. Just one worktree, one loop, one PR.

Linear CLI Reference

Task	Command
List my issues	linear issue list --no-pager
View issue	linear issue view ENG-123 --json --no-pager
Start issue (creates branch)	linear issue start ENG-123
Create sub-ticket	linear issue create --title "..." --parent ENG-123 --no-pager
Create PR from issue	linear issue pr

Always use --no-pager.

Common Mistakes

• Summarizing the doc before feeding it to brainstorming (feed FULL content)
• Asking for permission at any step other than ticket review (Step 4)
• Running tickets sequentially instead of parallel sub-agents
• Creating worktree with -b when branch already exists from linear issue start
• Forgetting Closes ENG-XXX in PR description
• Not including parent issue context in sub-agent prompts