wicked-garden 12.27.0

package/skills/runtime-exec/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: wicked-garden-runtime-exec
+context: fork
+description: |
+  Smart runtime execution for Python and Node scripts with automatic package manager detection.
+  Invoked by other skills and agents when scripts need execution with correct runtime resolution.
+user-invocable: false
+phase_relevance: ["*"]
+archetype_relevance: ["*"]
+---
+
+# Runtime Execution Skill
+
+Execute Python and Node scripts using the best available package manager.
+
+## Recommended: use the `_python.sh` shim
+
+For Python scripts inside this plugin, prefer the cross-platform shim at
+`${CLAUDE_PLUGIN_ROOT}/scripts/_python.sh`. It resolves `python3`, `python`,
+or `py -3` based on what's available and handles macOS, Linux, and Windows
+in one call. Bare `python3` is not available on Windows.
+
+```bash
+sh "${CLAUDE_PLUGIN_ROOT}/scripts/_python.sh" "${CLAUDE_PLUGIN_ROOT}/scripts/some/script.py"
+```
+
+The detection logic below is reference material for skills that need a
+different fallback chain (e.g. dependency-aware `uv run`).
+
+## Python Execution Priority
+
+1. **uv** (preferred) - Fast, reliable, handles dependencies automatically
+2. **poetry** - Good for projects with poetry.lock
+3. **.venv/bin/python** - Pre-existing virtual environment
+4. **`_python.sh` shim** - Cross-platform fallback; may miss dependencies
+
+## Node Execution Priority
+
+1. **pnpm** (preferred) - Fast, disk-efficient
+2. **npm** - Standard, widely available
+3. **yarn** - Alternative package manager
+4. **npx** - For one-off script execution
+
+## Usage Patterns
+
+### Python Script Execution
+
+```bash
+# In a directory with pyproject.toml:
+cd "${CLAUDE_PLUGIN_ROOT}/scripts"
+
+# Preferred (auto-installs deps)
+uv run python script.py [args]
+
+# Alternative
+poetry run python script.py [args]
+
+# If venv exists
+.venv/bin/python script.py [args]
+
+# Last resort (may fail on deps)
+python3 script.py [args]
+```
+
+### Node Script Execution
+
+```bash
+# In a directory with package.json:
+cd "${CLAUDE_PLUGIN_ROOT}/scripts"
+
+# Preferred
+pnpm run script-name
+pnpm exec script.js
+
+# Alternative
+npm run script-name
+npx script.js
+
+# Yarn
+yarn run script-name
+```
+
+## Detection Logic
+
+When executing a script, detect the runtime context:
+
+```bash
+# Python detection
+if command -v uv &>/dev/null && [ -f pyproject.toml ]; then
+    uv run python "$@"
+elif command -v poetry &>/dev/null && [ -f poetry.lock ]; then
+    poetry run python "$@"
+elif [ -f .venv/bin/python ]; then
+    .venv/bin/python "$@"
+else
+    python3 "$@"
+fi
+
+# Node detection
+if command -v pnpm &>/dev/null && [ -f pnpm-lock.yaml ]; then
+    pnpm exec "$@"
+elif command -v npm &>/dev/null && [ -f package-lock.json ]; then
+    npx "$@"
+elif command -v yarn &>/dev/null && [ -f yarn.lock ]; then
+    yarn exec "$@"
+else
+    node "$@"
+fi
+```
+
+## Important Notes
+
+- Always `cd` to the script directory first (where pyproject.toml/package.json lives)
+- Use `uv run` for Python - it auto-syncs dependencies from pyproject.toml
+- Warn user if falling back to system Python/Node (deps may be missing)
+- For plugins, scripts are in `${CLAUDE_PLUGIN_ROOT}/scripts/`
+
+## Common Issues
+
+### Missing Dependencies
+If using system python3 and imports fail:
+```bash
+# Install uv (recommended)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Or create venv manually
+python3 -m venv .venv
+.venv/bin/pip install -e .
+```
+
+### Wrong Python Version
+```bash
+# Check version
+uv run python --version
+
+# Specify version in pyproject.toml:
+# requires-python = ">=3.10"
+```

package/skills/search/codebase-narrator/SKILL.md

@@ -0,0 +1,131 @@
+---
+# Search domain convention: search is primarily command-driven. Skill logic is embedded in
+# the domain scripts (scripts/search/). Skills here cover cross-cutting codebase-level
+# patterns only. For interactive search, use /wicked-garden:search:{code|docs|blast-radius|lineage}.
+name: codebase-narrator
+description: |
+  Narrate codebase structure and architecture for orientation — directory layout,
+  key modules, data flows, technical decisions, and code health. A query +
+  synthesis capability rather than a persistent role; produces a guided
+  reading order and flags gotchas for newcomers.
+
+  Use when: "give me an architecture walkthrough", "narrate this codebase",
+  "explain how this project is organized", "code navigation", "where should
+  I start reading".
+phase_relevance: ["*"]
+archetype_relevance: ["*"]
+---
+
+# Codebase Narrator
+
+Analyzes a codebase and produces a **narrative** — not a file list, but a story
+of how the project is organized, why things are where they are, what to read
+first, and what the non-obvious gotchas are. Works on any language or stack.
+
+## Quick Start
+
+Invoke this skill when a human (or a subagent) needs orientation on an
+unfamiliar codebase. Typical outputs:
+
+- Big-picture summary (what this project does and how it's built)
+- Directory map with annotations
+- Key modules with responsibilities, dependencies, dependents
+- Data flow ASCII diagram
+- Technical-decision table
+- Code-health signals
+- Reading order ("start here, then here, then here")
+- Gotchas list (non-obvious patterns, common newcomer mistakes)
+
+## First Strategy: Use wicked-* Ecosystem
+
+- **Search**: Use wicked-garden:search to find symbols, imports, and patterns
+- **Memory**: Use wicked-brain:memory to recall past architecture decisions
+- **Native tasks**: Inspect current work via TaskCreate/TaskUpdate with
+  `metadata={event_type, chain_id, source_agent, phase}`
+
+If wicked-* tools are available, prefer them over manual grep/find.
+
+## Process
+
+### 1. Scan Project Structure
+
+```bash
+# Depth-limited directory tree
+find . -maxdepth 3 -type f | head -100
+```
+
+Or use the search index (FTS5 over indexed code):
+```
+wicked-brain:search "class |function |def |interface "
+```
+
+Identify:
+- **Language(s)**: primary + secondary
+- **Framework(s)**: web framework, ORM, test framework
+- **Build system**: how the project builds
+- **Package manager**: dependency management
+
+### 2. Identify Key Modules
+
+Find the architectural pillars:
+- **Entry points**: main files, server startup, CLI entry
+- **Core domain**: business logic, models, entities
+- **API layer**: routes, controllers, endpoints
+- **Data layer**: database models, migrations, repositories
+- **Infrastructure**: config, deployment, CI/CD
+
+For each module: what does it do? what does it depend on? what depends on it?
+
+### 3. Trace Data Flows
+
+```
+User Request → API Layer → Business Logic → Data Layer → Response
+     ↓              ↓            ↓              ↓
+  Validation    Auth/Authz   Processing    Persistence
+```
+
+Map: happy path, error paths, async flows (background jobs, events, queues),
+external calls (third-party API integrations).
+
+### 4. Surface Technical Decisions
+
+Visible in the code:
+- **Architecture style**: monolith, microservices, serverless
+- **Design patterns**: repository, factory, observer, etc.
+- **Configuration approach**: env vars, config files, secrets management
+- **Testing strategy**: unit, integration, e2e coverage
+
+### 5. Assess Code Health
+
+- **Complexity hotspots**: large files, deep nesting
+- **Tech debt markers**: TODO/FIXME/HACK counts
+- **Test coverage**: test-to-code ratio
+- **Documentation**: README quality, inline comments
+- **Dependency health**: outdated or vulnerable deps
+
+### 6. Generate Narrative
+
+See [refs/output-template.md](refs/output-template.md) for the full structure.
+
+## Narrative Quality
+
+Good codebase narratives:
+- **Tell a story** — not just a file list, but why things are where they are
+- **Prioritize** — start with the most important modules
+- **Connect the dots** — show how pieces relate
+- **Flag surprises** — call out non-obvious patterns
+- **Guide exploration** — give a reading order, not just a map
+
+## Common Pitfalls
+
+- Listing every file without explaining relationships
+- Assuming reader knows the framework conventions
+- Skipping the "why" behind architectural choices
+- Ignoring test structure (tests reveal intent)
+- Missing configuration and deployment patterns
+
+## See Also
+
+- [refs/output-template.md](refs/output-template.md) — full output format
+- `/wicked-garden:search:blast-radius` — for impact analysis of specific symbols
+- `/wicked-garden:search:index` — build or refresh the index before diving in

package/skills/search/codebase-narrator/refs/output-template.md

@@ -0,0 +1,100 @@
+---
+phase_relevance: ["*"]
+archetype_relevance: ["*"]
+---
+# Codebase Narrator — Output Template
+
+## Codebase Narrative: {project_name}
+
+### The Big Picture
+
+{2-3 sentences describing what this project does and how it's built. Pitch it
+to a new hire, not an expert.}
+
+### Architecture Style
+
+**{style}** — {why this approach}
+
+### Directory Map
+
+```
+{annotated directory tree}
+
+project-root/
+├── src/              — main application code
+│   ├── api/          — HTTP layer, routes, controllers
+│   ├── domain/       — business logic, entities, services
+│   ├── data/         — database access, repositories, migrations
+│   └── infra/        — config, logging, telemetry
+├── tests/            — unit + integration tests (mirrors src/)
+├── scripts/          — operational scripts
+├── config/           — environment config
+├── docs/             — architecture + how-to guides
+└── .github/          — CI/CD pipelines
+```
+
+### Key Modules
+
+#### {Module 1}: {purpose}
+
+- **Location**: `{path}`
+- **Responsibility**: {what it does}
+- **Key files**: {important files}
+- **Dependencies**: {what it needs}
+- **Dependents**: {what needs it}
+
+#### {Module 2}: {purpose}
+...
+
+### Data Flow
+
+```
+{ASCII diagram or Mermaid}
+
+[Client] → [API Gateway] → [Service Layer]
+                                ↓
+                           [Repository]
+                                ↓
+                           [Database]
+```
+
+Happy path, error path, async flows, external calls.
+
+### Technical Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| {area}   | {choice} | {why}  |
+| Framework | FastAPI | async support, type hints |
+| Database | Postgres | transactions + JSONB |
+| Queue | RabbitMQ | team familiarity |
+
+### Code Health
+
+| Signal | Status | Notes |
+|--------|--------|-------|
+| Complexity | LOW / MED / HIGH | {detail} |
+| Test coverage | {%} | {detail} |
+| Tech debt | {count} markers | {detail} |
+| Documentation | {quality} | {detail} |
+| Dependencies | {current / stale / vulnerable} | {detail} |
+
+### Where to Start Reading
+
+1. **{file}** — {why start here}
+2. **{file}** — {what you'll learn}
+3. **{file}** — {how it connects}
+
+### Gotchas
+
+- {non-obvious pattern or convention}
+- {common mistake newcomers make}
+- {important but poorly documented behavior}
+- {legacy naming that no longer matches the code}
+- {any monkey-patched dependency or hand-rolled framework fork}
+
+### Next Steps
+
+- Run `{command}` to bring the app up locally
+- Read `docs/{file}.md` for the deeper architectural rationale
+- Key people to talk to: {roles / teams}, for {topic}

package/skills/smaht/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: wicked-garden-smaht
+context: fork
+description: |
+  Context assembly / briefing builder (the name is a phonetic play on "smart").
+  Gathers a relevant on-demand context briefing over wicked-brain + wicked-garden:search
+  + domain state. Pull-model: subagents call it when they need background rather than
+  having context pushed onto every prompt (v6 replaced the v5 push orchestrator, #428).
+
+  Use when: gathering a context briefing before a task, "assemble context",
+  "give me a briefing", resuming work after a session break, or building background
+  on an unfamiliar area. Aliases: context-assembly, briefing, smart-context.
+user-invocable: true
+phase_relevance: ["*"]
+archetype_relevance: ["*"]
+---
+
+# Context Assembly (v6 pull-model)
+
+Gather relevant context from wicked-brain + wicked-garden:search + domain state when
+a subagent or command asks for it. There is no per-prompt push — the user prompt
+submit hook no longer runs an orchestrator.
+
+## Quick Reference
+
+```bash
+# Brain search — primary knowledge source
+wicked-brain:search "your query"
+
+# Brain query — conceptual / "how does X work"
+wicked-brain:query "how does the facilitator rubric work"
+
+# Codebase symbol / docs search (FTS5 over indexed code, docs, wiki)
+wicked-brain:search "symbol or pattern"
+
+# Pull v11 archetype-mode project state (the v6 crew.py find-active
+# auto-resolver was deleted with the universal pipeline — look up by name)
+sh "${CLAUDE_PLUGIN_ROOT}/scripts/_python.sh" "${CLAUDE_PLUGIN_ROOT}/scripts/_run.py" scripts/crew/phase_manager.py {project} status --json
+```
+
+## Context Sources
+
+| Source | Plugin | Content |
+|--------|--------|---------|
+| brain | wicked-brain (required) | Code, docs, wiki, memories — FTS5 search |
+| search | wicked-garden | Indexed code symbols + docs |
+| mem | wicked-garden | Memories, decisions, learnings |
+| crew | wicked-garden | Project phase, outcomes, constraints |
+| jam | wicked-garden | Brainstorm sessions, perspectives |
+
+## Pull-Model Rules
+
+1. **Ask only for what you need.** Each adapter costs latency and tokens.
+2. **Brain first.** `wicked-brain:search` replaces Grep/Glob/Agent(Explore) for any
+   open-ended search. Fall back to raw tools only when the brain returns empty.
+3. **Active chain matters.** When a crew project is active, prefer queries scoped
+   to that project's `chain_id` — see `scripts/_session.py::SessionState.active_chain_id`.
+4. **Recent events win.** For debugging, prefer the last 20 chain-matching events
+   over broad semantic search.
+
+## Sub-Skills
+
+- [discovery/SKILL.md](discovery/SKILL.md) — Integration discovery and adapter configuration
+
+## v5 → v6 Notes
+
+The v5 HOT/FAST/SLOW/SYNTHESIZE tiered orchestrator
+(`scripts/smaht/v2/orchestrator.py`) was deleted in #428. Adapters (`brain_adapter`,
+`domain_adapter`, `events_adapter`, etc.) still live under `scripts/smaht/adapters/`
+and can be called directly by subagents as needed. There is no longer a central
+router that decides HOT vs FAST vs SLOW — the caller decides by picking which
+adapters (or skill calls) to invoke.

package/skills/smaht/discovery/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: discovery
+description: |
+  Contextual command discovery — suggests related commands based on what was just used.
+  Discovers relationships dynamically from command/skill content, not a static map.
+  Invoked by the Stop hook and smaht:briefing to surface one relevant suggestion.
+user-invocable: false
+phase_relevance: ["*"]
+archetype_relevance: ["*"]
+---
+
+# Contextual Discovery
+
+After a command or skill runs, suggest ONE related command the user hasn't tried.
+
+## How It Works
+
+Relationships are discovered dynamically, not hardcoded:
+
+### 1. Parse the just-used command/skill
+
+Read the command's `.md` file from `commands/{domain}/{command}.md`. Look for:
+- **Explicit references** to other commands (e.g., `/wicked-garden:search:blast-radius`)
+- **"See also"** or **"Integration"** sections listing related commands
+- **Agent dispatches** (`subagent_type="wicked-garden:{domain}:{agent}"`) — the dispatched agent's domain has related commands
+- **Skill references** (`Skill(skill="wicked-garden:{domain}:{skill}")`) — related domain commands
+
+### 2. Check what the user has already used this session
+
+Query session state for commands invoked in this session. Only suggest commands NOT already used.
+
+### 3. Rank candidates
+
+Priority:
+1. Commands explicitly referenced in the just-used command's `.md` file
+2. Commands in the same domain (sibling commands)
+3. Commands in domains listed in the "Integration" section
+4. Cross-domain commands that share the same specialist role
+
+### 4. Select ONE suggestion
+
+Pick the highest-ranked candidate the user hasn't used. Frame contextually:
+- Include a specific argument from the current context when possible
+- Use the user's own terms (file paths, symbol names, project descriptions)
+
+## Selection Rules
+
+1. Pick ONE suggestion (never more)
+2. Only suggest commands the user has NOT used in this session
+3. Match based on the most recent command, not full session history
+4. If no good match, suggest nothing — silence is better than noise
+5. Frame as a question: "You might find X useful" not "Run X"
+6. Include specific arguments from context when possible (symbol name, file path)
+
+## Common Patterns
+
+These natural workflows emerge from command cross-references:
+
+- **Review → Impact**: After reviewing code, check what depends on it
+- **Search → Plan**: After finding a symbol, plan the change
+- **Brainstorm → Store**: After deciding something, persist the decision
+- **Analyze → Synthesize**: After understanding data, generate recommendations
+- **Scenarios → Automate**: After defining test scenarios, generate test code
+- **Security → Compliance**: After security scan, check regulatory alignment
+- **Incident → Store**: After resolving an incident, capture learnings

package/skills/smaht/intent/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: intent
+description: |
+  Show or set the session intent variable. Intent gates how loud the
+  framework is — simple-edit (silent), feature/research (synthesis
+  directive), rigor (full crew context). Auto-detected on turn 1;
+  this skill overrides explicitly. Sticky for the session.
+
+  Use when: "set intent", "intent override", "/wicked-garden:intent",
+  "make the framework quiet", "force rigor", "what's my intent".
+user-invocable: true
+phase_relevance: ["*"]
+archetype_relevance: ["*"]
+---
+
+# /wicked-garden:intent
+
+Session intent is the keystone of v10's steer-not-block model. It's auto-detected from the first turn's prompt and made sticky for the rest of the session. This skill lets you (or a command on your behalf) override that auto-detection without using flags or fighting validators.
+
+## Vocabulary
+
+Four values, locked. To change the vocabulary, run a brainstorm — don't add ad-hoc.
+
+| Intent | When to set | What fires |
+|---|---|---|
+| `simple-edit` | Trivial turns, status checks, continuations | Nothing — silent |
+| `feature` | Building / fixing / refactoring code | Synthesis directive (wicked-brain pull) |
+| `research` | Conceptual questions, "explain how", "why does" | Synthesis directive (wicked-brain pull) |
+| `rigor` | Crew sessions, multi-phase work, audit trail required | Synthesis directive + active-chain context |
+
+## Usage
+
+```
+/wicked-garden:intent              # show effective current value
+/wicked-garden:intent rigor        # set explicit override
+/wicked-garden:intent simple-edit  # quiet the framework
+```
+
+## Behavior
+
+- Sets `state.intent` and `state.intent_explicit=True` in session state via `scripts/_session.py::SessionState.update`.
+- Sticky for the rest of the session; reset by SessionEnd hook.
+- Explicit override echoes a bare `<wg intent="X" t=N />` label in the next system-reminder so the model knows the user (or a command) steered the framework.
+- Auto-detected intent stays invisible to the model — prevents confirmation bias.
+
+## Implementation (≤30 lines, slim-skill shape per v10 Phase 2)
+
+```bash
+# Show or set session intent. Pass nothing to display; pass a value to override.
+# Heredoc is single-quoted (<<'PY') so the shell does NOT expand $variables
+# inside the Python source — the script reads CLAUDE_PLUGIN_ROOT via
+# os.environ instead, which is inherited by the subprocess.
+ARG="${1:-}"
+sh "${CLAUDE_PLUGIN_ROOT}/scripts/_python.sh" - "$ARG" <<'PY'
+import os
+import sys
+
+plugin_root = os.environ.get("CLAUDE_PLUGIN_ROOT")
+if not plugin_root:
+    print("error: CLAUDE_PLUGIN_ROOT not set", file=sys.stderr)
+    sys.exit(1)
+sys.path.insert(0, os.path.join(plugin_root, "scripts"))
+
+from _session import SessionState
+
+VALID = ("simple-edit", "feature", "rigor", "research")
+arg = (sys.argv[1] if len(sys.argv) > 1 else "").strip()
+state = SessionState.load()
+
+if not arg:
+    eff = state.intent or "(not set; auto-detect runs on next turn)"
+    src = "explicit" if state.intent_explicit else "auto-detected" if state.intent else "n/a"
+    print(f"intent: {eff}  ({src})")
+    sys.exit(0)
+
+if arg not in VALID:
+    print(f"error: '{arg}' not in {VALID}", file=sys.stderr)
+    sys.exit(1)
+
+state.update(intent=arg, intent_explicit=True)
+print(f"intent set: {arg}  (explicit override; sticky until session end)")
+PY
+```
+
+## Notes
+
+- **Auto-detection runs once** on the first 1-2 turns and is sticky thereafter. If auto-detect picks the wrong value, override with this skill once and it sticks for the session.
+- **Commands may self-declare** by calling this skill internally as their first action — e.g. a future `crew:start` could call `/wicked-garden:intent rigor` to ensure the rigor directive fires from turn 1, even if the user's first prompt was short.
+- **Issue #813** for the design rationale + brainstorm record.