Add Background Agent and Orchestrator patterns

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)

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