wicked-garden 12.27.0

package/skills/agentic/frameworks/refs/migration-patterns-testing.md

@@ -0,0 +1,208 @@
+---
+phase_relevance: ["design", "review"]
+archetype_relevance: ["*"]
+---
+# Framework Migration Patterns: Testing, Rollback & Advanced Paths
+
+Migration testing strategy, rollback planning, advanced migration paths, effort estimates, and when not to migrate.
+
+## Advanced Migration Paths
+
+### 5. Python Framework -> ADK (TypeScript)
+
+**Scenario:** Migrating Python codebase to TypeScript.
+
+**Motivation:**
+- Team transitioning to TypeScript
+- Want ADK's production features
+- Building on Claude exclusively
+
+**Strategy:**
+
+**Step 1:** Port Agent Logic
+```python
+# Before: Python (any framework)
+class ReviewAgent:
+    def review(self, code):
+        return llm.generate(f"Review: {code}")
+
+# After: TypeScript (ADK)
+const reviewAgent = new Agent({
+    name: 'reviewer',
+    instructions: 'You review code.',
+    model: 'claude-opus-4-6'
+});
+```
+
+**Step 2:** Port Tools
+```python
+# Before: Python
+def analyze_code(code: str) -> dict:
+    return {"issues": [...]}
+
+# After: TypeScript
+const analyzeCodeTool = {
+    name: 'analyze_code',
+    description: 'Analyze code for issues',
+    parameters: {
+        type: 'object',
+        properties: {
+            code: { type: 'string' }
+        }
+    },
+    handler: async (params: { code: string }) => {
+        return { issues: [...] };
+    }
+};
+```
+
+**Gotchas:**
+- Async patterns differ (promises vs async/await)
+- Type systems differ
+- Tool definitions have different formats
+- Testing frameworks differ
+
+**Effort:** High (4-8 weeks for large codebase)
+
+### 6. Single-Provider -> Multi-Provider
+
+**Scenario:** Locked into one LLM provider, want flexibility.
+
+**Motivation:**
+- Want to A/B test providers
+- Cost optimization
+- Failover capability
+
+**Strategy:**
+
+**Step 1:** Abstract LLM Client
+```python
+# Before: Direct provider calls
+response = anthropic.messages.create(...)
+
+# After: Abstracted
+class LLMClient:
+    def generate(self, messages, model):
+        if model.startswith('claude'):
+            return self._call_anthropic(messages, model)
+        elif model.startswith('gpt'):
+            return self._call_openai(messages, model)
+```
+
+**Step 2:** Use Multi-Provider Framework
+```python
+# LangChain/LangGraph support multiple providers
+from langchain_anthropic import ChatAnthropic
+from langchain_openai import ChatOpenAI
+
+llm = ChatAnthropic(model="claude-opus-4")
+# Or
+llm = ChatOpenAI(model="gpt-4-turbo")
+```
+
+**Gotchas:**
+- Different providers have different features
+- Output formats may vary
+- Cost per token differs
+- Rate limits differ
+
+**Effort:** Low-Medium (1-2 weeks)
+
+## Migration Testing Strategy
+
+### 1. Equivalence Testing
+
+Run both old and new system in parallel, compare outputs:
+
+```python
+async def equivalence_test(input):
+    old_result = await old_agent.process(input)
+    new_result = await new_agent.process(input)
+
+    similarity = compare_outputs(old_result, new_result)
+    if similarity < 0.9:
+        log_discrepancy(input, old_result, new_result)
+
+    return similarity
+```
+
+### 2. Shadow Testing
+
+Route production traffic to both, use old result:
+
+```python
+async def shadow_process(input):
+    # Production (old)
+    result = await old_agent.process(input)
+
+    # Shadow (new) - don't await
+    asyncio.create_task(new_agent.process(input))
+
+    return result
+```
+
+### 3. Gradual Rollout
+
+Slowly increase traffic to new system:
+
+```python
+async def gradual_rollout(input, percentage=10):
+    if random.random() * 100 < percentage:
+        return await new_agent.process(input)
+    else:
+        return await old_agent.process(input)
+```
+
+## Rollback Planning
+
+Always have a rollback plan:
+
+1. **Feature Flags:** Quick disable of new system
+2. **Version Routing:** Route to old version instantly
+3. **Database Compatibility:** Ensure schemas compatible
+4. **Monitoring:** Alert on regressions immediately
+
+```python
+class FeatureFlag:
+    def __init__(self):
+        self.use_new_agent = False
+
+    async def process(self, input):
+        if self.use_new_agent:
+            return await new_agent.process(input)
+        else:
+            return await old_agent.process(input)
+```
+
+## Migration Effort Estimates
+
+| Migration Path | Typical Effort | Risk Level |
+|----------------|----------------|------------|
+| Custom -> Framework | 2-4 weeks | Medium |
+| LangChain -> LangGraph | 1-2 weeks | Low |
+| CrewAI -> LangGraph | 2-3 weeks | Medium |
+| AutoGen -> LangGraph | 3-4 weeks | Medium |
+| Python -> TypeScript (ADK) | 4-8 weeks | High |
+| Single -> Multi-Provider | 1-2 weeks | Low |
+
+## Post-Migration Checklist
+
+- [ ] All tests passing
+- [ ] Equivalence testing shows >95% similarity
+- [ ] Performance metrics maintained or improved
+- [ ] Cost per request unchanged or improved
+- [ ] Monitoring and alerting migrated
+- [ ] Documentation updated
+- [ ] Team trained on new framework
+- [ ] Old code removed or archived
+- [ ] Rollback plan tested
+
+## When NOT to Migrate
+
+Don't migrate if:
+- Current system is stable and meets needs
+- Migration cost exceeds benefits
+- Team lacks expertise in target framework
+- No clear improvement in capabilities
+- Close to sunsetting the product
+- Migration would delay critical features

package/skills/agentic/refs/audit.md

@@ -0,0 +1,134 @@
+# agentic:audit — 8-Layer Trust & Safety Audit Rubric
+
+Full rubric sourced from `agents/agentic/safety-reviewer.md` and
+`skills/agentic/trust-and-safety/`. Apply every layer to the target codebase.
+
+## Layer 1: Tool Risk Classification
+
+Inventory every tool the agent can invoke. For each, classify:
+- **Capability**: read-only | side-effecting | destructive | external-comms
+- **Scope**: local | cross-agent | external-system
+- **Reversibility**: reversible | irreversible
+
+Tag CRITICAL if destructive + irreversible (e.g. delete, payment, email-send).
+
+## Layer 2: HITL Gate Verification
+
+Check that every CRITICAL/HIGH-risk tool has a human-in-the-loop gate:
+
+- [ ] Gate trigger is explicit (confidence < threshold OR action in CRITICAL_ACTIONS)
+- [ ] Approval workflow exists (sync or async) with defined timeout
+- [ ] Fallback on no-response is deny (fail-safe), not allow
+- [ ] Reviewer decisions are tracked with audit trail
+
+Patterns (from `refs/guardrails-actions.md`):
+```python
+async def execute_with_approval(action, threshold=0.8):
+    if action.confidence < threshold or action.is_high_stakes():
+        approval = await request_human_approval(action)
+        if not approval.approved:
+            raise ApprovalDenied(approval.reason)
+    return await action.execute()
+```
+
+## Layer 3: PII Handling
+
+Search for PII patterns in inputs, outputs, and logs:
+
+```bash
+grep -r "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+" --include="*.log" .
+grep -r "\b\d{3}-\d{2}-\d{4}\b" .          # SSN
+grep -r "\b\d{4}[- ]?\d{4}[- ]?\d{4}" .    # CC
+```
+
+Checklist:
+- [ ] PII detection at entry points
+- [ ] PII redacted in logs and outputs (`[REDACTED_EMAIL]`, etc.)
+- [ ] No PII in plaintext storage
+- [ ] Retention policy defined
+
+## Layer 4: Prompt Injection Defense
+
+Direct injection — check for unvalidated string concatenation:
+
+```bash
+grep -r "f\"{.*user.*}\"" --include="*.py" .
+grep -r "prompt + user_input" .
+```
+
+Indirect injection — check for untrusted external content included in prompts
+(URL fetches, RAG documents, search results).
+
+Checklist:
+- [ ] Clear delimiters separate system / user content
+- [ ] Injection patterns detected and blocked
+- [ ] External content sanitized before prompt inclusion
+
+## Layer 5: AuthN / AuthZ
+
+- [ ] Agents use least-privilege credentials
+- [ ] Tool access is role-gated (not open to all agents)
+- [ ] Credentials are not logged or exposed in error messages
+
+## Layer 6: Rate Limits & Quotas
+
+- [ ] Per-user and per-session quotas defined
+- [ ] Circuit breaker opens after N failures
+- [ ] Rate limit headers / retry-after respected when calling external APIs
+
+## Layer 7: Observability
+
+- [ ] All agent actions logged with structured fields (action, user_id, params, result)
+- [ ] Audit log is append-only and tamper-evident
+- [ ] Monitoring alerts on CRITICAL findings or anomalous action rates
+
+## Layer 8: Failure Modes
+
+- [ ] Errors fail toward safety (deny by default)
+- [ ] No bare `except Exception: pass` swallowing errors silently
+- [ ] External API failures produce a safe fallback response (not a crash)
+- [ ] Kill switch exists to halt all operations + alert admins
+
+## Compliance Extensions
+
+When `--standard` is given, append the matching checklist:
+
+| Standard | Layer emphasis |
+|----------|---------------|
+| GDPR | Layer 3 (PII) + retention + right-to-erasure |
+| HIPAA | Layer 3 PHI encryption at rest + in transit |
+| SOC 2 | Layers 5, 6, 7 (access control, rate limits, audit) |
+| NIST AI RMF | All 8 layers with severity scoring |
+
+## Output Format
+
+```markdown
+## Trust & Safety Audit: {Project}
+
+**Date**: {date} | **Standard**: {standard or none} | **Risk Level**: {CRITICAL|HIGH|MEDIUM|LOW}
+
+### Risk Profile
+
+| Layer | Status | Critical | High | Medium | Low |
+|-------|--------|----------|------|--------|-----|
+| Tool Risk | {PASS/FAIL} | … | … | … | … |
+| HITL Gates | {PASS/FAIL} | … | … | … | … |
+| PII Handling | {PASS/FAIL} | … | … | … | … |
+| Prompt Injection | {PASS/FAIL} | … | … | … | … |
+| AuthN/AuthZ | {PASS/FAIL} | … | … | … | … |
+| Rate Limits | {PASS/FAIL} | … | … | … | … |
+| Observability | {PASS/FAIL} | … | … | … | … |
+| Failure Modes | {PASS/FAIL} | … | … | … | … |
+
+### Findings (CRITICAL and HIGH only — list all)
+
+**CRITICAL**: {file:line} — {description} — Fix: {specific action}
+
+### Remediation Roadmap
+
+P0 (fix immediately): …
+P1 (before production): …
+P2 (next sprint): …
+```
+
+When `--scenarios` is set, emit a `wicked-scenarios` block for each CRITICAL/HIGH finding.

package/skills/agentic/refs/design.md

@@ -0,0 +1,137 @@
+# agentic:design — Interactive Agentic Architecture Design Rubric
+
+Full rubric sourced from `agents/agentic/architect.md` and
+`skills/agentic/agentic-patterns/`. Use for greenfield agentic system design.
+
+## Phase 1: Requirements Gathering
+
+If no problem statement is supplied, ask 3–5 clarifying questions:
+
+1. What is the primary task the agentic system must accomplish?
+2. What tools / APIs / external systems must it interact with?
+3. What are the concurrency and latency requirements?
+4. What safety constraints apply (PII, HITL, compliance)?
+5. What framework preferences or constraints exist?
+
+## Phase 2: Pattern Selection
+
+Pick from the agentic pattern catalog (`skills/agentic/agentic-patterns/refs/pattern-catalog.md`):
+
+| Pattern | Use when |
+|---------|---------|
+| Scatter-Gather | Independent parallel lookups → aggregate |
+| Pipeline | Sequential stages, each depending on prior |
+| Router | Different input types → specialized agents |
+| Retry with Fallback | Transient failures expected |
+| Orchestrator / Subagents | Complex delegation with state |
+| Event-Driven | Decoupled, reactive workflows |
+
+## Phase 3: Five-Layer Architecture
+
+Render a five-layer breakdown for the proposed system:
+
+### Layer 1: Cognition
+- Agent roles and single-responsibility assignments
+- Reasoning pattern (ReAct, CoT, plan-and-execute)
+- Task decomposition strategy
+- Prompt versioning approach
+
+### Layer 2: Context
+- Memory scope (global vs. agent-local)
+- State checkpointing strategy
+- Context window budget (see `skills/agentic/context-engineering/`)
+- Cleanup / archival policy
+
+### Layer 3: Interaction
+- Tool inventory with capability + risk classification
+- External API contracts
+- Multi-agent communication protocol
+- Graceful degradation for tool failures
+
+### Layer 4: Runtime
+- Orchestration pattern (sequential | parallel | dynamic)
+- Error handling and retry logic
+- Resource quotas (max turns, max tokens, timeouts)
+- Observability (structured logging, tracing, metrics)
+
+### Layer 5: Governance
+- Input / output validation points
+- HITL gate placement (use Layer 3 tool risk to position)
+- Audit logging requirements
+- Compliance constraints
+
+## Phase 4: Safety Section
+
+Apply the 8-layer trust-and-safety checklist from `skills/agentic/refs/audit.md`
+to the proposed architecture. For a design review, focus on:
+
+- Tool risk classification (Layer 1 of audit)
+- HITL gate placement (Layer 2 of audit)
+- PII touchpoints (Layer 3 of audit)
+- Prompt injection exposure (Layer 4 of audit)
+- Failure mode defaults (Layer 8 of audit)
+
+## Phase 5: Framework Recommendation
+
+Using `skills/agentic/frameworks/SKILL.md` decision tree:
+
+| Requirement | Recommended framework |
+|-------------|----------------------|
+| Complex state + loops | LangGraph |
+| Role-based team | CrewAI or ADK |
+| RAG-heavy | LlamaIndex Agents |
+| TypeScript / Claude-only | Anthropic ADK |
+| Type-safe Python | Pydantic AI |
+| Multi-agent conversation | AutoGen |
+
+## Output Format
+
+```markdown
+## Agentic Architecture Design: {System Name}
+
+**Date**: {date} | **Pattern**: {chosen pattern} | **Framework**: {recommendation}
+
+### Problem Statement
+
+{refined from clarifying questions}
+
+### Five-Layer Architecture
+
+#### Layer 1: Cognition
+{agent roster, roles, reasoning patterns}
+
+#### Layer 2: Context
+{memory strategy, state, checkpointing}
+
+#### Layer 3: Interaction
+{tool inventory with risk tier, API contracts}
+
+#### Layer 4: Runtime
+{orchestration, error handling, resource limits, observability}
+
+#### Layer 5: Governance
+{HITL gates, validation points, audit, compliance}
+
+### Architecture Diagram
+
+```mermaid
+graph TB
+    User --> Orchestrator
+    Orchestrator --> AgentA & AgentB
+    AgentA --> ToolX
+    AgentB --> ToolY
+```
+
+### Safety Validation
+
+{8-layer safety checklist results — flag any CRITICAL/HIGH risks}
+
+### Next Steps
+
+1. {critical action}
+2. {high action}
+3. {medium action}
+
+→ Use `agentic:review` to assess once code is written.
+→ Use `agentic:audit` for compliance-grade evidence before production.
+```

package/skills/agentic/refs/frameworks.md

@@ -0,0 +1,102 @@
+# agentic:frameworks — Framework Selection / Comparison Rubric
+
+Full rubric sourced from `agents/agentic/framework-researcher.md` and
+`skills/agentic/frameworks/SKILL.md`. Use for framework selection, comparison,
+or the interactive wizard. Always use WebSearch for latest 2026 ecosystem state.
+
+## Mode Detection
+
+| Args | Mode |
+|------|------|
+| `--compare fw1,fw2,...` | Side-by-side comparison table |
+| `--language` / `--use-case` only | Filtered selection guide |
+| No args | Interactive 5-question wizard |
+
+## Wizard (no args)
+
+Ask in order (do not batch):
+
+1. What is the primary task? (RAG, stateful workflows, role-based team, conversational, pipeline)
+2. What language/runtime? (Python, TypeScript, C#, any)
+3. What's the team's experience level? (beginner, intermediate, expert)
+4. What are the production constraints? (cloud vendor, compliance, existing infra)
+5. What is the expected scale? (prototype, small prod, high-volume)
+
+Use answers to pick from the decision tree below.
+
+## Decision Tree
+
+```
+Primary use case?
+├─ Complex stateful workflow with branches/loops → LangGraph
+├─ Role-based team of agents → CrewAI or ADK
+├─ RAG-heavy application → LlamaIndex Agents
+├─ Multi-agent conversations/debates → AutoGen
+├─ Simple sequential — TypeScript → ADK
+├─ Simple sequential — Python → Pydantic AI or LangChain
+├─ Production pipeline → Haystack or ADK
+└─ Maximum flexibility → LangGraph or build from scratch
+```
+
+## Comparison Table (current as of 2026 — verify with WebSearch)
+
+| Feature | LangGraph | CrewAI | AutoGen | ADK | Pydantic AI |
+|---------|-----------|--------|---------|-----|-------------|
+| State management | ✅ StateGraph | ✅ Memory | ✅ GroupChat | ✅ Built-in | ❌ Manual |
+| Multi-agent | ✅ Subgraphs | ✅ Crew | ✅ Native | ✅ Agents | ⚠️ Custom |
+| HITL | ✅ Interrupts | ⚠️ Custom | ✅ human_proxy | ✅ Native | ⚠️ Custom |
+| Streaming | ✅ Native | ⚠️ Limited | ✅ Native | ✅ Native | ✅ Native |
+| Checkpointing | ✅ Built-in | ❌ No | ❌ No | ✅ Built-in | ❌ No |
+| Learning curve | Medium | Low | Medium | Medium | Low |
+| Production readiness | ✅ Stable | ⚠️ Evolving | ✅ Stable | ⚠️ Growing | ⚠️ New |
+
+**Legend**: ✅ Strong | ⚠️ Partial | ❌ Not available
+
+## Framework Scoring Template (comparison mode)
+
+For each framework in `--compare`:
+
+```markdown
+## {Framework} — Score: {total}/100
+
+**Version** (from WebSearch): {latest stable}
+**Community** (from WebSearch): {GitHub stars, Discord, activity}
+
+| Requirement | Weight | Score | Weighted | Notes |
+|-------------|--------|-------|----------|-------|
+| Multi-agent coordination | 10 | {0-10} | {w*s} | |
+| State management | 8 | | | |
+| HITL support | 7 | | | |
+| Observability | 6 | | | |
+| Learning curve | 5 | | | |
+| Community support | 5 | | | |
+| Production readiness | 9 | | | |
+| **Total** | **50** | | **{sum}** | |
+
+**Best for**: {use case}
+**Not ideal for**: {anti-use-case}
+**Latest news**: {from WebSearch}
+```
+
+## Output Format
+
+End every output with a pointer to the next step:
+
+```
+→ Next: `/wicked-garden:agentic:design` to turn this framework choice into a five-layer architecture.
+```
+
+For comparison mode, render the Decision Matrix:
+
+```markdown
+## Framework Decision Matrix
+
+| Framework | Score/100 | Recommendation |
+|-----------|-----------|----------------|
+| {fw} | {n} | RECOMMEND / CONSIDER / AVOID |
+
+**Top recommendation**: {framework} — {one-line rationale}
+**Runner-up**: {framework}
+```
+
+For wizard mode, render a single recommendation with rationale referencing the user's answers.