From cd12dd34146c3af0d487b099bf3a9986246a120c Mon Sep 17 00:00:00 2001 From: Nitsan Avni Date: Sat, 11 Oct 2025 09:44:24 +0200 Subject: [PATCH 1/2] Add Background Agent and Orchestrator patterns MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **Background Agent**: Delegate standalone tasks to agents running in parallel on separate branches while staying focused on main work. GTD-style collection of todos, spawn agents for clear standalone tasks. **Orchestrator**: Dedicated agent monitoring background work, integrating changes, resolving conflicts, running tests. Focused agent in feedback loop specialized for integration. These patterns work together to enable parallel work streams without blocking main thread. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- documents/patterns/background-agent.md | 49 +++++++++++++++++++++++ documents/patterns/orchestrator.md | 54 ++++++++++++++++++++++++++ 2 files changed, 103 insertions(+) create mode 100644 documents/patterns/background-agent.md create mode 100644 documents/patterns/orchestrator.md diff --git a/documents/patterns/background-agent.md b/documents/patterns/background-agent.md new file mode 100644 index 0000000..e0cb397 --- /dev/null +++ b/documents/patterns/background-agent.md @@ -0,0 +1,49 @@ +--- +authors: [nitsanavni] +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..7f663b3 --- /dev/null +++ b/documents/patterns/orchestrator.md @@ -0,0 +1,54 @@ +--- +authors: [nitsanavni] +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 From 8e3a40f238a3ccf99421a84b394c5a99cf720095 Mon Sep 17 00:00:00 2001 From: Nitsan Avni Date: Sat, 11 Oct 2025 09:47:58 +0200 Subject: [PATCH 2/2] Update author IDs to nitsan_avni format --- documents/patterns/background-agent.md | 2 +- documents/patterns/orchestrator.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/documents/patterns/background-agent.md b/documents/patterns/background-agent.md index e0cb397..3288725 100644 --- a/documents/patterns/background-agent.md +++ b/documents/patterns/background-agent.md @@ -1,5 +1,5 @@ --- -authors: [nitsanavni] +authors: [nitsan_avni] related_patterns: - focused-agent - orchestrator diff --git a/documents/patterns/orchestrator.md b/documents/patterns/orchestrator.md index 7f663b3..76cf921 100644 --- a/documents/patterns/orchestrator.md +++ b/documents/patterns/orchestrator.md @@ -1,5 +1,5 @@ --- -authors: [nitsanavni] +authors: [nitsan_avni] related_patterns: - focused-agent - feedback-loop