ouroboros-loops:branch

Ouroboros: Branch

Isolate large-scope tasks into separate git branches to prevent regressions in the main loop.

Overview

The branch skill sits between fix and enhance in the step sequence. It is invoked when state.json.branch_candidates is non-empty (populated by the analyze step). When no candidates exist, it passes through as a no-op.

When to Trigger

The analyze step should populate branch_candidates when any of these conditions are met for a finding:

Condition	Threshold
Files to be modified	>= 8
Estimated lines of change	>= 300
Cross-cutting concern keyword	architecture / redesign / migrate / restructure
New external dependency	any
Breaking API change	any
Finding modifies 3+ SKILL.md files simultaneously	yes

Procedure

0. Superpowers Gate

Check .ouroboros/config.json for the useSuperpowers field:

• Read config.json and inspect useSuperpowers
• If useSuperpowers is false or absent → skip Superpowers entirely for this step; proceed to step 1
• If useSuperpowers is true → check whether the superpowers:subagent-driven-development skill is available in the current session
  • If available: dispatch each branch task as a separate sub-agent task using TaskCreate
  • If NOT available: log [SUPERPOWERS UNAVAILABLE] subagent-driven-development skipped — plugin not loaded and continue with standard sequential execution

1. Read state.json

Read .ouroboros/state.json and check for:

• branch_candidates: list of strings describing large-scope tasks. If empty or absent, this step is a no-op — proceed directly to step 6 (Hand Off).
• branch_plans: existing branch plans from prior iterations. Check each for .done or .error markers.
• config.json approvalMode: determines execution mode (autonomous vs. review).

2. Check Existing Branch Plans

For each entry in branch_plans:

1. Check if .ouroboros/branch-plans/<slug>.done exists:
   • If yes: the branch agent completed successfully.
     • Run git merge --no-ff ouroboros/<slug> (autonomous mode) or note it for user review (review mode).
     • Move the corresponding branch_candidates entry to findings.enhancement_opportunities as [RESOLVED:branch-merged].
     • Update branch_plans entry status to "merged".
2. Check if .ouroboros/branch-plans/<slug>.error exists:
   • If yes: the branch agent failed.
     • Mark the corresponding finding as [DEFERRED:branch-failed] in state.json findings.
     • Update branch_plans entry status to "failed".
     • Log: [BRANCH FAILED] <slug> — background agent error. Finding deferred.
3. If neither marker exists and status is "in-progress":
   • Check if the PID is still alive (read PID from branch_plans entry).
   • If alive: skip this candidate (still running). Log: [BRANCH RUNNING] <slug> — PID <pid> still active.
   • If dead without .done or .error: write .error marker, treat as failed.

3. Process New Branch Candidates

For each entry in branch_candidates that does not already have a branch_plans entry:

3a. Generate slug

Create a short slug from the finding description (lowercase, hyphenated, max 40 chars). Example: "mcp/db.py: full async connection pool redesign (scope: 8+ files)" becomes "async-connection-pool-redesign".

3b. Write branch plan document

Create .ouroboros/branch-plans/<slug>.md:

# Branch Plan: <slug>

- created_at: YYYY-MM-DD
- iteration: N
- branch_name: ouroboros/<slug>
- status: pending
- trigger: <which trigger condition was met>

## Task Description
<One paragraph describing the large-scope task>

## Files in Scope
- <file1>: <what will change>
- <file2>: <what will change>

## Estimated Scope
- Files: N
- Estimated lines changed: ~N

## Agent Prompt
<The exact prompt to pass to Claude to execute this task on the feature branch>

## Completion Check
<How to verify the task is done>

## Merge Strategy
squash

Create the .ouroboros/branch-plans/ directory if it does not exist.

3c. Choose execution mode

Mode A — Background agent (approvalMode=autonomous, launcher supports --print)

1. Run scripts/detect-launcher.sh to detect the launcher type.
2. If LAUNCHER_TYPE != fallback:

   git checkout -b ouroboros/<slug>
   nohup claude --model <model> --print "<branch-skill prompt>" >> .ouroboros/<slug>.log 2>&1 &
   echo $! > .ouroboros/<slug>.pid
   git checkout master  # Return to main branch
   

   The prompt should instruct the agent to:
   • Read the branch plan document
   • Implement the changes described
   • Run any available tests
   • Commit with message [branch] <slug>: <summary>
   • Write .ouroboros/branch-plans/<slug>.done on success
   • Write .ouroboros/branch-plans/<slug>.error on failure
3. If LAUNCHER_TYPE == fallback (no suitable launcher): fall through to Mode B.

Mode B — User notification (approvalMode=review, or launcher unavailable)

Output a notification and defer the finding:

[BRANCH REQUIRED] Large-scope task detected: <description>
Branch plan written: .ouroboros/branch-plans/<slug>.md
To execute: git checkout -b ouroboros/<slug> && claude --print "<prompt>"
The main loop will pause this task until the branch is merged.

Mark the finding as [DEFERRED:branch-pending] in state.json findings. This prevents the deferred-stagnation mechanism from counting it.

3d. Record in state.json

Add to branch_plans in state.json:

{
  "branch_plans": [
    {
      "slug": "<slug>",
      "branch": "ouroboros/<slug>",
      "status": "in-progress",
      "pid": <pid or null>,
      "created_at": "YYYY-MM-DD",
      "iteration": N
    }
  ]
}

Remove the corresponding entry from branch_candidates (it has been promoted to a branch plan).

4. Git Safety Rules

• Never force-push — branch agents commit only on ouroboros/* branches.
• No auto-merge in review mode — wait for user confirmation.
• Auto-merge in autonomous mode — git merge --no-ff ouroboros/<slug> only after .done marker is confirmed.
• If a branch agent fails mid-execution, the .error marker ensures the main loop defers the finding without retrying it indefinitely.

5. Record Branch Activity

Append branch activity descriptions to current_iteration.enhancements in state.json (read current value first, then merge):

{
  "current_iteration": {
    "fixes": ["<preserve existing>"],
    "enhancements": ["skills/branch/SKILL.md: <description of branch activity>"]
  }
}

If current_iteration.fixes already contains entries, preserve them when writing back.

6. Hand Off

After processing all branch candidates (or if no-op), output a completion message. The agent (not this skill) is responsible for invoking ouroboros-loops:context-handoff next.

No-Op Behavior

When branch_candidates is empty or absent and no branch_plans are in progress, this step outputs:

[branch] No branch candidates. Passing through.

This is the normal case for most iterations. The step completes immediately without side effects.

context-handoff Mapping

completed_step	next_step
branch	enhance

Integration with loop-config.json

The branch step is inserted between fix and enhance in the step sequence:

{
  "stepSequence": ["research", "analyze", "fix", "branch", "enhance", "report", "evaluate", "determine"]
}

When branch is absent from stepSequence, the loop proceeds directly from fix to enhance as before — backward compatible.