wicked-garden 12.27.0

package/skills/agentic/agentic-patterns/refs/anti-patterns-operational.md

@@ -0,0 +1,216 @@
+---
+phase_relevance: ["design", "review"]
+archetype_relevance: ["*"]
+---
+# Anti-Patterns in Agentic Systems: Operational
+
+Operational anti-patterns including Sequential Bottleneck, Context Bloat, Redundant Agents, Hardcoded Prompts, and Missing Timeouts.
+
+## 6. Sequential Bottleneck
+
+### Description
+All work happens sequentially even when tasks are independent. Wastes time and resources through unnecessary serialization.
+
+### Symptoms
+- Total execution time is sum of all agent times
+- Agents sit idle waiting for others
+- No concurrent execution
+- Low resource utilization
+
+### Why It Happens
+- Sequential pattern is easiest to implement
+- Not identifying independent subtasks
+- Lack of async/parallel execution
+
+### How to Fix
+
+**Before:**
+```python
+# Sequential execution: 30 seconds total
+result1 = await agent1.process()  # 10 seconds
+result2 = await agent2.process()  # 10 seconds
+result3 = await agent3.process()  # 10 seconds
+```
+
+**After:**
+```python
+# Parallel execution: 10 seconds total
+results = await asyncio.gather(
+    agent1.process(),
+    agent2.process(),
+    agent3.process()
+)
+```
+
+### Prevention
+- Identify independent subtasks
+- Use asyncio.gather() or similar for parallel execution
+- Consider autonomous or collaborative patterns
+- Profile execution to find bottlenecks
+
+## 7. Context Bloat
+
+### Description
+Passing entire conversation history to every agent. Wasting tokens on irrelevant context. Slow and expensive.
+
+### Symptoms
+- Each agent receives 50k+ token context
+- Most context is irrelevant to agent's task
+- High costs and latency
+- Hitting context window limits
+
+### Why It Happens
+- "More context is better" assumption
+- Easy to pass everything vs. filtering
+- Not understanding what each agent needs
+
+### How to Fix
+
+**Before:**
+```python
+# Pass entire history to specialist
+await specialist.process(entire_conversation_history)
+```
+
+**After:**
+```python
+# Extract only relevant context
+relevant_context = self.extract_relevant_context(
+    full_history,
+    specialist.needs
+)
+await specialist.process(relevant_context)
+
+def extract_relevant_context(self, history, needs):
+    # Only include messages relevant to this specialist
+    return [
+        msg for msg in history
+        if self.is_relevant(msg, needs)
+    ]
+```
+
+### Prevention
+- Give each agent only what it needs
+- Compress or summarize old context
+- Use retrieval instead of passing everything
+- Implement context window budgets per agent
+
+## 8. Redundant Agents
+
+### Description
+Multiple agents doing the same thing. Wasted resources and complexity without benefit.
+
+### Symptoms
+- Two agents with identical tools and instructions
+- Same task being done multiple times
+- Agents overriding each other's work
+
+### How to Fix
+Consolidate into single agent or use agent pool:
+
+```python
+# Instead of redundant agents
+agent1 = Agent(tools=[code_review], instructions="Review code")
+agent2 = Agent(tools=[code_review], instructions="Review code")
+
+# Use single agent or agent pool
+review_agent = Agent(tools=[code_review], instructions="Review code")
+
+# Or if need concurrency, use pool of identical agents
+review_pool = AgentPool(
+    agent_factory=lambda: Agent(tools=[code_review], instructions="Review code"),
+    pool_size=3
+)
+```
+
+## 9. Hardcoded Prompts
+
+### Description
+System prompts and instructions baked into code. Hard to iterate, version, and A/B test.
+
+### Symptoms
+- Prompts scattered throughout codebase
+- Can't change prompts without code deployment
+- No version control for prompts
+- Can't A/B test prompt variations
+
+### How to Fix
+
+**Before:**
+```python
+class Agent:
+    def __init__(self):
+        self.prompt = "You are a helpful assistant that..."  # Hardcoded
+```
+
+**After:**
+```python
+# Externalize prompts
+class Agent:
+    def __init__(self, prompt_template_path):
+        self.template = self.load_template(prompt_template_path)
+
+    def load_template(self, path):
+        # Load from file, database, or config service
+        return Template.from_file(path)
+
+# Version control and manage prompts separately
+prompts/
+  agent-v1.txt
+  agent-v2.txt
+  agent-v3.txt
+```
+
+### Prevention
+- Store prompts in separate files or configuration
+- Version prompts alongside code
+- Use template systems for dynamic prompts
+- Enable runtime prompt updates
+
+## 10. Missing Timeouts
+
+### Description
+Agents can run forever. No time or resource limits. Can hang indefinitely or consume unlimited resources.
+
+### Symptoms
+- Agents occasionally never return
+- Resource exhaustion (memory, tokens, API quota)
+- No way to detect or recover from hangs
+
+### How to Fix
+
+```python
+class Agent:
+    def __init__(self, max_runtime=60, max_tokens=10000, max_iterations=10):
+        self.max_runtime = max_runtime
+        self.max_tokens = max_tokens
+        self.max_iterations = max_iterations
+
+    async def process(self, input):
+        # Time limit
+        timeout = asyncio.timeout(self.max_runtime)
+
+        async with timeout:
+            tokens_used = 0
+            iterations = 0
+
+            while not done:
+                # Iteration limit
+                iterations += 1
+                if iterations > self.max_iterations:
+                    raise MaxIterationsError()
+
+                result = await self.llm.generate(...)
+
+                # Token budget
+                tokens_used += result.tokens
+                if tokens_used > self.max_tokens:
+                    raise TokenBudgetExceededError()
+```
+
+### Prevention
+- Set timeouts on all async operations
+- Implement token budgets
+- Limit loop iterations
+- Add circuit breakers for external calls
+- Monitor resource usage

package/skills/agentic/agentic-patterns/refs/pattern-catalog.md

@@ -0,0 +1,329 @@
+---
+phase_relevance: ["design", "review"]
+archetype_relevance: ["*"]
+---
+# Pattern Catalog
+
+Detailed reference for agentic architecture patterns with implementation guidance.
+
+## Sequential Pattern
+
+### Description
+Agents execute in a fixed linear order. Each agent receives the output of the previous agent and produces input for the next agent. The simplest coordination pattern.
+
+### When to Use
+- Workflow has clear stages that must happen in order
+- Each stage depends on completion of previous stage
+- Task naturally decomposes into pipeline steps
+- Predictable, repeatable process
+
+### When NOT to Use
+- Stages are independent and could run in parallel
+- Need adaptive routing based on intermediate results
+- Any stage might need to loop back to previous stages
+
+### Implementation Example
+
+```python
+class SequentialPipeline:
+    def __init__(self, agents):
+        self.agents = agents
+
+    async def execute(self, initial_input):
+        current_output = initial_input
+        for agent in self.agents:
+            current_output = await agent.process(current_output)
+        return current_output
+
+# Usage
+pipeline = SequentialPipeline([
+    ResearchAgent(),
+    AnalysisAgent(),
+    DraftAgent(),
+    ReviewAgent()
+])
+result = await pipeline.execute({"topic": "AI Safety"})
+```
+
+### Variations
+- **With Checkpoints:** Save state after each agent for resume/replay
+- **With Validation:** Add validation gates between agents
+- **With Parallel Stages:** Allow some stages to fan out and merge back
+
+### Observability
+Track stage completion, duration, inter-stage data size, and failure points.
+
+## Hierarchical Pattern
+
+### Description
+A parent agent decomposes work and delegates to specialized child agents. Parent is responsible for task decomposition, delegation, and result aggregation.
+
+### When to Use
+- Complex task naturally decomposes into subtasks
+- Subtasks require different specializations
+- Need centralized coordination and monitoring
+- Want to scale by adding more specialized agents
+
+### When NOT to Use
+- Task is not decomposable
+- Overhead of delegation exceeds benefits
+- Need flat peer collaboration without hierarchy
+
+### Implementation Example
+
+```python
+class HierarchicalAgent:
+    def __init__(self, specialists):
+        self.specialists = specialists
+
+    async def execute(self, task):
+        # Parent agent plans decomposition
+        plan = await self.decompose_task(task)
+
+        # Delegate to specialists
+        subtask_results = []
+        for subtask in plan.subtasks:
+            specialist = self.specialists[subtask.type]
+            result = await specialist.execute(subtask)
+            subtask_results.append(result)
+
+        # Aggregate results
+        return await self.aggregate(subtask_results)
+
+    async def decompose_task(self, task):
+        # Parent agent reasons about task decomposition
+        prompt = f"""Break down this task into subtasks:
+        {task}
+
+        Available specialists: {list(self.specialists.keys())}
+        Return JSON plan."""
+        return await self.llm.generate(prompt)
+```
+
+### Variations
+Dynamic delegation (parent adapts on subtask results), multi-level hierarchy (specialists are themselves hierarchical), load balancing across specialist instances.
+
+### Common Pitfalls
+Deep nesting (>3 levels), parent micromanagement limiting specialist autonomy, parent becoming a bottleneck or single point of failure.
+
+## Collaborative Pattern
+
+### Description
+Multiple peer agents work together on a shared problem without fixed hierarchy. Agents contribute their perspectives and a consensus or synthesis mechanism combines results.
+
+### When to Use
+- Problem benefits from diverse expert viewpoints
+- No single agent has complete information
+- Quality improves with multiple perspectives (e.g., review, evaluation)
+- Need checks and balances
+
+### When NOT to Use
+- Clear hierarchy exists or is desirable
+- Problem has single correct answer
+- Coordination overhead exceeds benefits
+- Need fast, decisive action
+
+### Implementation Example
+
+```python
+class CollaborativeSystem:
+    def __init__(self, agents, consensus_fn):
+        self.agents = agents
+        self.consensus_fn = consensus_fn
+
+    async def solve(self, problem):
+        # All agents work on problem independently
+        proposals = []
+        for agent in self.agents:
+            proposal = await agent.propose_solution(problem)
+            proposals.append(proposal)
+
+        # Reach consensus
+        return await self.consensus_fn(proposals)
+
+# Consensus strategies
+async def voting_consensus(proposals):
+    # Simple majority vote
+    return max(set(proposals), key=proposals.count)
+
+async def synthesis_consensus(proposals):
+    # LLM synthesizes proposals into unified solution
+    prompt = f"""Given these expert proposals:
+    {proposals}
+
+    Synthesize the best elements into a unified solution."""
+    return await llm.generate(prompt)
+```
+
+### Variations
+- **With Debate:** Agents critique each other's proposals iteratively
+- **With Facilitator:** Add a non-voting facilitator agent to guide discussion
+- **Weighted Voting:** Different agents have different vote weights
+
+### Consensus Mechanisms
+Majority Vote (simple), Synthesis (rich but expensive), First-to-N (fast), Veto-Based (any agent blocks unsafe proposals).
+
+## Autonomous Pattern
+
+### Description
+Agents operate independently with minimal or no coordination. Each agent has its own goals and operates on its own schedule.
+
+### When to Use
+- Tasks are truly independent
+- Need maximum parallelism and throughput
+- Agents monitor different domains
+- Loose coupling is desired
+
+### When NOT to Use
+- Agents need to share information or coordinate
+- Tasks have dependencies
+- Need consistent global state
+- Resource contention is an issue
+
+### Implementation Example
+
+```python
+class AutonomousAgentPool:
+    def __init__(self, agents):
+        self.agents = agents
+
+    async def run(self):
+        # Launch all agents independently
+        tasks = [agent.run() for agent in self.agents]
+        await asyncio.gather(*tasks)
+
+# Each agent runs its own loop
+class MonitoringAgent:
+    async def run(self):
+        while True:
+            status = await self.check_service()
+            if status.is_unhealthy():
+                await self.alert(status)
+            await asyncio.sleep(self.interval)
+```
+
+### Coordination Patterns
+Even autonomous agents may need minimal coordination via shared event bus, shared state store, or rate limiting to stay under global limits.
+
+## Human-in-the-Loop Pattern
+
+### Description
+Agent execution includes explicit gates where a human approves, rejects, or modifies a proposed action before it takes effect. The human is part of the control loop, not just a downstream consumer. Human-in-the-Loop (HITL) sits naturally on top of any other pattern in this catalog — a workflow can have one HITL gate before a high-stakes step or many gates throughout.
+
+### When to Use
+- High-stakes decisions where an unreviewed agent action could cause material harm (sending external email, paying invoices, altering production state)
+- Regulatory or compliance regimes that require a human sign-off in the audit trail
+- Tasks where the agent's confidence is low and human judgment is the cheapest correction
+- Early deployment of a new agent capability — gates are a useful safety scaffold while trust is being built and metered down later
+
+### When NOT to Use
+- Hot-path or latency-sensitive workflows where pause-for-approval defeats the purpose
+- High-volume actions where the human review queue would saturate
+- Decisions that are reversible cheaply — an undo button is often a better trade-off than a gate
+- The human reviewer cannot meaningfully evaluate the proposed action (no context, no UI, no time)
+
+### Variations
+- **Pre-approval gate** — human approves before any side effect happens
+- **Post-execution review** — agent acts, human reviews and rolls back if needed (only when reversal is safe)
+- **Sampled review** — only every Nth action is gated; balances coverage vs throughput
+- **Risk-tiered gating** — low-risk actions auto-proceed, medium-risk get sampled review, high-risk always block on a human
+
+### Common Pitfalls
+Approval fatigue (humans rubber-stamp without reading), implicit bypass paths (the gate only fires on the happy path), no audit trail of who approved what, and gates that block without timeout (a missing reviewer halts the whole pipeline).
+
+## ReAct Pattern
+
+### Description
+Agent follows Reason → Act → Observe cycle. Agent reasons about what to do next, executes an action, observes the result, and repeats until task is complete.
+
+### When to Use
+- Environment is dynamic or partially observable
+- Need adaptive behavior based on feedback
+- Can't plan all steps upfront
+- Debugging, exploration, or research tasks
+
+### When NOT to Use
+- Environment is fully predictable
+- Planning overhead is too high
+- Need guaranteed completion time
+- Token budget is constrained
+
+### Implementation Example
+
+```python
+class ReActAgent:
+    async def solve(self, task):
+        context = {"task": task, "observations": []}
+
+        while not self.is_complete(context):
+            # Reason about next action
+            thought = await self.reason(context)
+
+            # Execute action
+            action = thought.action
+            result = await self.execute_action(action)
+
+            # Observe result
+            observation = self.observe(result)
+            context["observations"].append(observation)
+
+        return self.extract_answer(context)
+
+    async def reason(self, context):
+        prompt = f"""Task: {context['task']}
+
+        Previous observations:
+        {context['observations']}
+
+        What should I do next?
+        Think step-by-step, then specify an action."""
+        return await self.llm.generate(prompt)
+```
+
+### Variations
+- **With Memory:** Maintain long-term memory of successful strategies
+- **With Planning:** Create rough plan but adapt based on observations
+- **With Reflection:** Periodically reflect on strategy effectiveness
+
+## Plan-Execute Pattern
+
+### Description
+Agent creates a complete execution plan upfront, then executes all steps. Planning and execution are separate phases.
+
+### When to Use
+- Environment is predictable and stable
+- Planning cost is justified (complex dependencies, resource optimization)
+- Need to validate plan before execution
+
+### When NOT to Use
+- Environment changes during execution
+- Planning overhead exceeds execution savings
+- Need to start execution quickly
+
+### Planning Strategies
+- **Forward Planning:** Start from initial state, plan steps to goal
+- **Backward Planning:** Start from goal, plan steps back to initial state
+- **Hierarchical Planning:** Plan high-level strategy, then detailed tactics
+
+## Reflection Pattern
+
+### Description
+Agent reviews its own outputs and iteratively improves them through self-critique and refinement.
+
+### When to Use
+- Quality matters more than speed; initial output is expected to be imperfect
+- Cost of iteration is acceptable and clear quality criteria exist
+
+### When NOT to Use
+- Latency is critical, token budget is tight, or no clear improvement criteria
+
+### Variations
+- **With External Critic:** Separate critic agent reviews producer's output
+- **With Multiple Critics:** Different critics focus on different quality dimensions
+- **With Human Feedback:** Human reviews and guides refinement
+
+### Termination Conditions
+- **Fixed Iterations:** Stop after N iterations
+- **Quality Threshold:** Stop when quality score exceeds threshold
+- **Diminishing Returns:** Stop when improvements become marginal
+- **Token Budget:** Stop when token budget is exhausted

package/skills/agentic/context-engineering/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: context-engineering
+description: |
+  Context window management, token optimization, and memory patterns for efficient multi-agent systems.
+
+  Use when: optimizing token usage in an agentic pipeline, designing memory
+  scope for short / long-term / episodic state, or applying a context-loading
+  strategy (anticipatory / JIT / hybrid).
+portability: portable
+phase_relevance: ["design", "review"]
+archetype_relevance: ["*"]
+---
+
+# Context Engineering
+
+Techniques for managing context windows, optimizing token usage, and designing efficient memory systems for agentic applications.
+
+## Context Window Fundamentals
+
+**Context Window:** Maximum tokens an LLM can process in a single request (input + output).
+
+Limits vary by provider and model. Check the active model's documentation for
+the exact value.
+
+**Token Efficiency Matters:**
+- Cost: Charged per token (input + output)
+- Latency: More tokens = slower response
+- Quality: Irrelevant context can confuse model
+
+## State Management Patterns
+
+| Pattern | Use when | Pros | Cons |
+|---------|----------|------|------|
+| **Shared** | Agents need synchronized view | Consistency, simple coordination | Contention, single point of failure |
+| **Isolated** | Agents operate independently | No contention, parallel execution | Inconsistency possible, harder to coordinate |
+| **Checkpointed** | Long-running processes, need recovery | Fault tolerance, replayability | Storage overhead, consistency complexity |
+
+## Token Optimization Techniques
+
+### 1. Aggressive Summarization
+Compress old context into summaries to reduce token usage.
+
+### 2. Selective Context Loading
+Only load relevant context based on the current task.
+
+### 3. Structured Compression
+Use JSON/structured formats instead of prose to reduce tokens.
+
+**Example:**
+- Before: "The user's name is John Smith..." (verbose)
+- After: `{"name": "John Smith", ...}` (compact)
+
+### 4. Lazy Loading
+Load details only when explicitly needed.
+
+### 5. Reference Instead of Embedding
+Reference external documents instead of embedding full text.
+
+See `refs/selective-loading.md` and `refs/caching-and-optimization.md` for code examples and detailed strategies.
+
+## Memory Patterns
+
+| Memory | Scope | Size | Retention |
+|--------|-------|------|-----------|
+| **Short-term (working)** | Current session/task | 1K-10K tokens | Minutes to hours |
+| **Long-term** | Cross-session, permanent | Unbounded (vector DB) | Days to forever |
+| **Episodic** | Historical events | Summaries stored | Varies by importance |
+
+See `refs/compression-techniques.md` for implementation patterns.
+
+## Prompt Engineering for Agents
+
+### Role Definition
+Be specific about agent's role and boundaries.
+
+**Example:**
+```
+You are a Python code reviewer specializing in security.
+Your job is to identify security vulnerabilities.
+You do NOT review style or performance.
+```
+
+### Task Specification
+Clear, actionable instructions with explicit format.
+
+**Bad:** "Review this code."
+**Good:** "Review for security: 1) SQL injection 2) Input validation 3) Secrets. Output: JSON with vulnerabilities."
+
+### Format Control
+Specify exact output format to reduce tokens.
+
+### Few-Shot Examples
+Show examples for complex tasks.
+
+See `refs/selective-loading.md` for detailed prompting patterns.
+
+## Context Loading Strategies
+
+| Strategy | Pros | Cons |
+|----------|------|------|
+| **Anticipatory** | Faster response time (load before needed) | May load unnecessary data |
+| **Just-in-Time (JIT)** | Minimal token usage (load only when needed) | Latency on each request |
+| **Hybrid** | Balanced (core context + JIT for task-specific) | More complex implementation |
+
+## Cost Modeling
+
+### Token Cost Calculation
+Track input and output tokens separately. Rates vary by model (typically $0.003-0.075 per 1K tokens).
+
+### Budget Enforcement
+Set hard token limits per agent/session to prevent runaway costs.
+
+### Multi-Agent Cost Attribution
+Track costs per agent to identify expensive components.
+
+See `refs/cost-calculation-budget.md` and `refs/cost-optimization-reporting.md` for detailed cost strategies.
+
+## Context Window Strategies by Agent Pattern
+
+**Sequential Pattern:** Pass only output of previous agent, not entire chain.
+
+**Hierarchical Pattern:** Parent gets summaries from children, children get only relevant task context.
+
+**Collaborative Pattern:** Shared context (compressed), each agent adds only delta.
+
+**Autonomous Pattern:** Minimal shared context, isolated context per agent.
+
+## Quick Wins
+
+1. **Compress old messages:** Summarize history > 20 messages
+2. **Use structured outputs:** JSON instead of prose
+3. **Lazy load details:** Only when needed
+4. **Set token budgets:** Hard limits per agent/session
+5. **Monitor token usage:** Track and optimize high-cost agents
+
+## References
+
+- `refs/compression-techniques.md` - Conversation summarization, deduplication, entity compression
+- `refs/selective-loading.md` - Relevance filtering, time decay, token-budgeted retrieval
+- `refs/caching-and-optimization.md` - Prompt caching, semantic caching, batching, cost-aware model selection
+- `refs/cost-calculation-budget.md` - Token pricing, cost calculation, budget management
+- `refs/cost-optimization-reporting.md` - Cost estimation, optimization strategies, reporting