list-branches

name	list-branches
description	Use when user wants to inventory autonomy branches with custom sorting, grouping, or filtering
user-invocable	true

Listing Branches

Overview

Display inventory of all autonomy branches with user-specified sorting, grouping, and information display using computational analysis.

Core principle: Use branch-analyzer agent with Python scripts for precise analysis. Never "eyeball it".

When to Use

Use this skill when:

• User runs /list-branches command
• User wants to see all autonomy branches
• User wants custom sorting or grouping of branches
• User wants to filter branches by criteria

DO NOT use for:

• Analyzing single branch (use branch-status instead)
• Comparing two branches (use compare-branches instead)
• General iteration review on current branch (use review-progress instead)

Quick Reference

Step	Action	Tool
1. Parse query	Extract sorting/grouping/filter requirements	Manual
2. Dispatch agent	Send query to branch-analyzer	Task
3. Format results	Present markdown table to user	Direct output

Process

Step 1: Parse User Query

Extract requirements from user's query (if provided):

Default (no query):

• Sort by: most recent update (git log date)
• Grouping: none (flat list)
• Show: branch name, latest iteration, last update, status

Parse user query for:

• Sorting: "sort by [criterion]" → most recent, alphabetical, iteration count, status
• Grouping: "group by [field]" → status, date range, metric value
• Filtering: "show only [criteria]" → active, blocked, updated since date
• Information: "with [fields]" → metrics, blockers, next steps

Example queries:

"sort by most recent, show only active"
  → Sort: recency, Filter: status=active, Show: default fields

"group by status, show metrics"
  → Group: status, Sort: recency within groups, Show: + metrics

"show branches updated in last 30 days"
  → Filter: date > (today - 30 days), Sort: recency, Show: default

Step 2: Dispatch Branch-Analyzer Agent

Dispatch the branch-analyzer agent with detailed instructions:

Task tool with subagent_type: "autonomy:branch-analyzer"
Model: haiku
Prompt: "List all autonomy branches and analyze their status.

User query: [user's query or 'default: sort by most recent']

Requirements:
- Find all branches matching 'autonomy/*'
- For each branch, find most recent journal commit (starts with 'journal: ')
- Parse commit message for: status, metrics, blockers, next steps
- [Apply sorting: {criterion}]
- [Apply grouping: {field}]
- [Apply filtering: {criteria}]
- Generate Python script to process data
- Output markdown table with columns: [requested fields]

Use computational methods (Python scripts), do not eyeball the analysis."

Agent will:

1. Run git branch -a | grep 'autonomy/' to list all autonomy branches
2. For each branch, find most recent journal commit
3. Parse commit message metadata (Status, Metrics, Blockers, Next)
4. Generate Python script to sort/group/filter
5. Execute Python script
6. Return formatted markdown table

Step 3: Present Results

Display agent's output to user.

Example output format:

# Autonomy Branches

Showing 3 branches (sorted by most recent update)

| Branch | Latest Iteration | Last Updated | Status | Metrics | Next |
|--------|------------------|--------------|--------|---------|------|
| experiment-a | 0028 | 2026-01-02 | blocked | MRR: $62k (+12%) | Resolve Stripe API integration |
| experiment-b | 0015 | 2025-12-28 | active | Build: 3.2min (-40%) | Implement checkout flow |
| initial-strategy | 0042 | 2025-12-15 | concluded | Churn: 8% (from 13%) | Goal achieved |

If no autonomy branches found:

No autonomy branches found.

To create your first autonomy branch:
1. Run `/create-goal` to set up an open-ended goal
2. Run `/fork-iteration <strategy-name>` to create autonomy branch
3. Run `/start-iteration` to begin work

Important Notes

Only Autonomy Branches

This skill ONLY operates on autonomy/* branches:

• Filters for branches with autonomy/ prefix
• Will not show non-autonomy branches (e.g., main, develop)
• For general iteration review, user should use /review-progress

Computational Analysis Required

DO NOT:

• Manually count or sort branches
• "Eyeball" which branches are active
• Guess at groupings or filters

DO:

• Dispatch branch-analyzer agent
• Let agent generate Python scripts
• Use computational methods for precision

Flexible Query Parsing

User queries are free-text and flexible:

• Don't require exact syntax
• Interpret intent from natural language
• Ask via AskUserQuestion if query is ambiguous
• Default to sensible behavior if unclear

No Branch Checkout Required

All analysis happens via git commands:

• Never checkout branches
• Read commit messages via git log <branch>
• Branch-analyzer uses read-only operations

Common Mistakes

Mistake	Reality
"I'll manually list branches from git branch output"	NO. Dispatch branch-analyzer agent for computational analysis.
"Only 3 branches, I can eyeball the sorting"	NO. Always use Python scripts for precision.
"User query is unclear, I'll guess"	NO. Use AskUserQuestion to clarify if ambiguous.
"I'll check out each branch to read journals"	NO. Use git log to read commit messages without checkout.
"Non-autonomy branch appeared, I'll include it"	NO. Only autonomy/* branches. Strict filtering.

After Listing

Once branches are listed:

• Results displayed to user
• No files created or modified
• User can drill into specific branch with /branch-status <branch-name>
• User can fork from any listed iteration with /fork-iteration <iteration> <strategy-name>