wicked-garden 12.27.0

package/skills/agentic/refs/review.md

@@ -0,0 +1,160 @@
+# agentic:review — Full Agentic Codebase Review Rubric
+
+Full rubric sourced from `agents/agentic/architect.md`,
+`agents/agentic/safety-reviewer.md`, `agents/agentic/performance-analyst.md`,
+and `skills/agentic/review-methodology/`. Apply to the target path.
+
+## Step 1: Framework + Topology Detection
+
+Run the detection scripts directly:
+
+```bash
+sh "${CLAUDE_PLUGIN_ROOT}/scripts/_python.sh" \
+  "${CLAUDE_PLUGIN_ROOT}/scripts/_run.py" \
+  scripts/agentic/detect_framework.py --path "$TARGET_PATH"
+
+sh "${CLAUDE_PLUGIN_ROOT}/scripts/_python.sh" \
+  "${CLAUDE_PLUGIN_ROOT}/scripts/_run.py" \
+  scripts/agentic/analyze_agents.py \
+  --path "$TARGET_PATH" --framework "${FRAMEWORK_OVERRIDE:-$DETECTED_FRAMEWORK}"
+```
+
+If `--quick` is set, stop here and return the structural summary.
+
+## Step 2: Architecture Assessment (Five-Layer)
+
+Using `skills/agentic/agentic-patterns/` catalog, score each layer PASS / FAIL:
+
+| Layer | Check |
+|-------|-------|
+| Cognition | Single-responsibility, clear reasoning pattern, prompt versioning |
+| Context | Memory scoping, context limits respected, checkpointing |
+| Interaction | Tool interfaces defined, rate limits handled, graceful degradation |
+| Runtime | Orchestration strategy explicit, error handling, observability |
+| Governance | Input/output validation, HITL gates positioned, audit logging |
+
+**Topology health checks** (from `analyze_agents.py` output):
+- Circular dependencies → CRITICAL
+- God agents (>5 responsibilities) → HIGH
+- Orphaned agents → MEDIUM
+- Deep nesting (>4 levels) → MEDIUM
+
+## Step 3: Safety Assessment (8-Layer)
+
+Apply the full 8-layer rubric from `skills/agentic/refs/audit.md`.
+Focus: tool risk, HITL, PII, prompt injection, failure modes.
+
+Build risk matrix:
+
+| Category | Findings | Critical | High | Medium |
+|----------|----------|----------|------|--------|
+| Tool Risk | | | | |
+| HITL Gates | | | | |
+| PII Handling | | | | |
+| Prompt Injection | | | | |
+| AuthN/AuthZ | | | | |
+| Rate Limits | | | | |
+| Observability | | | | |
+| Failure Modes | | | | |
+
+## Step 4: Performance Assessment
+
+Using `skills/agentic/context-engineering/` and pattern catalog:
+
+**Token analysis**:
+- System prompt size and cacheability
+- Context window utilization (target: leave 35%+ buffer)
+- Opportunities for prompt compression
+
+**Latency analysis**:
+```bash
+# Find sequential agent calls that could parallelize
+grep -r "await.*agent\|agent\.run" --include="*.py" "$TARGET_PATH" -A 3
+```
+
+| Metric | Target | Finding |
+|--------|--------|---------|
+| Avg latency p50 | < 5s | |
+| Sequential ops that can parallelize | 0 | |
+| Cache hit rate | > 60% | |
+| Cost per request | {baseline} | |
+
+**Parallelization opportunities**: list agents that have no mutual dependencies
+and can run with `asyncio.gather()`.
+
+## Step 5: Pattern Scoring + Issue Taxonomy
+
+Run the pattern scorer to get quantitative data:
+
+```bash
+sh "${CLAUDE_PLUGIN_ROOT}/scripts/_python.sh" \
+  "${CLAUDE_PLUGIN_ROOT}/scripts/_run.py" \
+  scripts/agentic/pattern_scorer.py \
+  --agents "$AGENTS_FILE" --framework "$DETECTED_FRAMEWORK"
+
+sh "${CLAUDE_PLUGIN_ROOT}/scripts/_python.sh" \
+  "${CLAUDE_PLUGIN_ROOT}/scripts/_run.py" \
+  scripts/agentic/issue_taxonomy.py \
+  --findings "$FINDINGS_FILE" --agents "$AGENTS_FILE" \
+  --framework "$FRAMEWORK_FILE" --format markdown
+```
+
+**Anti-pattern detection** (from `skills/agentic/agentic-patterns/refs/anti-patterns-design.md`):
+
+| Anti-Pattern | Severity | Detection |
+|--------------|----------|-----------|
+| God Agent | HIGH | > 5 responsibilities |
+| Circular Dependency | CRITICAL | A → B → A in call graph |
+| State Mutation | HIGH | Shared mutable context |
+| Error Swallowing | MEDIUM | bare `except: pass` |
+| Tight Coupling | MEDIUM | Direct class instantiation |
+| Duplicated Orchestration | LOW | Same pipeline in 2+ places |
+
+## Output Format
+
+```markdown
+## Agentic Review: {Project}
+
+**Date**: {date} | **Framework**: {fw} v{version} | **Path**: {path}
+
+### Executive Summary
+{2-3 sentences — overall health, top 2 risks, main recommendation}
+
+### Five-Layer Architecture Scores
+
+| Layer | Score | Top Finding |
+|-------|-------|-------------|
+| Cognition | PASS/FAIL | |
+| Context | PASS/FAIL | |
+| Interaction | PASS/FAIL | |
+| Runtime | PASS/FAIL | |
+| Governance | PASS/FAIL | |
+
+### Safety Risk Matrix
+{table from Step 3}
+
+### Performance Summary
+{token / latency / cost findings, parallelization opportunities}
+
+### Issue Inventory by Severity
+
+**CRITICAL** (fix immediately):
+- {issue} — {file:line} — Fix: {action}
+
+**HIGH** (before production):
+- {issue} — {file:line} — Fix: {action}
+
+**MEDIUM** (next sprint):
+- …
+
+### 4-Phase Remediation Roadmap
+
+| Phase | Window | Items |
+|-------|--------|-------|
+| P0 | Immediate | CRITICAL items |
+| P1 | This sprint | HIGH items |
+| P2 | Next sprint | MEDIUM items |
+| P3 | Backlog | LOW + tech debt |
+```
+
+Write to `$OUTPUT_FILE` when `--output` is set; otherwise return inline.

package/skills/agentic/review-methodology/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: review-methodology
+description: |
+  Use when reviewing an agentic codebase for issues, risks, and maturity gaps — covers the four-phase review
+  process (Detect → Analyze → Prioritize → Report) and the five-level maturity model (Prototype → Functional →
+  Reliable → Production → Optimized) for assessing production readiness.
+  NOT for architecture design (use agentic-patterns) or live agentic review with a subagent (use agentic:review command).
+portability: portable
+phase_relevance: ["design", "review"]
+archetype_relevance: ["*"]
+---
+
+# Agentic Review Methodology
+
+Systematic approach to reviewing agentic systems and codebases for issues, risks, and improvement opportunities.
+
+## Four-Phase Review Process
+
+### Phase 1: Detect (Discovery)
+
+**Goal:** Identify all potential issues
+
+**Activities:**
+1. Code analysis (static analysis, anti-patterns)
+2. Configuration review (prompts, secrets, limits)
+3. Runtime analysis (logs, traces, metrics)
+4. Documentation review
+
+**Tools:**
+- Static analyzers (pylint, mypy, eslint)
+- Custom grep patterns for agentic anti-patterns
+- Log aggregation tools
+
+**Deliverable:** Raw issue inventory
+
+### Phase 2: Analyze (Assessment)
+
+**Goal:** Understand each issue's impact and root cause
+
+**For Each Issue:**
+1. Classify type (see `refs/issue-taxonomy-reliability-safety.md` and `refs/issue-taxonomy-quality-testing.md`)
+2. Determine severity (Critical/High/Medium/Low)
+3. Assess impact (Reliability/Security/Cost/Performance)
+4. Identify root cause
+5. Estimate fix effort
+
+**Analysis Framework:**
+- What is the issue?
+- Why is it a problem?
+- What are the consequences?
+- What is the root cause?
+- How should it be fixed?
+
+**Deliverable:** Analyzed issue list with severity and impact
+
+### Phase 3: Score (Prioritization)
+
+**Goal:** Prioritize issues for remediation
+
+**Severity Levels:**
+
+**Critical (P0):** Security vulnerabilities, data loss risks, system crashes, compliance violations. Fix immediately.
+
+**High (P1):** Reliability issues, performance problems, cost inefficiencies, safety gaps. Fix within 1 week.
+
+**Medium (P2):** Code quality issues, minor performance issues, missing observability. Fix within 1 month.
+
+**Low (P3):** Style issues, optimization opportunities, nice-to-have features. Backlog.
+
+**Prioritization Matrix:**
+```
+Impact vs Effort:
+           Low Effort    High Effort
+High       Quick Wins    Major Projects
+Impact     (Do First)    (Plan)
+
+Low        Easy Wins     Avoid
+Impact     (Do Later)    (Skip)
+```
+
+**Deliverable:** Prioritized roadmap
+
+### Phase 4: Report (Communication)
+
+**Goal:** Communicate findings effectively to stakeholders
+
+**Report Components:**
+1. Executive Summary (1 page) - Overall assessment and top recommendations
+2. Issue Inventory (Detailed) - All issues with severity and recommendations
+3. Remediation Roadmap - Phased approach with quick wins
+4. Metrics Dashboard - Issue counts and maturity score
+
+**Deliverable:** Comprehensive review report
+
+See `refs/deliverable-templates.md` for complete templates.
+
+## Issue Severity Classification
+
+### Determining Severity
+
+1. Can it cause data loss? → Critical
+2. Can it cause security breach? → Critical
+3. Does it crash the system? → Critical/High
+4. Does it violate compliance? → Critical
+5. Does it affect reliability? → High/Medium
+6. Does it waste money? → High/Medium
+7. Is it a code quality issue? → Medium/Low
+
+### Examples by Severity
+
+**Critical:**
+- No input validation (SQL injection risk)
+- Credentials in code
+- No error handling (system crashes)
+- Production deletes without approval
+- Missing audit logs for compliance
+
+**High:**
+- No circuit breakers (cascading failures)
+- Missing observability (can't debug)
+- No resource limits (runaway costs)
+- Hardcoded prompts (can't iterate)
+- No testing (high bug risk)
+
+**Medium:**
+- Inefficient token usage
+- Missing documentation
+- No caching (higher costs)
+- Verbose logging
+- Code duplication
+
+**Low:**
+- Style inconsistencies
+- Missing type hints
+- Suboptimal variable names
+- Minor optimizations
+
+See `refs/issue-taxonomy-reliability-safety.md` and `refs/issue-taxonomy-quality-testing.md` for complete classification guide.
+
+## Finding Documentation Template
+
+For each issue, document:
+
+```markdown
+## Issue: [Short Title]
+
+**ID:** ISSUE-001
+**Severity:** Critical | High | Medium | Low
+**Category:** Reliability | Security | Safety | Cost | Performance | Quality
+**Component:** [Which agent/module]
+
+### Description
+[What is the issue?]
+
+### Evidence
+[Code snippets, logs, metrics]
+
+### Impact
+[What are the consequences?]
+
+### Root Cause
+[Why does this exist?]
+
+### Recommendation
+[How to fix it?]
+
+### Effort Estimate
+[Hours/Days/Weeks]
+
+### Priority
+[P0/P1/P2/P3]
+```
+
+## Tips for Effective Reviews
+
+1. **Be Systematic:** Follow all four phases
+2. **Be Objective:** Focus on facts, not opinions
+3. **Be Specific:** Provide code examples and evidence
+4. **Be Constructive:** Suggest solutions, not just problems
+5. **Be Prioritized:** Don't overwhelm with low-priority issues
+6. **Be Clear:** Use simple language in reports
+
+## References
+
+- `refs/issue-taxonomy-reliability-safety.md` and `refs/issue-taxonomy-quality-testing.md` - Complete issue category reference and anti-pattern detection
+- `refs/deliverable-templates.md` - Detailed report templates and review checklist

package/skills/agentic/review-methodology/refs/deliverable-templates.md

@@ -0,0 +1,246 @@
+---
+phase_relevance: ["design", "review"]
+archetype_relevance: ["*"]
+---
+# Review Deliverable Templates
+
+Complete templates for all review report types.
+
+## 1. Issue Inventory (Detailed Report)
+
+```markdown
+# Agentic System Review - Issue Inventory
+Date: 2026-02-05
+Reviewer: [Name]
+
+## Summary
+- Total Issues: 47
+- Critical: 3
+- High: 12
+- Medium: 20
+- Low: 12
+
+## Critical Issues (P0)
+
+### ISSUE-001: No input validation
+**Severity:** Critical
+**Category:** Security
+**Component:** UserInputHandler
+
+**Description:**
+User inputs are passed directly to SQL queries without validation or sanitization.
+
+**Evidence:**
+```python
+query = f"SELECT * FROM users WHERE name = '{user_input}'"
+```
+
+**Impact:**
+SQL injection vulnerability allowing arbitrary database access.
+
+**Root Cause:**
+No input validation layer implemented.
+
+**Recommendation:**
+Implement parameterized queries and input validation.
+
+**Effort Estimate:** 3 days
+
+**Priority:** P0
+
+[Additional issues...]
+```
+
+## 2. Executive Summary (1-Pager)
+
+```markdown
+# Executive Summary - Agentic System Review
+
+## Overall Assessment
+The system shows promise but has critical security and reliability gaps
+that must be addressed before production deployment.
+
+## Critical Findings
+1. Input validation is missing, creating SQL injection risk (ISSUE-001)
+2. No circuit breakers, leading to cascading failures (ISSUE-005)
+3. Credentials stored in code (ISSUE-008)
+
+## Top 3 Recommendations
+1. Implement comprehensive input validation (1 week)
+2. Add circuit breakers and retry logic (3 days)
+3. Move credentials to secure vault (1 day)
+
+## Estimated Effort
+- Critical fixes: 2 weeks
+- High priority: 4 weeks
+- Total: 6 weeks to production-ready
+
+## Maturity Assessment
+Current Level: 1 (Functional)
+Target Level: 3 (Production)
+Gap: Safety, Reliability, Observability
+```
+
+## 3. Remediation Roadmap
+
+```markdown
+# Remediation Roadmap
+
+## Phase 1: Critical Fixes (Week 1-2)
+- [ ] Add input validation (ISSUE-001)
+- [ ] Remove hardcoded credentials (ISSUE-008)
+- [ ] Add circuit breakers (ISSUE-005)
+
+## Phase 2: High Priority (Week 3-6)
+- [ ] Implement observability (ISSUE-010)
+- [ ] Add resource limits (ISSUE-012)
+- [ ] Externalize prompts (ISSUE-015)
+
+## Phase 3: Medium Priority (Week 7-10)
+- [ ] Add caching (ISSUE-020)
+- [ ] Improve documentation (ISSUE-025)
+- [ ] Optimize token usage (ISSUE-030)
+
+## Quick Wins (Can do anytime)
+- [ ] Add type hints (ISSUE-040)
+- [ ] Fix linting errors (ISSUE-045)
+```
+
+## 4. Metrics Dashboard
+
+```
+Issue Distribution by Severity:
+Critical  [███░░░░░░░] 3
+High      [█████████░] 12
+Medium    [██████████] 20
+Low       [██████░░░░] 12
+
+Issue Distribution by Category:
+Security      [█████░░░░░] 8
+Reliability   [██████████] 15
+Safety        [███░░░░░░░] 5
+Cost          [████░░░░░░] 6
+Performance   [███░░░░░░░] 5
+Quality       [█████░░░░░] 8
+
+Maturity Score:
+Reliability:    ████░ 2.0/4.0
+Observability:  ██░░░ 1.0/4.0
+Safety:         ███░░ 1.5/4.0
+Testing:        ██░░░ 1.0/4.0
+Overall:        ██░░░ 1.4/4.0 (Functional)
+```
+
+## 5. Finding Documentation Template
+
+```markdown
+## Issue: [Short Title]
+
+**ID:** ISSUE-001
+**Severity:** Critical | High | Medium | Low
+**Category:** Reliability | Security | Safety | Cost | Performance | Quality
+**Component:** [Which agent/module]
+
+### Description
+[What is the issue?]
+
+### Evidence
+[Code snippets, logs, metrics]
+
+### Impact
+[What are the consequences?]
+
+### Root Cause
+[Why does this exist?]
+
+### Recommendation
+[How to fix it?]
+
+### Effort Estimate
+[Hours/Days/Weeks]
+
+### Priority
+[P0/P1/P2/P3]
+```
+
+## Review Checklist
+
+Complete checklist for comprehensive review.
+
+### Architecture
+- [ ] Agent roles clearly defined
+- [ ] Communication patterns documented
+- [ ] State management strategy clear
+- [ ] Error handling strategy defined
+
+### Code Quality
+- [ ] Prompts externalized
+- [ ] No hardcoded values
+- [ ] Proper error handling
+- [ ] Logging implemented
+- [ ] Type hints present
+- [ ] Code documented
+
+### Safety & Security
+- [ ] Input validation
+- [ ] Output validation
+- [ ] Action whitelisting
+- [ ] Human-in-the-loop gates
+- [ ] PII detection
+- [ ] Audit logging
+- [ ] No credentials in code
+
+### Reliability
+- [ ] Error handling
+- [ ] Retry logic
+- [ ] Circuit breakers
+- [ ] Timeouts
+- [ ] Graceful degradation
+
+### Observability
+- [ ] Structured logging
+- [ ] Distributed tracing
+- [ ] Metrics collection
+- [ ] Dashboards
+- [ ] Alerting
+
+### Testing
+- [ ] Unit tests
+- [ ] Integration tests
+- [ ] Test coverage > 70%
+- [ ] CI/CD pipeline
+
+### Performance & Cost
+- [ ] Token usage monitored
+- [ ] Cost tracking
+- [ ] Caching implemented
+- [ ] Resource limits
+
+### Documentation
+- [ ] Architecture documented
+- [ ] API documented
+- [ ] Runbooks exist
+- [ ] README complete
+
+## Anti-Pattern Grep Commands
+
+Quick detection commands for common issues:
+
+```bash
+# Hardcoded credentials
+grep -r "api_key\s*=\s*['\"]" .
+grep -r "password\s*=\s*['\"]" .
+
+# No error handling
+grep -r "await.*generate" . | grep -v "try"
+
+# Hardcoded prompts in code
+grep -r "You are a" . --include="*.py"
+
+# No input validation
+grep -r "user_input" . | grep -v "validate"
+
+# Missing timeouts
+grep -r "while True" .
+grep -r "await" . | grep -v "timeout"
+```