@bastani/atomic 0.7.17-1 → 0.8.0-0

package/dist/builtin/workflows/skills/workflow/references/context-engineering/multi-agent-patterns.md

@@ -0,0 +1,259 @@
+---
+name: multi-agent-patterns
+description: This skill should be used when the user asks to "design multi-agent system", "implement supervisor pattern", "create swarm architecture", "coordinate multiple agents", or mentions multi-agent patterns, context isolation, agent handoffs, sub-agents, or parallel agent execution. Part of the context engineering skill suite — also activates when the user mentions "context engineering" or "context-engineering" in the context of orchestrating context across multiple agents.
+metadata:
+  provider: atomic
+---
+
+# Multi-Agent Architecture Patterns
+
+Multi-agent architectures distribute work across multiple language model instances, each with its own context window. When designed well, this distribution enables capabilities beyond single-agent limits. When designed poorly, it introduces coordination overhead that negates benefits. The critical insight is that sub-agents exist primarily to isolate context, not to anthropomorphize role division.
+
+## When to Activate
+
+Activate this skill when:
+- Single-agent context limits constrain task complexity
+- Tasks decompose naturally into parallel subtasks
+- Different subtasks require different tool sets or system prompts
+- Building systems that must handle multiple domains simultaneously
+- Scaling agent capabilities beyond single-context limits
+- Designing production agent systems with multiple specialized components
+
+## Core Concepts
+
+Use multi-agent patterns when a single agent's context window cannot hold all task-relevant information. Context isolation is the primary benefit — each agent operates in a clean context without accumulated noise from other subtasks, preventing the telephone game problem where information degrades through repeated summarization.
+
+Choose among three dominant patterns based on coordination needs, not organizational metaphor:
+
+- **Supervisor/orchestrator** — Use for centralized control when tasks have clear decomposition and human oversight matters. A single coordinator delegates to specialists and synthesizes results.
+- **Peer-to-peer/swarm** — Use for flexible exploration when rigid planning is counterproductive. Any agent can transfer control to any other through explicit handoff mechanisms.
+- **Hierarchical** — Use for large-scale projects with layered abstraction (strategy, planning, execution). Each layer operates at a different level of detail with its own context structure.
+
+Design every multi-agent system around explicit coordination protocols, consensus mechanisms that resist sycophancy, and failure handling that prevents error propagation cascades.
+
+## Detailed Topics
+
+### Why Multi-Agent Architectures
+
+**The Context Bottleneck**
+Reach for multi-agent architectures when a single agent's context fills with accumulated history, retrieved documents, and tool outputs to the point where performance degrades. Recognize three degradation signals: the lost-in-middle effect (attention weakens for mid-context content), attention scarcity (too many competing items), and context poisoning (irrelevant content displaces useful content).
+
+Partition work across multiple context windows so each agent operates in a clean context focused on its subtask. Aggregate results at a coordination layer without any single context bearing the full burden.
+
+**The Token Economics Reality**
+Budget for substantially higher token costs. Production data shows multi-agent systems run at approximately 15x the token cost of a single-agent chat:
+
+| Architecture | Token Multiplier | Use Case |
+|--------------|------------------|----------|
+| Single agent chat | 1x baseline | Simple queries |
+| Single agent with tools | ~4x baseline | Tool-using tasks |
+| Multi-agent system | ~15x baseline | Complex research/coordination |
+
+Research on the BrowseComp evaluation found that three factors explain 95% of performance variance: token usage (80% of variance), number of tool calls, and model choice. This validates distributing work across agents with separate context windows to add capacity for parallel reasoning.
+
+Prioritize model selection alongside architecture design — upgrading to better models often provides larger performance gains than doubling token budgets. BrowseComp data shows that model quality improvements frequently outperform raw token increases. Treat model selection and multi-agent architecture as complementary strategies.
+
+**The Parallelization Argument**
+Assign parallelizable subtasks to dedicated agents with fresh contexts rather than processing them sequentially in a single agent. A research task requiring searches across multiple independent sources, analysis of different documents, or comparison of competing approaches benefits from parallel execution. Total real-world time approaches the duration of the longest subtask rather than the sum of all subtasks.
+
+**The Specialization Argument**
+Configure each agent with only the system prompt, tools, and context it needs for its specific subtask. A general-purpose agent must carry all possible configurations in context, diluting attention. Specialized agents carry only what they need, operating with lean context optimized for their domain. Route from a coordinator to specialized agents to achieve specialization without combinatorial explosion.
+
+### Architectural Patterns
+
+**Pattern 1: Supervisor/Orchestrator**
+Deploy a central agent that maintains global state and trajectory, decomposes user objectives into subtasks, and routes to appropriate workers.
+
+```
+User Query -> Supervisor -> [Specialist, Specialist, Specialist] -> Aggregation -> Final Output
+```
+
+Choose this pattern when: tasks have clear decomposition, coordination across domains is needed, or human oversight is important.
+
+Expect these trade-offs: strict workflow control and easier human-in-the-loop interventions, but the supervisor context becomes a bottleneck, supervisor failures cascade to all workers, and the "telephone game" problem emerges where supervisors paraphrase sub-agent responses incorrectly.
+
+**The Telephone Game Problem and Solution**
+Anticipate that supervisor architectures initially perform approximately 50% worse than optimized versions due to the telephone game problem (LangGraph benchmarks). Supervisors paraphrase sub-agent responses, losing fidelity with each pass.
+
+Fix this by implementing a `forward_message` tool that allows sub-agents to pass responses directly to users:
+
+```python
+def forward_message(message: str, to_user: bool = True):
+    """
+    Forward sub-agent response directly to user without supervisor synthesis.
+
+    Use when:
+    - Sub-agent response is final and complete
+    - Supervisor synthesis would lose important details
+    - Response format must be preserved exactly
+    """
+    if to_user:
+        return {"type": "direct_response", "content": message}
+    return {"type": "supervisor_input", "content": message}
+```
+
+Prefer swarm architectures over supervisors when sub-agents can respond directly to users, as this eliminates translation errors entirely.
+
+**Pattern 2: Peer-to-Peer/Swarm**
+Remove central control and allow agents to communicate directly based on predefined protocols. Any agent transfers control to any other through explicit handoff mechanisms.
+
+```python
+def transfer_to_agent_b():
+    return agent_b  # Handoff via function return
+
+agent_a = Agent(
+    name="Agent A",
+    functions=[transfer_to_agent_b]
+)
+```
+
+Choose this pattern when: tasks require flexible exploration, rigid planning is counterproductive, or requirements emerge dynamically and defy upfront decomposition.
+
+Expect these trade-offs: no single point of failure and effective breadth-first scaling, but coordination complexity increases with agent count, divergence risk rises without a central state keeper, and robust convergence constraints become essential.
+
+Define explicit handoff protocols with state passing. Ensure agents communicate their context needs to receiving agents.
+
+**Pattern 3: Hierarchical**
+Organize agents into layers of abstraction: strategy (goal definition), planning (task decomposition), and execution (atomic tasks).
+
+```
+Strategy Layer (Goal Definition) -> Planning Layer (Task Decomposition) -> Execution Layer (Atomic Tasks)
+```
+
+Choose this pattern when: projects have clear hierarchical structure, workflows involve management layers, or tasks require both high-level planning and detailed execution.
+
+Expect these trade-offs: clear separation of concerns and support for different context structures at different levels, but coordination overhead between layers, potential strategy-execution misalignment, and complex error propagation paths.
+
+### Context Isolation as Design Principle
+
+Treat context isolation as the primary purpose of multi-agent architectures. Each sub-agent should operate in a clean context window focused on its subtask without carrying accumulated context from other subtasks.
+
+**Isolation Mechanisms**
+Select the right isolation mechanism for each subtask:
+
+- **Full context delegation** — Share the planner's entire context with the sub-agent. Use for complex tasks where the sub-agent needs complete understanding. The sub-agent has its own tools and instructions but receives full context for its decisions. Note: this partially defeats the purpose of context isolation.
+- **Instruction passing** — Create instructions via function call; the sub-agent receives only what it needs. Use for simple, well-defined subtasks. Maintains isolation but limits sub-agent flexibility.
+- **File system memory** — Agents read and write to persistent storage. Use for complex tasks requiring shared state. The file system serves as the coordination mechanism, avoiding context bloat from shared state passing. Introduces latency and consistency challenges but scales better than message-passing.
+
+Choose based on task complexity, coordination needs, and acceptable latency. Default to instruction passing and escalate to file system memory when shared state is needed. Avoid full context delegation unless the subtask genuinely requires it.
+
+### Consensus and Coordination
+
+**The Voting Problem**
+Avoid simple majority voting — it treats hallucinations from weak models as equal to reasoning from strong models. Without intervention, multi-agent discussions devolve into consensus on false premises due to inherent bias toward agreement.
+
+**Weighted Voting**
+Weight agent votes by confidence or expertise. Agents with higher confidence or domain expertise should carry more weight in final decisions.
+
+**Debate Protocols**
+Structure agents to critique each other's outputs over multiple rounds. Adversarial critique often yields higher accuracy on complex reasoning than collaborative consensus. Guard against sycophantic convergence where agents agree to be agreeable rather than correct.
+
+**Trigger-Based Intervention**
+Monitor multi-agent interactions for behavioral markers. Activate stall triggers when discussions make no progress. Detect sycophancy triggers when agents mimic each other's answers without unique reasoning.
+
+### Framework Considerations
+
+Different frameworks implement these patterns with different philosophies. LangGraph uses graph-based state machines with explicit nodes and edges. AutoGen uses conversational/event-driven patterns with GroupChat. CrewAI uses role-based process flows with hierarchical crew structures.
+
+## Practical Guidance
+
+### Failure Modes and Mitigations
+
+**Failure: Supervisor Bottleneck**
+The supervisor accumulates context from all workers, becoming susceptible to saturation and degradation.
+
+Mitigate by constraining worker output schemas so workers return only distilled summaries. Use checkpointing to persist supervisor state without carrying full history in context.
+
+**Failure: Coordination Overhead**
+Agent communication consumes tokens and introduces latency. Complex coordination can negate parallelization benefits.
+
+Mitigate by minimizing communication through clear handoff protocols. Batch results where possible. Use asynchronous communication patterns. Measure whether multi-agent coordination actually saves time versus a single agent with a longer context.
+
+**Failure: Divergence**
+Agents pursuing different goals without central coordination drift from intended objectives.
+
+Mitigate by defining clear objective boundaries for each agent. Implement convergence checks that verify progress toward shared goals. Set time-to-live limits on agent execution to prevent unbounded exploration.
+
+**Failure: Error Propagation**
+Errors in one agent's output propagate to downstream agents that consume that output, compounding into increasingly wrong results.
+
+Mitigate by validating agent outputs before passing to consumers. Implement retry logic with circuit breakers. Use idempotent operations where possible. Consider adding a verification agent that cross-checks critical outputs before they enter the pipeline.
+
+## Examples
+
+**Example 1: Research Team Architecture**
+```text
+Supervisor
+├── Researcher (web search, document retrieval)
+├── Analyzer (data analysis, statistics)
+├── Fact-checker (verification, validation)
+└── Writer (report generation, formatting)
+```
+
+**Example 2: Handoff Protocol**
+```python
+def handle_customer_request(request):
+    if request.type == "billing":
+        return transfer_to(billing_agent)
+    elif request.type == "technical":
+        return transfer_to(technical_agent)
+    elif request.type == "sales":
+        return transfer_to(sales_agent)
+    else:
+        return handle_general(request)
+```
+
+## Guidelines
+
+1. Design for context isolation as the primary benefit of multi-agent systems
+2. Choose architecture pattern based on coordination needs, not organizational metaphor
+3. Implement explicit handoff protocols with state passing
+4. Use weighted voting or debate protocols for consensus
+5. Monitor for supervisor bottlenecks and implement checkpointing
+6. Validate outputs before passing between agents
+7. Set time-to-live limits to prevent infinite loops
+8. Test failure scenarios explicitly
+
+## Gotchas
+
+1. **Supervisor bottleneck scaling** — Supervisor context pressure grows non-linearly with worker count. At 5+ workers, the supervisor spends more tokens processing summaries than workers spend on actual tasks. Set a hard cap on workers per supervisor (3-5) and add a second supervisor tier rather than overloading one.
+2. **Token cost underestimation** — Multi-agent runs cost approximately 15x baseline. Teams consistently underbudget because they estimate per-agent costs without accounting for coordination overhead, retries, and consensus rounds. Budget for 15x and treat anything less as a bonus.
+3. **Sycophantic consensus** — Agents in debate patterns tend to converge on agreeable answers, not correct ones. LLMs have an inherent bias toward agreement. Counter this by assigning explicit adversarial roles and requiring agents to state disagreements before convergence is allowed.
+4. **Agent sprawl** — Adding more agents past 3-5 shows diminishing returns and increases coordination overhead. Each additional agent adds communication channels quadratically. Start with the minimum viable number of agents and add only when a clear context isolation benefit exists.
+5. **Telephone game in message-passing** — Information degrades through repeated summarization as it passes between agents. Each agent paraphrases and loses nuance. Use filesystem coordination instead of message-passing for state that multiple agents need to access faithfully.
+6. **Error propagation cascades** — One agent's hallucination becomes another agent's "fact." Downstream agents have no way to distinguish upstream hallucinations from genuine information. Add validation checkpoints between agents and never trust upstream output without verification.
+7. **Over-decomposition** — Splitting tasks too finely creates more coordination overhead than the task itself. A 10-step pipeline with 10 agents spends more tokens on handoffs than on actual work. Decompose only when subtasks genuinely benefit from separate contexts.
+8. **Missing shared state** — Agents operating without a shared filesystem or state store duplicate work, produce inconsistent outputs, and lose track of what has already been accomplished. Establish shared persistent storage before building multi-agent workflows.
+
+## Integration
+
+This skill builds on context-fundamentals and context-degradation. It connects to:
+
+- memory-systems - Shared state management across agents
+- tool-design - Tool specialization per agent
+- context-optimization - Context partitioning strategies
+
+## References
+
+Internal reference:
+- [Frameworks Reference](./references/frameworks.md) - Read when: implementing a specific multi-agent pattern in LangGraph, AutoGen, or CrewAI and needing framework-specific code examples
+
+Related skills in this collection:
+- context-fundamentals - Read when: needing to understand context window mechanics before designing agent partitioning
+- memory-systems - Read when: agents need to share state across context boundaries or persist information between runs
+- context-optimization - Read when: individual agent contexts are too large and need partitioning or compression strategies
+
+External resources:
+- [LangGraph Documentation](https://langchain-ai.github.io/langgraph/) - Read when: building graph-based multi-agent workflows with explicit state machines
+- [AutoGen Framework](https://microsoft.github.io/autogen/) - Read when: implementing conversational GroupChat patterns or event-driven agent coordination
+- [CrewAI Documentation](https://docs.crewai.com/) - Read when: designing role-based hierarchical agent processes
+- [Research on Multi-Agent Coordination](https://arxiv.org/abs/2308.00352) - Read when: needing academic grounding on multi-agent system theory and evaluation
+
+---
+
+## Skill Metadata
+
+**Created**: 2025-12-20
+**Last Updated**: 2026-03-17
+**Author**: Agent Skills for Context Engineering Contributors
+**Version**: 2.0.0

package/dist/builtin/workflows/skills/workflow/references/context-engineering/project-development.md

@@ -0,0 +1,293 @@
+---
+name: project-development
+description: This skill should be used when the user asks to "start an LLM project", "design batch pipeline", "evaluate task-model fit", "structure agent project", or mentions pipeline architecture, agent-assisted development, cost estimation, or choosing between LLM and traditional approaches. Part of the context engineering skill suite — also activates when the user mentions "context engineering" or "context-engineering" in the context of structuring LLM-powered project architectures.
+metadata:
+  provider: atomic
+---
+
+# Project Development Methodology
+
+This skill covers the principles for identifying tasks suited to LLM processing, designing effective project architectures, and iterating rapidly using agent-assisted development. The methodology applies whether building a batch processing pipeline, a multi-agent research system, or an interactive agent application.
+
+## When to Activate
+
+Activate this skill when:
+- Starting a new project that might benefit from LLM processing
+- Evaluating whether a task is well-suited for agents versus traditional code
+- Designing the architecture for an LLM-powered application
+- Planning a batch processing pipeline with structured outputs
+- Choosing between single-agent and multi-agent approaches
+- Estimating costs and timelines for LLM-heavy projects
+
+## Core Concepts
+
+### Task-Model Fit Recognition
+
+Evaluate task-model fit before writing any code, because building automation on a fundamentally mismatched task wastes days of effort. Run every proposed task through these two tables to decide proceed-or-stop.
+
+**Proceed when the task has these characteristics:**
+
+| Characteristic | Rationale |
+|----------------|-----------|
+| Synthesis across sources | LLMs combine information from multiple inputs better than rule-based alternatives |
+| Subjective judgment with rubrics | Grading, evaluation, and classification with criteria map naturally to language reasoning |
+| Natural language output | When the goal is human-readable text, LLMs deliver it natively |
+| Error tolerance | Individual failures do not break the overall system, so LLM non-determinism is acceptable |
+| Batch processing | No conversational state required between items, which keeps context clean |
+| Domain knowledge in training | The model already has relevant context, reducing prompt engineering overhead |
+
+**Stop when the task has these characteristics:**
+
+| Characteristic | Rationale |
+|----------------|-----------|
+| Precise computation | Math, counting, and exact algorithms are unreliable in language models |
+| Real-time requirements | LLM latency is too high for sub-second responses |
+| Perfect accuracy requirements | Hallucination risk makes 100% accuracy impossible |
+| Proprietary data dependence | The model lacks necessary context and cannot acquire it from prompts alone |
+| Sequential dependencies | Each step depends heavily on the previous result, compounding errors |
+| Deterministic output requirements | Same input must produce identical output, which LLMs cannot guarantee |
+
+### The Manual Prototype Step
+
+Always validate task-model fit with a manual test before investing in automation. Copy one representative input into the model interface, evaluate the output quality, and use the result to answer these questions:
+
+- Does the model have the knowledge required for this task?
+- Can the model produce output in the format needed?
+- What level of quality should be expected at scale?
+- Are there obvious failure modes to address?
+
+Do this because a failed manual prototype predicts a failed automated system, while a successful one provides both a quality baseline and a prompt-design template. The test takes minutes and prevents hours of wasted development.
+
+### Pipeline Architecture
+
+Structure LLM projects as staged pipelines because separation of deterministic and non-deterministic stages enables fast iteration and cost control. Design each stage to be:
+
+- **Discrete**: Clear boundaries between stages so each can be debugged independently
+- **Idempotent**: Re-running produces the same result, preventing duplicate work
+- **Cacheable**: Intermediate results persist to disk, avoiding expensive re-computation
+- **Independent**: Each stage can run separately, enabling selective re-execution
+
+**Use this canonical pipeline structure:**
+
+```
+acquire -> prepare -> process -> parse -> render
+```
+
+1. **Acquire**: Fetch raw data from sources (APIs, files, databases)
+2. **Prepare**: Transform data into prompt format
+3. **Process**: Execute LLM calls (the expensive, non-deterministic step)
+4. **Parse**: Extract structured data from LLM outputs
+5. **Render**: Generate final outputs (reports, files, visualizations)
+
+Stages 1, 2, 4, and 5 are deterministic. Stage 3 is non-deterministic and expensive. Maintain this separation because it allows re-running the expensive LLM stage only when necessary, while iterating quickly on parsing and rendering.
+
+### File System as State Machine
+
+Use the file system to track pipeline state rather than databases or in-memory structures, because file existence provides natural idempotency and human-readable debugging.
+
+```
+data/{id}/
+  raw.json         # acquire stage complete
+  prompt.md        # prepare stage complete
+  response.md      # process stage complete
+  parsed.json      # parse stage complete
+```
+
+Check if an item needs processing by checking whether the output file exists. Re-run a stage by deleting its output file and downstream files. Debug by reading the intermediate files directly. This pattern works because each directory is independent, enabling simple parallelization and trivial caching.
+
+### Structured Output Design
+
+Design prompts for structured, parseable outputs because prompt design directly determines parsing reliability. Include these elements in every structured prompt:
+
+1. **Section markers**: Explicit headers or prefixes that parsers can match on
+2. **Format examples**: Show exactly what output should look like
+3. **Rationale disclosure**: State "I will be parsing this programmatically" so the model prioritizes format compliance
+4. **Constrained values**: Enumerated options, score ranges, and fixed formats
+
+Build parsers that handle LLM output variations gracefully, because LLMs do not follow instructions perfectly. Use regex patterns flexible enough for minor formatting variations, provide sensible defaults when sections are missing, and log parsing failures for review rather than crashing.
+
+### Agent-Assisted Development
+
+Use agent-capable models to accelerate development through rapid iteration: describe the project goal and constraints, let the agent generate initial implementation, test and iterate on specific failures, then refine prompts and architecture based on results.
+
+Adopt these practices because they keep agent output focused and high-quality:
+- Provide clear, specific requirements upfront to reduce revision cycles
+- Break large projects into discrete components so each can be validated independently
+- Test each component before moving to the next to catch failures early
+- Keep the agent focused on one task at a time to prevent context degradation
+
+### Cost and Scale Estimation
+
+Estimate LLM processing costs before starting, because token costs compound quickly at scale and late discovery of budget overruns forces costly rework. Use this formula:
+
+```
+Total cost = (items x tokens_per_item x price_per_token) + API overhead
+```
+
+For batch processing, estimate input tokens per item (prompt + context), estimate output tokens per item (typical response length), multiply by item count, and add 20-30% buffer for retries and failures.
+
+Track actual costs during development. If costs exceed estimates significantly, reduce context length through truncation, use smaller models for simpler items, cache and reuse partial results, or add parallel processing to reduce wall-clock time.
+
+## Detailed Topics
+
+### Choosing Single vs Multi-Agent Architecture
+
+Default to single-agent pipelines for batch processing with independent items, because they are simpler to manage, cheaper to run, and easier to debug. Escalate to multi-agent architectures only when one of these conditions holds:
+
+- Parallel exploration of different aspects is required
+- The task exceeds single context window capacity
+- Specialized sub-agents demonstrably improve quality on benchmarks
+
+Choose multi-agent for context isolation, not role anthropomorphization. Sub-agents get fresh context windows for focused subtasks, which prevents context degradation on long-running tasks.
+
+See `multi-agent-patterns` skill for detailed architecture guidance.
+
+### Architectural Reduction
+
+Start with minimal architecture and add complexity only when production evidence proves it necessary, because over-engineered scaffolding often constrains rather than enables model performance.
+
+Vercel's d0 agent achieved 100% success rate (up from 80%) by reducing from 17 specialized tools to 2 primitives: bash command execution and SQL. The file system agent pattern uses standard Unix utilities (grep, cat, find, ls) instead of custom exploration tools.
+
+**Reduce when:**
+- The data layer is well-documented and consistently structured
+- The model has sufficient reasoning capability
+- Specialized tools are constraining rather than enabling
+- More time is spent maintaining scaffolding than improving outcomes
+
+**Add complexity when:**
+- The underlying data is messy, inconsistent, or poorly documented
+- The domain requires specialized knowledge the model lacks
+- Safety constraints require limiting agent capabilities
+- Operations are truly complex and benefit from structured workflows
+
+See `tool-design` skill for detailed tool architecture guidance.
+
+### Iteration and Refactoring
+
+Plan for multiple architectural iterations from the start, because production agent systems at scale always require refactoring. Manus refactored their agent framework five times since launch. The Bitter Lesson suggests that structures added for current model limitations become constraints as models improve.
+
+Build for change by following these practices:
+- Keep architecture simple and unopinionated so refactoring is cheap
+- Test across model generations to verify the harness is not limiting performance
+- Design systems that benefit from model improvements rather than locking in limitations
+
+## Practical Guidance
+
+### Project Planning Template
+
+Follow this template in order, because each step validates assumptions before the next step invests effort.
+
+1. **Task Analysis**
+   - Define the input and desired output explicitly
+   - Classify: synthesis, generation, classification, or analysis
+   - Set an acceptable error rate based on business impact
+   - Estimate the value per successful completion to justify costs
+
+2. **Manual Validation**
+   - Test one representative example with the target model
+   - Evaluate output quality and format against requirements
+   - Identify failure modes that need parser hardening or prompt revision
+   - Estimate tokens per item for cost projection
+
+3. **Architecture Selection**
+   - Choose single pipeline vs multi-agent based on the criteria above
+   - Identify required tools and data sources
+   - Design storage and caching strategy using file-system state
+   - Plan parallelization approach for the process stage
+
+4. **Cost Estimation**
+   - Calculate items x tokens x price with a 20-30% buffer
+   - Estimate development time for each pipeline stage
+   - Identify infrastructure requirements (API keys, storage, compute)
+   - Project ongoing operational costs for production runs
+
+5. **Development Plan**
+   - Implement stage-by-stage, testing each before proceeding
+   - Define a testing strategy per stage with expected outputs
+   - Set iteration milestones tied to quality metrics
+   - Plan deployment approach with rollback capability
+
+## Examples
+
+**Example 1: Batch Analysis Pipeline (Karpathy's HN Time Capsule)**
+
+Task: Analyze 930 HN discussions from 10 years ago with hindsight grading.
+
+Architecture:
+- 5-stage pipeline: fetch -> prompt -> analyze -> parse -> render
+- File system state: data/{date}/{item_id}/ with stage output files
+- Structured output: 6 sections with explicit format requirements
+- Parallel execution: 15 workers for LLM calls
+
+Results: $58 total cost, ~1 hour execution, static HTML output.
+
+**Example 2: Architectural Reduction (Vercel d0)**
+
+Task: Text-to-SQL agent for internal analytics.
+
+Before: 17 specialized tools, 80% success rate, 274s average execution.
+
+After: 2 tools (bash + SQL), 100% success rate, 77s average execution.
+
+Key insight: The semantic layer was already good documentation. Claude just needed access to read files directly.
+
+See [Case Studies](./references/case-studies.md) for detailed analysis.
+
+## Guidelines
+
+1. Validate task-model fit with manual prototyping before building automation
+2. Structure pipelines as discrete, idempotent, cacheable stages
+3. Use the file system for state management and debugging
+4. Design prompts for structured, parseable outputs with explicit format examples
+5. Start with minimal architecture; add complexity only when proven necessary
+6. Estimate costs early and track throughout development
+7. Build robust parsers that handle LLM output variations
+8. Expect and plan for multiple architectural iterations
+9. Test whether scaffolding helps or constrains model performance
+10. Use agent-assisted development for rapid iteration on implementation
+
+## Gotchas
+
+1. **Skipping manual validation**: Building automation before verifying the model can do the task wastes significant time when the approach is fundamentally flawed. Always run one representative example through the model interface first.
+2. **Monolithic pipelines**: Combining all stages into one script makes debugging and iteration difficult. Separate stages with persistent intermediate outputs so each can be re-run independently.
+3. **Over-constraining the model**: Adding guardrails, pre-filtering, and validation logic that the model could handle on its own reduces performance. Test whether scaffolding helps or hurts before keeping it.
+4. **Ignoring costs until production**: Token costs compound quickly at scale. Estimate and track from the beginning to avoid budget surprises that force architectural rework.
+5. **Perfect parsing requirements**: Expecting LLMs to follow format instructions perfectly leads to brittle systems. Build robust parsers that handle variations and log failures for review.
+6. **Premature optimization**: Adding caching, parallelization, and optimization before the basic pipeline works correctly wastes effort on code that may be discarded during iteration.
+7. **Model version lock-in**: Building pipelines that only work with one specific model version creates fragile systems. Test across model generations and abstract the LLM call layer so models can be swapped without rewriting pipeline logic.
+8. **Evaluation-less deployment**: Shipping agent pipelines without measuring output quality means regressions go undetected. Define quality metrics during development and run evaluation checks before and after every model or prompt change.
+
+## Integration
+
+This skill connects to:
+- context-fundamentals - Understanding context constraints for prompt design
+- tool-design - Designing tools for agent systems within pipelines
+- multi-agent-patterns - When to use multi-agent versus single pipelines
+- evaluation - Evaluating pipeline outputs and agent performance
+- context-compression - Managing context when pipelines exceed limits
+
+## References
+
+Internal references:
+- [Case Studies](./references/case-studies.md) - Read when: evaluating architecture tradeoffs or reviewing real-world pipeline implementations (Karpathy HN Capsule, Vercel d0, Manus patterns)
+- [Pipeline Patterns](./references/pipeline-patterns.md) - Read when: designing a new pipeline stage layout, choosing caching strategies, or debugging stage boundaries
+
+Related skills in this collection:
+- tool-design - Tool architecture and reduction patterns
+- multi-agent-patterns - When to use multi-agent architectures
+- evaluation - Output evaluation frameworks
+
+External resources:
+- Karpathy's HN Time Capsule project: https://github.com/karpathy/hn-time-capsule
+- Vercel d0 architectural reduction: https://vercel.com/blog/we-removed-80-percent-of-our-agents-tools
+- Manus context engineering: Peak Ji's blog on context engineering lessons
+- Anthropic multi-agent research: How we built our multi-agent research system
+
+---
+
+## Skill Metadata
+
+**Created**: 2025-12-25
+**Last Updated**: 2026-03-17
+**Author**: Agent Skills for Context Engineering Contributors
+**Version**: 1.1.0