diff --git a/documents/patterns/background-agent.md b/documents/patterns/background-agent.md new file mode 100644 index 0000000..3288725 --- /dev/null +++ b/documents/patterns/background-agent.md @@ -0,0 +1,49 @@ +--- +authors: [nitsan_avni] +related_patterns: + - focused-agent + - orchestrator +--- + +# Background Agent + +## Pattern +Delegate standalone tasks to background agents running in parallel while you stay focused on main work. + +**Workflow:** +1. **Collect**: During main work, capture todos/ideas in markdown file (GTD-style) +2. **Identify**: Find tasks that are standalone, well-sized, clear enough to delegate +3. **Spawn**: Launch background agent per task (separate branch/context) +4. **Continue**: Stay focused on main thread while agents work in parallel +5. **Integrate**: Review and merge results when ready + +**What makes a task ready for background agent:** +- Standalone: doesn't block your current work +- Well-sized: clear scope, not too big +- Clear enough: agent can execute without constant guidance + +Human stays on main thread. Agent works asynchronously. + +## Example + +**Main work: Refactoring authentication flow** + +While working, you notice: +- Tests are missing for edge cases +- Documentation needs updating +- Dead code should be removed +- Logging format is inconsistent + +Collect these in `todo.md`. Each is standalone and clear. + +Spawn background agents: +- Agent 1: Add edge case tests (branch: `add-edge-tests`) +- Agent 2: Update auth docs (branch: `update-auth-docs`) +- Agent 3: Remove dead code (branch: `cleanup-dead-code`) + +You continue refactoring. Agents work in parallel on their branches. + +**Tools that enable this:** +- Claude Code GitHub app: runs agents in GitHub Actions, creates branches +- Multiple chat windows/sessions +- Separate working directories (git worktrees) diff --git a/documents/patterns/orchestrator.md b/documents/patterns/orchestrator.md new file mode 100644 index 0000000..76cf921 --- /dev/null +++ b/documents/patterns/orchestrator.md @@ -0,0 +1,54 @@ +--- +authors: [nitsan_avni] +related_patterns: + - focused-agent + - feedback-loop + - background-agent +--- + +# Orchestrator + +## Pattern +Dedicated agent that monitors background work, integrates changes, resolves conflicts, runs tests, updates main trunk. + +While background agents work on individual tasks, orchestrator handles integration work autonomously. + +**Workflow:** +1. **Monitor**: Track progress of background agents/branches +2. **Integrate**: Merge completed branches to main +3. **Resolve**: Handle merge conflicts +4. **Verify**: Run tests, check CI +5. **Update**: Keep main trunk healthy + +Orchestrator is a focused agent running in feedback loop - specialized for integration work. + +## Example + +**Orchestrator monitors 3 background agents:** + +``` +Orchestrator loop: +→ Check branch status (gh CLI) +→ Agent 1 done: merge add-edge-tests +→ Conflict in test file +→ Resolve conflict +→ Run tests +→ Tests pass +→ Agent 2 done: merge update-auth-docs +→ No conflicts +→ Agent 3 still working... +→ Wait and check again +``` + +**Why this works:** +- Focused agent: only handles integration (follows ground rules reliably) +- Feedback loop: autonomous checking and acting +- Runs locally: needs more privileges (git merge, push to main) + +**Collaboration with Background Agent:** +Background agents produce isolated changes. Orchestrator integrates them. Together they enable parallel work streams without blocking main thread. + +**Tools:** +- `gh` CLI for monitoring PR/branch status +- Git for merging and conflict resolution +- Test runners for verification