Development Philosophy

Autogit is built around trunk-based development — a workflow where all changes flow through short-lived feature branches into a single main branch. This approach is optimized for continuous integration, fast iteration, and multi-agent development.

Trunk-Based Development

main ─────●─────●─────●─────●─────●─────●─────
          ↑     ↑     ↑     ↑     ↑     ↑
         PR1   PR2   PR3   PR4   PR5   PR6

Core Principles

Principle	Description
Single main branch	All work merges to main — no long-lived develop or release branches
Short-lived branches	Feature branches live hours to days, not weeks
Small PRs	Each PR addresses one issue or feature
Continuous integration	Merge frequently to avoid drift

---

The Complete Workflow

Autogit connects the full development cycle from idea to merged PR:

With Triage Agent

For teams using the Triage Agent, issues flow through automatic categorization first:

Stage 1: Issue Triage

When an issue is created, the Triage Agent automatically:

1. Categorizes — Applies area labels (e.g., area:frontend, area:api)
2. Prioritizes — Sets priority in GitHub Projects (P0-P4)
3. Types — Sets issue type (Bug, Feature, Task)
4. Flags — Adds needs-human label if human intervention required

The needs-human label is the key decision point:

Label	Meaning	Next Step
No needs-human	Issue is clear and complete	AI agent can work autonomously
Has needs-human	Needs clarification or decisions	Human must provide input first

Stage 2: Branch + Draft PR

When work begins on an issue:

1. Create branch from issue — Press 8 on main with issue selected
2. Draft PR created — Links to issue, signals work started
3. Worktree created — Isolated workspace for this work

Draft PRs serve as “locks” — they signal to other agents and developers that someone is working on this issue.

Stage 3: Development

Work happens in the isolated worktree:

• AI agents or humans make changes
• Smart Commit (7) generates commit messages
• Changes push to the draft PR
• CI runs on each push

Stage 4: Ship

When work is complete:

1. Mark ready — Press 8 to mark PR ready for review
2. Review — Human or automated review
3. Merge — Squash or merge to main
4. Cleanup — Delete branch and worktree

---

Multi-Agent Development

The combination of trunk-based development + worktrees enables multiple AI agents to work in parallel:

How It Works

1. Triage identifies issues without needs-human — these are AI-ready
2. Each agent gets its own worktree and draft PR
3. Agents work in parallel — no file conflicts, no blocking
4. PRs merge independently — each is a small, focused change

The Role of needs-human

The needs-human label acts as a gate:

Issues flow through triage, get routed appropriately, and AI-ready issues can be picked up by autonomous agents.

---

Best Practices

Keep PRs Small

• One issue = one PR
• Easier to review
• Faster to merge
• Less conflict risk

Use Draft PRs

• Create draft PR immediately when starting work
• Signals to others that work is in progress
• Gets early CI feedback
• Mark ready only when truly ready for review

Merge Frequently

• Don’t let branches drift from main
• Rebase or merge main into feature branch if needed
• Smaller deltas = easier merges

Clean Up After Merge

• Delete merged branches
• Prune worktrees (Ctrl+Shift+P)
• Keep the workspace tidy

---

Keyboard Reference

Action	Key	Context
Create issue	6	Global
Create branch + draft PR from issue	8	On main with issue selected
Mark PR ready for review	8	On feature branch with draft PR
Smart Commit	7	Global
Create worktree	Ctrl+W	Worktrees panel
Prune worktrees	Ctrl+Shift+P	Worktrees panel

---

Further Reading

• Triage Agent — Automatic issue categorization
• PR Workflow — Detailed Smart PR behavior
• Worktrees — Parallel development setup
• Smart Commit — Automated commit messages