Decisions
- Pending: Branch naming convention — flat or nested?
- Pending: Squash commits per agent stage or preserve full history?
- Pending: Conflict resolution — auto-rebase, manual, or abort?
User Tasks
Summary
Automate the git workflow for coding agents: branch creation per FR, structured commits, PR creation via GitHub API, and merge management — so agents can deliver code changes end-to-end without manual git operations.
Problem / Motivation
Coding agents in the pipeline (FR-056) produce code changes in sandboxed worktrees (FR-055). But getting those changes from a worktree into a mergeable PR requires manual git operations:
- Creating a branch with the right name
- Committing with a meaningful message
- Pushing to the remote
- Creating a PR with description, labels, and linked FR
- Handling merge conflicts with main
- Cleaning up after merge
Without automation, every completed pipeline requires human intervention for git housekeeping. This blocks the “wake up to completed PRs” vision.
Proposed Solution
A src/opus/git/ module with:
- Branch Manager: Creates branches per FR with consistent naming, manages branch lifecycle.
- Commit Builder: Generates structured commit messages from agent context (FR title, phase, changes).
- PR Creator: Creates GitHub PRs via API with description generated from FR spec + changes.
- Merge Manager: Detects and resolves conflicts, manages merge after approval.
Open Questions
1. Branch Naming Convention
Question: What branch naming format should agents use?
| Option | Description |
|---|---|
A) Flat: opus/FR-058-llm-provider | Simple, readable, easy to filter with opus/ prefix |
B) Nested: opus/coder/FR-058-llm-provider | Includes agent role. More info but longer names |
C) Job-based: opus/job-12345 | Tied to job ID, not FR. Harder to associate with features |
Recommendation: Option A — flat with opus/ prefix is clean and filterable. The FR number already identifies the work.
Decision:
2. Commit Strategy
Question: Should agents squash commits per pipeline stage or preserve full history?
| Option | Description |
|---|---|
| A) One commit per stage | Planner: 1 commit, Coder: 1 commit, Fix: 1 commit. Clean but loses granularity |
| B) Squash on PR | Agents commit freely during work, squash to single commit on merge. Best of both |
| C) Preserve all commits | Full history of agent work. Noisy but complete audit trail |
Recommendation: Option B — agents commit as they work (useful for crash recovery), squash on merge keeps main history clean.
Decision:
3. Conflict Resolution
Question: How should agents handle merge conflicts with main?
| Option | Description |
|---|---|
| A) Auto-rebase and retry | Agent rebases on main, re-runs tests. Works for simple conflicts |
| B) Auto-rebase for simple, escalate complex | Try auto-rebase. If conflicts remain, escalate to human with conflict details |
| C) Always escalate | Any conflict goes to human. Safest but slowest |
Recommendation: Option B — most conflicts from concurrent agents are trivial (different files). Escalate only when auto-resolution fails.
Decision:
Phase Overview
| Phase | Description | Status |
|---|---|---|
| Phase 1 | Branch-per-FR creation, commit conventions, automatic staging | — |
| Phase 2 | PR creation via GitHub API | — |
| Phase 3 | Conflict detection, resolution, merge management | — |
Phase 1: Branch + Commit Automation —
Goal: Automate branch creation and structured commits for agent work.
| File / Feature | Details | Owner | Status |
|---|---|---|---|
src/opus/git/branch.py | BranchManager: create, checkout, push, delete branches. Naming convention enforcement | opus | — |
src/opus/git/commit.py | CommitBuilder: generate commit messages from agent context (FR ID, phase, summary) | opus | — |
src/opus/git/models.py | BranchInfo, CommitInfo dataclasses | opus | — |
| Branch naming | Convention: opus/FR-{id}-{slug} (e.g., opus/FR-058-llm-provider) | opus | — |
| Commit message format | [FR-{id}] {summary} with body containing phase and details | opus | — |
| Auto-staging | Stage all changes in worktree before commit (agent controls which files via sandbox) | opus | — |
| Unit tests | Branch creation, naming validation, commit message generation | mv | — |
Phase 2: PR Creation —
Goal: Automatically create GitHub PRs with rich descriptions generated from FR context.
| File / Feature | Details | Owner | Status |
|---|---|---|---|
src/opus/git/pr.py | PRCreator: create PR via GitHub API (using gh CLI or PyGithub) | opus | — |
| PR title | Format: [FR-{id}] {FR title} | opus | — |
| PR description | Auto-generated from: FR summary, phases completed, files changed, test results | mv | — |
| PR labels | Auto-label with opus-agent, FR priority, complexity tier | opus | — |
| FR linking | Reference FR file path and ID in PR description | opus | — |
| Draft PRs | Create as draft by default, mark ready-for-review after all checks pass | mv | — |
| Integration with FR-018 | Use GitHub integration (FR-018) for API access | opus | — |
| Integration tests | Create PR from test branch, verify description and labels | mv | — |
Phase 3: Conflict Resolution + Merge —
Goal: Handle merge conflicts and manage the merge lifecycle.
| File / Feature | Details | Owner | Status |
|---|---|---|---|
src/opus/git/merge.py | MergeManager: rebase on main, detect conflicts, attempt auto-resolution | opus | — |
| Conflict detection | Before PR creation: check if branch can be cleanly merged | opus | — |
| Auto-rebase | Rebase agent branch on latest main, re-run tests after rebase | mv | — |
| Complex conflict escalation | If auto-rebase fails: create PR with conflict markers, notify human | mv | — |
| Post-merge cleanup | Delete remote branch, clean up local worktree, update FR status | opus | — |
| Stale branch detection | Flag branches that haven’t been updated in > 24 hours | opus | — |
| Integration tests | Create conflicting branches, verify auto-rebase, verify escalation | mv | — |
Prerequisites / Gap Analysis
Requirements
| Requirement | Description |
|---|---|
| REQ-0 | Coding agency design doc reviewed and approved |
| REQ-1 | Python project scaffold (FR-009) — git module is Python code |
| REQ-2 | GitHub integration (FR-018) — API access for PR creation |
| REQ-3 | Sandboxed execution (FR-055) — git ops happen in worktrees |
Current State
| Component | Status | Details |
|---|---|---|
| Python scaffold | — | FR-009 not started |
| GitHub integration | in-progress | FR-018 Phase 1 done (repo + remote) |
| Git worktrees | — | FR-055 not started |
Gap (What’s missing?)
| Gap | Effort | Blocker? |
|---|---|---|
| Python scaffold (FR-009) | Med | Yes — code needs a home |
| GitHub API access (FR-018) | Low | Partially done — need PR creation API |
| Sandbox worktrees (FR-055) | Med | Yes — git ops happen in worktrees |
Test
Manual tests
| Test | Expected | Actual | Last |
|---|---|---|---|
| Complex conflict escalates to human | PR created with conflict note, human notified | pending | - |
AI-verified tests
| Scenario | Expected behavior | Verification method |
|---|---|---|
| … | … | … |
E2E tests
| Scenario | Assertion |
|---|---|
| … | … |
Integration tests
| Component | Coverage |
|---|---|
| … | … |
Unit tests
| Component | Tests | Coverage |
|---|---|---|
| … | … | … |
History
| Date | Event | Details |
|---|---|---|
| 2026-03-12 | Created | Part of autonomous coding agency architecture |
References
- FR-018 (GitHub Integration) — API access for PR operations
- FR-009 (Python Project Scaffold) — code infrastructure prerequisite
- FR-055 (Sandboxed Code Execution) — git operations happen in worktrees
- FR-056 (Autonomous Coding Orchestrator) — orchestrator triggers git workflow at pipeline end
- FR-057 (Code Review Pipeline) — review happens on the diff before PR creation
vault/00_system/designs/drafts/autonomous-coding-agency.md— architecture overview