wicked-garden 12.27.0

package/scripts/where_am_i.py

@@ -0,0 +1,236 @@
+#!/usr/bin/env python3
+"""
+where_am_i.py — Emit a compact path manifest for the current session.
+
+Resolves the five storage roots used by wicked-garden subagent dispatches
+so callers don't have to re-enumerate them in every prompt:
+
+  1. plugin_root       — the wicked-garden plugin checkout
+  2. source_cwd        — the working directory at invocation
+  3. project_artifacts — ~/.something-wicked/wicked-garden/projects/{slug}/...
+  4. brain             — ~/.wicked-brain/projects/{basename}/_meta/config.json
+  5. bus_db            — ~/.something-wicked/wicked-bus/bus.db
+
+Usage:
+    where_am_i.py            # JSON manifest (default)
+    where_am_i.py --fence    # wrap in ```json fence
+    where_am_i.py --env      # substitute env-var forms (e.g. $CLAUDE_PLUGIN_ROOT)
+
+Fail-open contract: any resolution failure emits `null` for that field and
+a one-line note on stderr; the script never raises to the caller.
+
+Provenance: Issue #576 — reduce per-dispatch prompt bloat.
+"""
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+# Named constants — avoid magic strings.
+_ENV_PLUGIN_ROOT = "CLAUDE_PLUGIN_ROOT"
+_CREW_DOMAIN = "wicked-crew"
+_CREW_PROJECTS_SUB = "projects"
+_BRAIN_ROOT = Path.home() / ".wicked-brain"
+_BRAIN_PROJECTS = _BRAIN_ROOT / "projects"
+_BRAIN_META_CONFIG = Path("_meta") / "config.json"
+_ROOT_BRAIN_CONFIG = _BRAIN_ROOT / "_meta" / "config.json"
+_BUS_DB_PATH = Path.home() / ".something-wicked" / "wicked-bus" / "bus.db"
+
+_FENCE_OPEN = "```json"
+_FENCE_CLOSE = "```"
+
+# Ensure scripts/ is importable when invoked directly.
+_THIS_DIR = Path(__file__).resolve().parent
+if str(_THIS_DIR) not in sys.path:
+    sys.path.insert(0, str(_THIS_DIR))
+
+
+def _note(msg: str) -> None:
+    """Emit a single-line stderr note; never raises."""
+    try:
+        sys.stderr.write(f"[where-am-i] {msg}\n")
+    except OSError:
+        pass  # fail open — stderr unavailable is non-fatal
+
+
+def _resolve_plugin_root() -> str | None:
+    """Return the plugin checkout path, preferring CLAUDE_PLUGIN_ROOT."""
+    env_val = os.environ.get(_ENV_PLUGIN_ROOT)
+    if env_val:
+        return env_val
+    try:
+        # Fail-safe: the helper lives at <plugin_root>/scripts/where_am_i.py
+        return str(Path(__file__).resolve().parents[1])
+    except (OSError, IndexError) as exc:
+        _note(f"plugin_root fallback failed: {exc}")
+        return None
+
+
+def _resolve_source_cwd() -> str | None:
+    """Return the caller's working directory."""
+    try:
+        return os.getcwd()
+    except OSError as exc:
+        _note(f"source_cwd unresolved: {exc}")
+        return None
+
+
+def _resolve_project_artifacts() -> tuple[str | None, str | None]:
+    """Resolve (project_artifacts_path, active_project_id).
+
+    When SessionState.active_project_id is set, returns the project-specific
+    artifacts directory; otherwise returns the crew projects domain root.
+    """
+    try:
+        from _paths import get_local_path
+    except Exception as exc:
+        _note(f"_paths import failed: {exc}")
+        return None, None
+
+    try:
+        from _session import SessionState
+        state = SessionState.load()
+        active_id = state.active_project_id
+    except Exception as exc:
+        _note(f"SessionState load failed: {exc}")
+        active_id = None
+
+    try:
+        base = get_local_path(_CREW_DOMAIN, _CREW_PROJECTS_SUB)
+    except Exception as exc:
+        _note(f"get_local_path failed: {exc}")
+        return None, active_id
+
+    if active_id:
+        return str(base / active_id), active_id
+    return str(base), active_id
+
+
+def _resolve_brain() -> dict | None:
+    """Resolve brain config path + port for the current cwd.
+
+    Prefers the project brain at ~/.wicked-brain/projects/{cwd_basename}/.
+    Falls back to the root brain config. Returns None when neither exists.
+    """
+    try:
+        cwd_name = Path(os.getcwd()).name
+    except OSError as exc:
+        _note(f"brain cwd basename failed: {exc}")
+        cwd_name = ""
+
+    candidates: list[Path] = []
+    if cwd_name:
+        candidates.append(_BRAIN_PROJECTS / cwd_name / _BRAIN_META_CONFIG)
+    candidates.append(_ROOT_BRAIN_CONFIG)
+
+    for cfg_path in candidates:
+        if not cfg_path.is_file():
+            continue
+        try:
+            with open(cfg_path, encoding="utf-8") as fh:
+                cfg = json.load(fh)
+        except (OSError, ValueError) as exc:
+            _note(f"brain config read failed at {cfg_path}: {exc}")
+            continue
+        port_val = cfg.get("server_port")
+        try:
+            port = int(port_val) if port_val is not None else None
+        except (TypeError, ValueError):
+            port = None
+        # cfg_path is .../<project>/_meta/config.json — emit the project dir.
+        brain_path = cfg.get("brain_path") or str(cfg_path.parent.parent)
+        return {"path": brain_path, "port": port}
+
+    _note("brain config not found")
+    return None
+
+
+def _resolve_bus_db() -> str | None:
+    """Return the bus DB path if present, else None."""
+    try:
+        if _BUS_DB_PATH.is_file():
+            return str(_BUS_DB_PATH)
+    except OSError as exc:
+        _note(f"bus_db stat failed: {exc}")
+        return None
+    _note("bus_db not present")
+    return None
+
+
+def build_manifest() -> dict:
+    """Compose the manifest dict. Never raises."""
+    plugin_root = _resolve_plugin_root()
+    source_cwd = _resolve_source_cwd()
+    project_artifacts, active_project_id = _resolve_project_artifacts()
+    brain = _resolve_brain()
+    bus_db = _resolve_bus_db()
+
+    return {
+        "plugin_root": plugin_root,
+        "source_cwd": source_cwd,
+        "active_project_id": active_project_id,
+        "project_artifacts": project_artifacts,
+        "brain": brain,
+        "bus_db": bus_db,
+    }
+
+
+def apply_env_substitutions(manifest: dict) -> dict:
+    """Replace concrete paths with env-var forms when the env is present.
+
+    Currently maps plugin_root -> $CLAUDE_PLUGIN_ROOT. Other fields stay
+    as-is so consumers still get usable absolute paths.
+    """
+    out = dict(manifest)
+    env_plugin = os.environ.get(_ENV_PLUGIN_ROOT)
+    if env_plugin and out.get("plugin_root") == env_plugin:
+        out["plugin_root"] = f"${_ENV_PLUGIN_ROOT}"
+    return out
+
+
+def render(manifest: dict, *, fence: bool) -> str:
+    """Serialize the manifest to JSON, optionally fenced for paste."""
+    body = json.dumps(manifest, indent=2, sort_keys=True)
+    if fence:
+        return f"{_FENCE_OPEN}\n{body}\n{_FENCE_CLOSE}"
+    return body
+
+
+def _parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="where_am_i",
+        description="Emit a compact path manifest for the current session.",
+    )
+    parser.add_argument(
+        "--json",
+        dest="as_json",
+        action="store_true",
+        help="Emit JSON manifest (default).",
+    )
+    parser.add_argument(
+        "--fence",
+        action="store_true",
+        help="Wrap the JSON manifest in a ```json fence.",
+    )
+    parser.add_argument(
+        "--env",
+        action="store_true",
+        help="Substitute env-var forms (e.g. $CLAUDE_PLUGIN_ROOT).",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parse_args(argv if argv is not None else sys.argv[1:])
+    manifest = build_manifest()
+    if args.env:
+        manifest = apply_env_substitutions(manifest)
+    output = render(manifest, fence=args.fence)
+    sys.stdout.write(output + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/agentic/agentic-patterns/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: agentic-patterns
+description: |
+  Use when designing or analyzing multi-agent architectures — covers core patterns (sequential, hierarchical,
+  parallel, event-driven), anti-patterns, and the five-layer model (Cognition → Context → Interaction →
+  Runtime → Governance) for separating concerns in production-grade agentic systems.
+  NOT for reviewing existing agentic code (use review-methodology) or framework selection (use the frameworks skill).
+portability: portable
+phase_relevance: ["design", "review"]
+archetype_relevance: ["*"]
+---
+
+# Agentic Patterns
+
+Reference guide for proven agentic architecture patterns and common anti-patterns to avoid.
+
+## Core Patterns
+
+| Pattern | Use when | Example | Tradeoffs |
+|---------|----------|---------|-----------|
+| **Sequential** | Linear workflow, clear dependencies, predictable stages | Research → Analyze → Draft → Review | Simple coordination; bottlenecks if any agent is slow |
+| **Hierarchical** | Complex task decomposable into subtasks; central coordination | PM agent delegates to designer / dev / QA | Clear accountability, scales; single point of failure at parent |
+| **Collaborative** | Diverse perspectives matter; no clear lead | Multiple reviewers collaborating on code review | Rich outputs; needs conflict resolution + consensus |
+| **Autonomous** | Tasks are fully independent; parallel execution | Multiple monitoring agents checking different services | Max parallelism; no shared learning or coordination |
+| **Human-in-the-Loop** | High-stakes decisions, regulatory gates, human feedback | Agent drafts report; human approves before sending | Adds latency; ensures safety and quality |
+| **ReAct** | Dynamic environments; need adaptive behavior on feedback | Debug agent: try fix → observe tests → adapt | Flexible; high token/latency cost for reasoning |
+| **Plan-Execute** | Predictable environment; planning overhead justified | Multi-step pipeline with known transformations | Efficient; brittle if environment changes |
+| **Reflection** | Quality > speed; self-improvement valuable | Writer drafts → critiques → refines | Higher quality; more tokens and latency |
+
+See `refs/pattern-catalog.md` for full descriptions and implementation notes per pattern.
+
+## Anti-Patterns Quick Reference
+
+1. **God Agent:** Single agent doing everything. Split responsibilities.
+2. **Tight Coupling:** Agents depend on internal implementation details. Use interfaces.
+3. **Missing Guardrails:** No constraints on agent actions. Add validation and limits.
+4. **Deep Nesting:** Agents calling agents calling agents. Flatten hierarchy.
+5. **No Observability:** Can't see what agents are doing. Add logging and tracing.
+6. **Sequential Bottleneck:** Everything waits for slowest agent. Add parallelism.
+7. **Context Bloat:** Passing entire history to every agent. Compress and filter.
+8. **Redundant Agents:** Multiple agents doing same thing. Consolidate.
+9. **Hardcoded Prompts:** Prompts baked into code. Externalize and version.
+10. **Missing Timeouts:** Agents can run forever. Add time and resource limits.
+
+## Pattern Selection Decision Tree
+
+```
+Is task decomposable into subtasks?
+├─ YES: Is there a clear lead/coordinator role?
+│   ├─ YES: Use Hierarchical
+│   └─ NO: Use Collaborative
+└─ NO: Does task require adaptation based on results?
+    ├─ YES: Can you plan all steps upfront?
+    │   ├─ YES: Use Plan-Execute
+    │   └─ NO: Use ReAct
+    └─ NO: Do you have multiple independent tasks?
+        ├─ YES: Use Autonomous
+        └─ NO: Use Sequential
+```
+
+Add Human-in-the-Loop gates for any high-stakes decisions.
+Add Reflection layer when quality is critical.
+
+## Combining Patterns
+
+Patterns are composable:
+- **Hierarchical + ReAct:** Parent plans, children adapt execution
+- **Sequential + Reflection:** Each stage includes self-review
+- **Collaborative + Human-in-Loop:** Peer review with human arbitration
+- **Autonomous + Hierarchical:** Independent teams with team leads
+
+## Pattern Anti-Affinities
+
+Avoid these combinations:
+- **Plan-Execute + ReAct:** Contradictory - either plan upfront or adapt dynamically
+- **Autonomous + Tight Coordination:** Defeats the purpose of autonomy
+- **Deep Hierarchies + Reflection:** Exponential token cost
+
+## Quick Start
+
+1. Identify if task is decomposable (subtasks?) or atomic
+2. Identify if execution is predictable (plan?) or dynamic (adapt?)
+3. Identify if agents should coordinate (hierarchy/collaboration) or work independently
+4. Check anti-patterns list against current design
+5. See refs/pattern-catalog.md for detailed examples
+
+## References
+
+- `refs/pattern-catalog.md` - Detailed pattern descriptions with implementation examples
+- `refs/anti-patterns-design.md` - Design anti-patterns (God Agent, Tight Coupling, Missing Guardrails, Deep Nesting, No Observability)
+- `refs/anti-patterns-operational.md` - Operational anti-patterns (Sequential Bottleneck, Context Bloat, Redundant Agents, Hardcoded Prompts, Missing Timeouts)

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

@@ -0,0 +1,283 @@
+---
+phase_relevance: ["design", "review"]
+archetype_relevance: ["*"]
+---
+# Anti-Patterns in Agentic Systems: Design
+
+Common design mistakes in agentic systems and how to fix them. Covers God Agent, Tight Coupling, Missing Guardrails, Deep Nesting, and No Observability.
+
+## 1. God Agent
+
+### Description
+Single agent attempting to handle all responsibilities. Agent has too many tools, too much context, and too many decision points. Becomes a monolithic, unmaintainable system.
+
+### Symptoms
+- Agent has access to 20+ tools
+- Single system prompt is 5000+ tokens
+- Agent handles unrelated tasks (e.g., both code review and deployment)
+- Difficult to debug when things go wrong
+- High token costs due to large context
+
+### Why It Happens
+- Starting simple and accumulating features
+- Lack of clear separation of concerns
+- Fear of coordination complexity
+
+### How to Fix
+
+**Before:**
+```python
+god_agent = Agent(
+    tools=[
+        code_analysis, security_scan, performance_test,
+        deploy, rollback, monitoring, alerting,
+        documentation, ticket_creation, email_notification
+    ],
+    instructions="You are a DevOps agent that does everything..."
+)
+```
+
+**After:**
+```python
+# Specialized agents with clear responsibilities
+code_quality_agent = Agent(
+    tools=[code_analysis, security_scan, performance_test],
+    instructions="You review code quality, security, and performance."
+)
+
+deployment_agent = Agent(
+    tools=[deploy, rollback, monitoring],
+    instructions="You handle deployments and monitor health."
+)
+
+communication_agent = Agent(
+    tools=[documentation, ticket_creation, email_notification],
+    instructions="You handle documentation and notifications."
+)
+
+# Coordinator orchestrates specialists
+coordinator = HierarchicalAgent(
+    specialists={
+        "review": code_quality_agent,
+        "deploy": deployment_agent,
+        "communicate": communication_agent
+    }
+)
+```
+
+### Prevention
+- Each agent should have single, clear responsibility
+- Limit agents to 5-10 tools maximum
+- When adding a feature, ask: "Does this fit agent's core purpose?"
+
+## 2. Tight Coupling
+
+### Description
+Agents depend on internal implementation details of other agents. Changes to one agent break others. Hard to evolve or replace agents independently.
+
+### Symptoms
+- Agent A parses the exact output format of Agent B
+- Agents share global state without interfaces
+- Can't swap out an agent without updating all callers
+- Fragile to prompt engineering changes
+
+### Why It Happens
+- Quick prototyping without interfaces
+- Lack of abstraction layer
+- Direct access to other agents' internals
+
+### How to Fix
+
+**Before:**
+```python
+# Agent B tightly coupled to Agent A's output format
+class AgentB:
+    async def process(self, agent_a_output):
+        # Fragile: depends on exact string format
+        if "APPROVED:" in agent_a_output:
+            decision = agent_a_output.split("APPROVED:")[1].strip()
+            return self.proceed(decision)
+```
+
+**After:**
+```python
+# Define interface/contract
+class ReviewDecision:
+    approved: bool
+    reasoning: str
+    confidence: float
+
+# Agent A returns structured data
+class AgentA:
+    async def review(self, code) -> ReviewDecision:
+        result = await self.llm.generate(...)
+        return ReviewDecision(
+            approved=result["approved"],
+            reasoning=result["reasoning"],
+            confidence=result["confidence"]
+        )
+
+# Agent B depends on interface, not implementation
+class AgentB:
+    async def process(self, decision: ReviewDecision):
+        if decision.approved and decision.confidence > 0.8:
+            return self.proceed(decision.reasoning)
+```
+
+### Prevention
+- Define contracts/interfaces between agents
+- Use structured output formats (JSON, Pydantic models)
+- Version your interfaces
+- Validate inputs and outputs at boundaries
+
+## 3. Missing Guardrails
+
+### Description
+Agents can take any action without constraints. No validation, limits, or safety checks. High risk of unintended consequences.
+
+### Symptoms
+- Agents can delete production data
+- No human approval for high-stakes actions
+- Agents can run indefinitely
+- No rate limiting or resource constraints
+- Sensitive operations have no extra checks
+
+### Why It Happens
+- Focus on functionality over safety
+- Assuming LLM will "do the right thing"
+- Lack of production experience with agents
+
+### How to Fix
+
+**Before:**
+```python
+class DeploymentAgent:
+    async def execute(self, command):
+        # No guardrails!
+        return await self.shell.run(command)
+```
+
+**After:**
+```python
+class DeploymentAgent:
+    def __init__(self, max_runtime=300, require_approval=True):
+        self.max_runtime = max_runtime
+        self.require_approval = require_approval
+        self.allowed_commands = ["deploy", "status", "logs"]
+        self.forbidden_patterns = ["rm -rf", "DROP TABLE", "delete"]
+
+    async def execute(self, command):
+        # Validate command
+        if not self._is_safe_command(command):
+            raise SecurityError(f"Unsafe command: {command}")
+
+        # Require approval for production
+        if self.require_approval and self.is_production():
+            approval = await self.request_human_approval(command)
+            if not approval:
+                raise AbortedError("Human rejected command")
+
+        # Execute with timeout
+        try:
+            return await asyncio.wait_for(
+                self.shell.run(command),
+                timeout=self.max_runtime
+            )
+        except asyncio.TimeoutError:
+            raise TimeoutError(f"Command exceeded {self.max_runtime}s")
+
+    def _is_safe_command(self, command):
+        # Whitelist approach
+        if not any(cmd in command for cmd in self.allowed_commands):
+            return False
+        # Blacklist dangerous patterns
+        if any(pattern in command for pattern in self.forbidden_patterns):
+            return False
+        return True
+```
+
+### Prevention
+- Start with least privilege (minimal permissions)
+- Add human-in-the-loop for high-stakes actions
+- Implement timeouts and resource limits
+- Whitelist allowed actions
+- Validate all inputs and outputs
+- Add audit logging
+
+## 4. Deep Nesting
+
+### Description
+Agents calling agents calling agents, creating deep hierarchies. Hard to debug, trace, and reason about. High latency and token costs.
+
+### Symptoms
+- 4+ levels of agent nesting
+- Difficult to trace execution flow
+- High latency due to serial delegation
+- Token costs grow exponentially with depth
+- Hard to determine which agent made which decision
+
+### Why It Happens
+- Recursive decomposition without limits
+- Each agent delegates instead of doing work
+- Lack of architectural planning
+
+### How to Fix
+
+**Before:**
+```
+CEO Agent
+  → VP Agent
+    → Manager Agent
+      → Team Lead Agent
+        → Worker Agent (finally does work!)
+```
+
+**After:**
+```
+Coordinator Agent
+  → Specialist A (does work)
+  → Specialist B (does work)
+  → Specialist C (does work)
+```
+
+### Prevention
+- Limit hierarchy to 2-3 levels maximum
+- Favor flat, wide hierarchies over deep, narrow ones
+- Ensure agents at each level do meaningful work, not just delegate
+- Use sequential or collaborative patterns when hierarchy isn't needed
+
+## 5. No Observability
+
+### Description
+Can't see what agents are doing, why they made decisions, or where failures occur. Debugging is impossible. No metrics or monitoring.
+
+### Symptoms
+- "It didn't work" is the only error message
+- Can't replay failed executions
+- No visibility into agent reasoning
+- Can't measure performance or costs
+- Silent failures
+
+### Why It Happens
+- Focus on happy path
+- Treating agents as black boxes
+- Lack of production monitoring practices
+
+### How to Fix
+
+Wrap every agent in an `ObservableAgent` decorator that: opens a trace span, logs the task and agent ID before execution, records success/failure + duration + tokens_used after execution, and re-raises exceptions with full context.
+
+### What to Observe
+- Agent decisions and reasoning
+- Token usage per agent
+- Latency per agent and per operation
+- Success/failure rates
+- Input/output at each stage
+- Cost attribution
+
+### Prevention
+- Structured logging from day one
+- Distributed tracing across agents
+- Metrics and dashboards
+- Ability to replay executions
+- Save agent reasoning/thoughts