Initial commit

2025-11-29 18:00:36 +08:00
commit c83b4639c5
49 changed files with 18594 additions and 0 deletions
--- a/skills/multi-agent-composition/reference/core-4-framework.md
+++ b/skills/multi-agent-composition/reference/core-4-framework.md
@@ -0,0 +1,428 @@
+# The Core 4 Framework
+
+> "Keep track of the core four. If you understand the core 4 and how each element flows and controls your agent, you will understand compute and you'll understand how to scale your compute."
+
+The Core 4 Framework is the foundation of all agentic systems. Every agent—whether base, custom, or sub-agent—operates on these four pillars:
+
+1. **Context** - What information does the agent have?
+2. **Model** - What capabilities does the model provide?
+3. **Prompt** - What instruction are you giving?
+4. **Tools** - What actions can the agent take?
+
+## Why the Core 4 Matters
+
+**Understanding compute = Understanding the Core 4**
+
+When you analyze any agent configuration, isolate the Core 4:
+- How is context being managed?
+- Which model is selected and why?
+- What are the system prompts vs user prompts?
+- What tools are available?
+
+**Everything comes down to just four pieces. If you understand these, you will win.**
+
+## The Four Pillars in Detail
+
+### 1. Context - What Information Does the Agent Have?
+
+Context is the information available to your agent at any given moment.
+
+**Types of Context:**
+
+```text
+Static Context (always loaded):
+├── CLAUDE.md (global instructions)
+├── System prompt (agent definition)
+└── MCP servers (tool descriptions)
+
+Dynamic Context (accumulated during session):
+├── Conversation history
+├── File reads
+├── Tool execution results
+└── User prompts
+```
+
+**Context Management Strategies:**
+
+| Strategy | When to Use | Token Cost |
+|----------|-------------|------------|
+| Minimal CLAUDE.md | Always | 500-1k tokens |
+| Context priming | Task-specific setup | 2-5k tokens |
+| Context bundles | Agent handoffs | 10-20k tokens |
+| Sub-agent delegation | Parallel work | Isolated per agent |
+
+**Key Principle:** A focused agent is a performant agent.
+
+**Anti-pattern:** Loading all context upfront regardless of relevance.
+
+### 2. Model - What Capabilities Does the Model Provide?
+
+The model determines intelligence, speed, and cost characteristics.
+
+**Model Selection:**
+
+```text
+Claude Opus:
+├── Use: Complex reasoning, large codebases, architectural decisions
+├── Cost: Highest
+└── Speed: Slower
+
+Claude Sonnet:
+├── Use: Balanced tasks, general development
+├── Cost: Medium
+└── Speed: Medium
+
+Claude Haiku:
+├── Use: Simple tasks, fast iteration, text transformation
+├── Cost: Lowest (pennies)
+└── Speed: Fastest
+```
+
+**Example: Echo Agent (Custom Agents)**
+```python
+model: "claude-3-haiku-20240307"  # Downgraded for simple text manipulation
+# Result: Much faster, much cheaper, still effective for the task
+```
+
+**Key Principle:** Match model capability to task complexity. Don't pay for Opus when Haiku will do.
+
+### 3. Prompt - What Instruction Are You Giving?
+
+Prompts are the fundamental unit of knowledge work and programming.
+
+**Critical Distinction: System Prompts vs User Prompts**
+
+```text
+System Prompts:
+├── Define agent identity and capabilities
+├── Loaded once at agent initialization
+├── Affect every user prompt that follows
+├── Used in: Custom agents, sub-agents
+└── Not visible in conversation history
+
+User Prompts:
+├── Request specific work from the agent
+├── Added to conversation history
+├── Build on system prompt foundation
+├── Used in: Interactive Claude Code sessions
+└── Visible in conversation history
+```
+
+**The Pong Agent Example:**
+
+```python
+# System prompt (3 lines):
+"You are a pong agent. Always respond exactly with 'pong'. That's it."
+
+# Result: No matter what user prompts ("hello", "summarize codebase", "what can you do?")
+# Agent always responds: "pong"
+```
+
+**Key Insight:** "As soon as you touch the system prompt, you change the product, you change the agent."
+
+**Information Flow in Multi-Agent Systems:**
+
+```text
+User Prompt → Primary Agent (System + User Prompts)
+                    ↓
+              Primary prompts Sub-Agent (System Prompt + Primary's instructions)
+                    ↓
+              Sub-Agent responds → Primary Agent (not to user!)
+                    ↓
+              Primary Agent → User
+```
+
+**Why this matters:** Sub-agents respond to your primary agent, not to you. This changes how you write sub-agent prompts.
+
+### 4. Tools - What Actions Can the Agent Take?
+
+Tools are the agent's ability to interact with the world.
+
+**Tool Sources:**
+
+```text
+Built-in Claude Code Tools:
+├── Read, Write, Edit files
+├── Bash commands
+├── Grep, Glob searches
+├── Git operations
+└── ~15 standard tools
+
+MCP Servers (External):
+├── APIs, databases, services
+├── Added via mcp.json
+└── Can consume 24k+ tokens if not managed
+
+Custom Tools (SDK):
+├── Built with @mcptool decorator
+├── Passed to create_sdk_mcp_server()
+└── Integrated with system prompt
+```
+
+**Example: Custom Echo Agent Tool**
+
+```python
+@mcptool(
+    name="text_transformer",
+    description="Transform text with reverse, uppercase, repeat operations"
+)
+def text_transformer(params: dict) -> dict:
+    text = params["text"]
+    operation = params["operation"]
+    # Do whatever you want inside your tool
+    return {"result": transformed_text}
+```
+
+**Key Principle:** Tools consume context. The `/context` command shows what's loaded—every tool takes space in your agent's mind.
+
+## The Core 4 in Different Agent Types
+
+### Base Claude Code Agent
+
+```text
+Context: CLAUDE.md + conversation history
+Model: User-selected (Opus/Sonnet/Haiku)
+Prompt: User prompts → system prompt
+Tools: All 15 built-in + loaded MCP servers
+```
+
+### Custom Agent (SDK)
+
+```text
+Context: Can be customized (override or extend)
+Model: Specified in options (can use Haiku for speed)
+Prompt: Custom system prompt (can override completely)
+Tools: Custom tools + optionally built-in tools
+```
+
+**Example:** The Pong agent completely overrides Claude Code's system prompt—it's no longer Claude Code, it's a custom agent.
+
+### Sub-Agent
+
+```text
+Context: Isolated context window (no history from primary)
+Model: Inherits from primary or can be specified
+Prompt: System prompt (in .md file) + primary agent's instructions
+Tools: Configurable (can restrict to subset)
+```
+
+**Key distinction:** Sub-agents have no context history. They only have what the primary agent prompts them with.
+
+## Information Flow Between Agents
+
+### Single Agent Flow
+
+```text
+User Prompt
+    ↓
+Primary Agent (Context + Model + Prompt + Tools)
+    ↓
+Response to User
+```
+
+### Multi-Agent Flow
+
+```text
+User Prompt
+    ↓
+Primary Agent
+    ├→ Sub-Agent 1 (isolated context)
+    ├→ Sub-Agent 2 (isolated context)
+    └→ Sub-Agent 3 (isolated context)
+    ↓
+Aggregates responses
+    ↓
+Response to User
+```
+
+**Critical Understanding:**
+- Your sub-agents respond to your primary agent, not to you
+- Each sub-agent has its own Core 4
+- You must track multiple sets of (Context, Model, Prompt, Tools)
+
+## Context Preservation vs Context Isolation
+
+### Context Preservation (Benefit)
+
+```text
+Primary Agent:
+├── Conversation history maintained
+├── Can reference previous work
+├── Builds on accumulated knowledge
+└── Uses client class in SDK for multi-turn conversations
+```
+
+### Context Isolation (Feature + Limitation)
+
+```text
+Sub-Agent:
+├── Fresh context window (no pollution from main conversation)
+├── Focused on single purpose
+├── Cannot access primary agent's full history
+└── Operates on what primary agent passes it
+```
+
+**The Trade-off:** Context isolation makes agents focused (good) but limits information flow (limitation).
+
+## The 12 Leverage Points of Agent Coding
+
+While the Core 4 are foundational, experienced engineers track 12 leverage points:
+
+1. **Context** (Core 4)
+2. **Model** (Core 4)
+3. **Prompt** (Core 4)
+4. **Tools** (Core 4)
+5. System prompt structure
+6. Tool permission management
+7. Context window monitoring
+8. Model selection per task
+9. Multi-agent orchestration
+10. Information flow design
+11. Debugging and observability
+12. Dependency coupling management
+
+**Key Principle:** "Whenever you see Claude Code options, isolate the Core 4. How will the Core 4 be managed given this setup?"
+
+## Practical Applications
+
+### Application 1: Choosing the Right Model
+
+```text
+Task: Simple text transformation
+Core 4 Analysis:
+├── Context: Minimal (just the text to transform)
+├── Model: Haiku (fast, cheap, sufficient)
+├── Prompt: Simple instruction ("reverse this text")
+└── Tools: Custom text_transformer tool
+
+Result: Pennies cost, sub-second response
+```
+
+### Application 2: Managing Context Explosion
+
+```text
+Problem: Primary agent context at 180k tokens
+Core 4 Analysis:
+├── Context: Too much accumulated history
+├── Model: Opus (expensive at high token count)
+├── Prompt: Gets diluted in massive context
+└── Tools: All 15 + 5 MCP servers (24k tokens)
+
+Solution: Delegate to sub-agents
+├── Context: Split work across 3 sub-agents (60k each)
+├── Model: Keep Opus only where needed
+├── Prompt: Focused sub-agent system prompts
+└── Tools: Restrict to relevant subset per agent
+
+Result: Work completed, context manageable
+```
+
+### Application 3: Custom Agent for Specialized Workflow
+
+```text
+Use Case: Plan-Build-Review-Ship task board
+Core 4 Design:
+├── Context: Task board state + file structure
+├── Model: Sonnet (balanced for coding + reasoning)
+├── Prompt: Custom system prompt defining PBRS workflow
+└── Tools: Built-in file ops + custom task board tools
+
+Implementation: SDK with custom system prompt and tools
+Result: Specialized agent that understands your specific workflow
+```
+
+## System Prompts vs User Prompts in Practice
+
+### The Confusion
+
+Many engineers treat sub-agent `.md` files as user prompts. **This is wrong.**
+
+```markdown
+# ❌ Wrong: Writing sub-agent prompt like a user prompt
+Please analyze this codebase and tell me what it does.
+```
+
+```markdown
+# ✅ Correct: Writing sub-agent prompt as system prompt
+Purpose: Analyze codebases and provide concise summaries
+
+When called, you will receive a user's request from the PRIMARY AGENT.
+Your job is to read relevant files and create a summary.
+
+Report Format:
+Respond to the PRIMARY AGENT (not the user) with:
+"Claude, tell the user: [your summary]"
+```
+
+### Why the Distinction Matters
+
+```text
+System Prompt:
+├── Defines WHO the agent is
+├── Loaded once (persistent)
+└── Affects all user interactions
+
+User Prompt:
+├── Defines WHAT work to do
+├── Changes with each interaction
+└── Builds on system prompt foundation
+```
+
+## Debugging with the Core 4
+
+When an agent misbehaves, audit the Core 4:
+
+```text
+1. Check Context:
+   └── Run /context to see what's loaded
+   └── Are unused MCP servers consuming tokens?
+
+2. Check Model:
+   └── Is Haiku trying to do Opus-level reasoning?
+   └── Is cost/speed appropriate for task?
+
+3. Check Prompt:
+   └── Is system prompt clear and focused?
+   └── Are sub-agents responding to primary, not user?
+
+4. Check Tools:
+   └── Run /all-tools to see available options
+   └── Are too many tools creating choice paralysis?
+```
+
+## Key Takeaways
+
+1. **Everything is Core 4** - Every agent configuration comes down to Context, Model, Prompt, Tools
+
+2. **System ≠ User** - System prompts define agent identity; user prompts define work requests
+
+3. **Information flows matter** - In multi-agent systems, understand who's talking to whom
+
+4. **Focused agents perform better** - Like engineers, agents work best with clear, bounded context
+
+5. **Model selection is strategic** - Don't overpay for Opus when Haiku will work
+
+6. **Tools consume context** - Every MCP server and tool takes space in the agent's mind
+
+7. **Context isolation is powerful** - Sub-agents get fresh starts, preventing context pollution
+
+## Source Attribution
+
+**Primary sources:**
+- Custom Agents transcript (Core 4 framework, system prompts, SDK usage)
+- Sub-Agents transcript (information flow, context preservation, multi-agent systems)
+
+**Key quotes:**
+- "Keep track of the core four. If you understand the core 4 and how each element flows and controls your agent, you will understand compute." (Custom Agents)
+- "Context, model, prompt, and specifically the flow of the context, model, and prompt between different agents." (Sub-Agents)
+
+## Related Documentation
+
+- [Progressive Disclosure](progressive-disclosure.md) - Managing context (Core 4 pillar #1)
+- [Architecture Reference](architecture.md) - How components use the Core 4
+- [Decision Framework](../patterns/decision-framework.md) - Choosing components based on Core 4 needs
+- [Context Window Protection](../patterns/context-window-protection.md) - Advanced context management
+
+---
+
+**Remember:** Context, Model, Prompt, Tools. Master these four, and you master Claude Code.