store: Command + background agent pattern for context-dependent async work

graph/code-patterns/command-background-agent-pattern-for-context-dependent-async-9369e5.md

@@ -0,0 +1,48 @@
+---
+id: 9369e53e-123c-4102-b69d-2a4705f2388e
+type: code_pattern
+title: "Command + background agent pattern for context-dependent async work"
+tags: [claude-code, commands, agents, pattern, architecture]
+importance: 0.6
+confidence: 0.8
+created: "2026-02-19T22:09:59.147931+00:00"
+updated: "2026-02-19T22:09:59.147931+00:00"
+---
+
+Pattern for tasks needing conversation context but should run asynchronously.
+
+## Pattern Structure
+
+1. **Slash command** in `.claude/commands/` runs inline with full conversation context
+2. **Command analyzes context** and builds structured summary
+3. **Command spawns custom agent** from `.claude/agents/` in background via Task tool with `run_in_background=true`
+4. **Agent receives summary** as prompt and does heavy lifting
+5. **User gets control back** immediately
+
+## Workflow
+
+- Command has access to full conversation history → ideal for context analysis
+- Agent runs asynchronously → ideal for time-consuming operations
+- Structured summary bridges the two → cleanly separates concerns
+
+## Real-World Example
+
+`/save-memories` command:
+- Command analyzes conversation, finds duplicate cutoff, builds memory summary
+- Spawns memory-saver agent with summary
+- User can continue working while agent stores items
+
+## Implementation Notes
+
+- Newly created agents require a **session restart** to appear in the `subagent_type` list
+- Until then, use `subagent_type: general-purpose` as fallback
+- Agent receives summary via prompt, not conversation history
+- Task tool with `run_in_background=true` prevents blocking user
+
+## Applicable To
+
+Any task that:
+- Requires analyzing session/conversation context
+- Takes time to execute (network, storage, processing)
+- Should not block the user
+- Needs to defer execution to another agent