wicked-garden 12.27.0

package/skills/multi-model/refs/opencode.md

@@ -0,0 +1,196 @@
+---
+phase_relevance: ["clarify", "design"]
+archetype_relevance: ["*"]
+---
+# OpenCode CLI — Usage Patterns
+
+OpenCode CLI for AI-assisted coding with multiple providers. Supports OpenAI, Anthropic,
+Google, and more. Includes TUI mode, session continuity, and GitHub PR integration.
+
+## Installation and Setup
+
+```bash
+# Check if installed
+which opencode
+
+# Install
+brew install opencode  # or see https://github.com/sst/opencode
+
+# Authentication (supports multiple providers)
+opencode auth  # Interactive auth setup
+```
+
+## Core Usage Patterns
+
+### Non-Interactive (run)
+
+```bash
+# Simple query
+opencode run "Explain this error: ${error_message}"
+
+# With file context
+opencode run "Review this code for security issues" -f src/auth.py
+
+# Multiple files
+opencode run "How do these modules interact?" -f src/api.ts -f src/db.ts
+
+# Specific model
+opencode run -m anthropic/claude-3-5-sonnet "Analyze this design" -f design.md
+
+# Continue previous session
+opencode run -c "What about error handling?"
+
+# Continue specific session by ID
+opencode run -s SESSION_ID "Follow-up question"
+```
+
+### Interactive TUI Session
+
+```bash
+# Start in current directory
+opencode
+
+# Start in specific project
+opencode /path/to/project
+
+# Open web interface
+opencode web
+```
+
+### GitHub Integration
+
+```bash
+# Fetch and review a PR
+opencode pr 123
+
+# Work with GitHub agent
+opencode github
+```
+
+## Model Selection
+
+OpenCode's key differentiator: switch providers without changing workflow.
+
+```bash
+# OpenAI models
+opencode run -m openai/gpt-4o "Query"
+opencode run -m openai/o1 --variant high "Complex analysis"
+
+# Anthropic models
+opencode run -m anthropic/claude-3-5-sonnet "Query"
+
+# Google models
+opencode run -m google/gemini-1.5-pro "Query"
+
+# List available models
+opencode models
+opencode models openai
+opencode models anthropic
+```
+
+## Multi-Provider Comparison
+
+Use OpenCode to get the same query answered by multiple providers:
+
+```bash
+PROMPT="Review this auth design for security issues"
+FILE="docs/auth-design.md"
+
+# GPT-4o perspective
+opencode run -m openai/gpt-4o "$PROMPT" -f "$FILE" > gpt4o_review.md
+
+# Claude perspective (via OpenCode, not current session)
+opencode run -m anthropic/claude-3-5-sonnet "$PROMPT" -f "$FILE" > claude_review.md
+
+# Gemini perspective
+opencode run -m google/gemini-1.5-pro "$PROMPT" -f "$FILE" > gemini_review.md
+```
+
+## Native Task Tracking
+
+```
+# Create review task
+TaskCreate(
+  subject="Multi-provider review: checkout flow",
+  metadata={
+    "event_type": "task",
+    "chain_id": "checkout-review.root",
+    "source_agent": "multi-model:opencode",
+    "priority": "P1"
+  }
+)
+
+# Capture GPT-4o perspective and append via TaskUpdate
+# OPENCODE_REVIEW=$(opencode run -m openai/gpt-4o "Review" -f src/checkout.ts)
+# TaskUpdate(taskId, description="{previous}\n\nopencode (gpt-4o): ${OPENCODE_REVIEW}")
+```
+
+## Command Reference
+
+| Command | Description |
+|---------|-------------|
+| `opencode` | Interactive TUI session |
+| `opencode run "message"` | Non-interactive one-shot |
+| `opencode run -f file "query"` | Query with file context |
+| `opencode run -c "follow up"` | Continue last session |
+| `opencode pr 123` | Work on GitHub PR |
+| `opencode models` | List available models |
+| `opencode auth` | Configure provider authentication |
+| `opencode web` | Open web interface |
+
+## Options Reference
+
+| Option | Description |
+|--------|-------------|
+| `-m provider/model` | Select model |
+| `-f path` | Attach file(s) |
+| `-c` | Continue last session |
+| `-s SESSION_ID` | Continue specific session |
+| `--variant high` | Reasoning effort variant |
+
+## Strengths
+
+| Area | Description |
+|------|-------------|
+| Multi-provider | One CLI, any provider — ideal for comparison |
+| Session continuity | `-c` flag continues conversations naturally |
+| GitHub integration | Native PR review and issue management |
+| TUI mode | Full interactive coding sessions |
+
+## Best Practices
+
+1. **Use for multi-provider comparison** — OpenCode's main advantage is provider flexibility
+2. **Session continuity** — Use `-c` for follow-up questions without losing context
+3. **PR reviews** — `opencode pr 123` for native GitHub PR review
+4. **File context** — Use `-f` to attach files cleanly (vs piping)
+
+## Session Management
+
+```bash
+# Start a session
+opencode run "Let's review the auth design" -f design.md
+
+# Continue naturally
+opencode run -c "What about the token refresh strategy?"
+opencode run -c "How does this compare to session-based auth?"
+
+# Or use specific session ID for parallel threads
+SESSION_A=$(opencode run -m openai/gpt-4o "Review" -f design.md | grep "session:" | awk '{print $2}')
+opencode run -s "$SESSION_A" -c "Deeper dive on security"
+```
+
+## Common Prompts
+
+```bash
+# Architecture review with GPT-4o
+opencode run -m openai/gpt-4o "Architecture review: scalability, coupling, and missing abstractions" -f design.md
+
+# PR review
+opencode pr 123  # Interactive; or:
+gh pr diff 123 | opencode run "Code review: flag issues and missing tests"
+
+# Multi-provider comparison
+for model in openai/gpt-4o anthropic/claude-3-5-sonnet google/gemini-1.5-pro; do
+  echo "=== $model ===" && opencode run -m "$model" "Security review" -f src/auth.py
+done
+```

package/skills/multi-model/refs/orchestration.md

@@ -0,0 +1,188 @@
+---
+phase_relevance: ["clarify", "design"]
+archetype_relevance: ["*"]
+---
+# Multi-Model Orchestration Patterns
+
+Patterns for coordinating multiple AI models via external CLI dispatch.
+Each model responds independently to a fixed question scaffold, then Claude synthesizes.
+
+## The Orchestration Loop
+
+```
+1. Detect CLIs (which codex gemini opencode pi)
+2. Quorum check (need 2+ for true council)
+3. Build question scaffold (4 fixed questions)
+4. Dispatch scaffold to each CLI in parallel (stdin pipe)
+5. Claude answers the same scaffold independently
+6. Synthesize all responses (3-stage output)
+7. Persist transcript + decision record
+```
+
+## CLI Detection
+
+```bash
+# Council agent detects available CLIs at runtime
+which codex 2>/dev/null && echo "codex:available" || echo "codex:missing"
+which copilot 2>/dev/null && echo "copilot:available" || echo "copilot:missing"
+which gemini 2>/dev/null && echo "gemini:available" || echo "gemini:missing"
+which opencode 2>/dev/null && echo "opencode:available" || echo "opencode:missing"
+which pi 2>/dev/null && echo "pi:available" || echo "pi:missing"
+```
+
+### Quorum Rules
+
+| Available External CLIs | Behavior |
+|------------------------|----------|
+| 0 | Refuse council. Suggest `/jam:brainstorm` instead. |
+| 1 | Run as "brainstorm with external guest" — warn not a true council. |
+| 2+ | Full council mode. |
+
+## Question Scaffold
+
+Every external model answers the **same fixed question set** for comparability:
+
+```
+Topic: {topic}
+Options under evaluation: {options}
+Evaluation criteria: {criteria}
+
+Answer these 4 questions:
+
+1. RECOMMENDATION: Which option do you recommend and why?
+2. TOP RISK: What is the single biggest risk in your recommendation?
+3. WHAT WOULD CHANGE YOUR MIND: What evidence would reverse your recommendation?
+4. DISQUALIFIER: Is any option fundamentally unviable? If so, which and why?
+```
+
+## Parallel Dispatch
+
+**Non-negotiable**: Each model responds independently. No model sees another's output.
+
+```bash
+# Write scaffold to temp file (avoids shell quoting issues)
+SCAFFOLD_FILE="${TMPDIR:-/tmp}/council-scaffold-$$.md"
+cat > "$SCAFFOLD_FILE" <<'SCAFFOLD_EOF'
+{question_scaffold_content}
+SCAFFOLD_EOF
+
+# Dispatch in parallel (all run simultaneously via multiple Bash calls)
+cat "$SCAFFOLD_FILE" | codex exec "Evaluate the options. Answer the 4 questions."
+cat "$SCAFFOLD_FILE" | copilot -p "Evaluate the options. Answer the 4 questions." --output-format text --available-tools=""
+cat "$SCAFFOLD_FILE" | gemini "Evaluate the options. Answer the 4 questions."
+cat "$SCAFFOLD_FILE" | opencode run "Evaluate the options. Answer the 4 questions."
+cat "$SCAFFOLD_FILE" | pi exec "Evaluate the options. Answer the 4 questions."
+```
+
+Claude also answers the scaffold independently before reading external responses.
+
+## Synthesis Framework
+
+### Three-Stage Output
+
+**Stage 1: Independent Responses** — Raw answers per model, clearly separated.
+
+```markdown
+## Council Evaluation: {topic}
+
+*Each model responded independently. No model saw another's output.*
+
+### Claude
+{Claude's 4 answers}
+
+### Codex
+{Codex's 4 answers}
+
+### Gemini
+{Gemini's 4 answers}
+```
+
+**Stage 2: Synthesis Matrix** — Structured comparison.
+
+```markdown
+| Model | Recommendation | Top Risk | Disqualifier |
+|-------|---------------|----------|-------------|
+| Claude | {option} | {risk} | {disqualifier or None} |
+| Codex | {option} | {risk} | {disqualifier or None} |
+| Gemini | {option} | {risk} | {disqualifier or None} |
+
+### Risk Convergence
+**High signal** (3+ models cite): {risks in 3+ responses}
+**Notable** (1-2 models cite): {risks from 1-2 responses}
+```
+
+**Stage 3: Verdict** — Consensus or fault lines.
+
+```markdown
+## Verdict
+**Council recommends {Option X}** ({count}-{dissent}).
+Primary risk: {most-cited risk}.
+```
+
+Or if no consensus:
+```markdown
+## Verdict
+**No consensus.** Fault lines: {Option A} vs {Option B}.
+Key disagreement: {fundamental question models disagree on}.
+```
+
+## Transcript Persistence
+
+Council responses are persisted via `save_transcript.py`:
+
+```bash
+sh "${CLAUDE_PLUGIN_ROOT}/scripts/_python.sh" "${CLAUDE_PLUGIN_ROOT}/scripts/jam/save_transcript.py" \
+  --session-id "{session_id}" \
+  --entries '{json_array_of_entries}'
+```
+
+Each model response becomes one entry:
+```json
+{
+  "session_id": "{session_id}",
+  "round": 1,
+  "persona_name": "Gemini",
+  "persona_type": "council",
+  "raw_text": "{full response}",
+  "timestamp": "{ISO timestamp}",
+  "entry_type": "council_response"
+}
+```
+
+Synthesis is appended as `entry_type: synthesis`, `persona_name: Council`.
+
+### Decision Records (via wicked-brain:memory)
+
+```
+Skill(skill="wicked-brain:memory", args="store \"Auth: JWT with 15min/7day expiry.\nCouncil: Claude (architect), Gemini (security), Codex (ux).\nConsensus: idempotency critical, session store risky at scale.\nUnique: Gemini flagged Redis cluster cost.\" --type decision --tags auth,council")
+```
+
+## Anti-Patterns
+
+```
+# BAD: No quorum check
+Run council with 0 external CLIs  # just Claude talking to itself
+
+# GOOD: Check quorum first
+which codex copilot gemini opencode pi    # need 2+ for real council
+
+# BAD: Sequential dispatch (one model could influence the next)
+response1=$(codex exec "$q"); echo "$response1" | gemini "$q"
+
+# GOOD: Parallel dispatch (all independent)
+codex exec "$q" &  gemini "$q" &  # simultaneous, isolated
+
+# BAD: Confidence scores in synthesis
+"Gemini is 85% confident..."  # LLMs produce uncalibrated numbers
+
+# GOOD: Risk convergence
+"3/3 models flagged this risk"  # count-based signal
+```
+
+## Important Rules
+
+1. **No confidence scores** — Use risk convergence (count-based) instead
+2. **No rounds** — Single structured pass; rounds break isolation
+3. **No editorial gloss on Stage 1** — Present raw answers without interpretation
+4. **Parallel only** — Never run CLIs sequentially
+5. **Claude participates** — Always a council member, same scaffold

package/skills/multi-model/refs/pi.md

@@ -0,0 +1,208 @@
+---
+phase_relevance: ["clarify", "design"]
+archetype_relevance: ["*"]
+---
+# Pi CLI — Usage Patterns
+
+`pi` is a coding-agent CLI (`@mariozechner/pi-coding-agent` on npm). Configurable across Google, OpenAI, Anthropic, and more; works as a council member via non-interactive `-p` mode with `@file` attachments.
+
+> **Note:** This is *not* the retired Inflection Pi-Mono CLI. That project ended; `pi` today is Mario Zechner's coding agent.
+
+## Installation and Setup
+
+```bash
+# Check if installed
+which pi
+
+# Install (npm global)
+npm install -g @mariozechner/pi-coding-agent
+
+# Configure provider — picks Google by default
+# Set provider API keys as env vars
+export GEMINI_API_KEY="..."       # default provider
+export OPENAI_API_KEY="..."
+export ANTHROPIC_API_KEY="..."
+
+# Override default provider/model per call
+pi --provider anthropic --model claude-sonnet-4-5 "..."
+pi --model openai/gpt-4o "..."
+pi --model sonnet:high "..."      # thinking-level shorthand
+```
+
+## Core Usage Patterns
+
+### Non-Interactive (`-p` / `--print`)
+
+```bash
+# Simple query
+pi -p "Evaluate this user onboarding flow for clarity and warmth"
+
+# Attach files via @file syntax
+pi -p "Review this welcome email for tone and empathy" @src/emails/welcome.md
+
+# Multiple attachments
+pi -p "Answer the 4 questions in the attached scaffold." @scaffold.md
+
+# Specific provider + model
+pi --provider anthropic --model claude-sonnet-4-5 -p "Analyze trade-offs" @options.md
+
+# Thinking level
+pi --thinking high -p "Solve this complex decision" @context.md
+
+# Ephemeral — do not save session
+pi --no-session -p "One-off question" @scaffold.md
+```
+
+### Interactive Session
+
+```bash
+# Start interactive
+pi
+
+# Start with initial prompt
+pi "Let's discuss the user experience implications of this design"
+
+# Continue previous session
+pi --continue "What did we decide?"
+
+# Select a session to resume
+pi --resume
+```
+
+### Decision Evaluation
+
+```bash
+# Human factors analysis
+pi -p "What are the human factors in this technical decision?" @decision.md
+
+# Communication review
+pi -p "How will different stakeholders interpret this announcement?" @announcement.md
+
+# User journey review
+pi -p "Where will users get confused or frustrated?" @flows/checkout.md
+```
+
+## Pi's Distinct Role in Multi-Model Sessions
+
+Pi is configurable across providers, so its "voice" depends on which model is selected. When pointed at a capable conversational model, it contributes empathetic perspective-taking and stakeholder framing — a useful counterweight to the code-editor framing of `aider` or the architectural framing of `codex`.
+
+```bash
+# Technical review via codex
+cat src/auth.py | codex exec "Technical security review"
+
+# Human-factor framing via pi (anthropic Sonnet)
+pi --provider anthropic --model claude-sonnet-4-5 -p \
+  "How will error states and edge cases affect the user experience?" @src/auth.py
+
+# Communication review via pi (google)
+pi -p "Is this message clear and empathetic to affected users?" @docs/deprecation-notice.md
+```
+
+## Strengths
+
+| Area | Description |
+|------|-------------|
+| Empathetic reasoning | Evaluates human factors and emotional impact |
+| Communication tone | Analyzes and improves tone, clarity, and warmth |
+| User advocacy | Champions end-user experience in technical decisions |
+| Balanced perspective | Provides nuanced trade-off analysis |
+| Stakeholder analysis | Considers diverse stakeholder responses |
+
+## Multi-Model Collaboration
+
+Pi provides the human-factor voice in council sessions:
+
+```bash
+CONTEXT="docs/auth-design.md"
+
+# Technical reviews
+cat "$CONTEXT" | codex exec "Architecture review: technical risks"
+cat "$CONTEXT" | gemini "Security and scalability analysis"
+
+# Human factors review (Pi's unique contribution)
+cat "$CONTEXT" | pi exec "User experience and human factors: where will users struggle? \
+  What error states are confusing? What emotional impact does this design have?"
+
+# Synthesize all perspectives
+```
+
+## Native Task Tracking
+
+```
+# Create review task
+TaskCreate(
+  subject="UX impact review: new auth flow",
+  metadata={
+    "event_type": "task",
+    "chain_id": "ux-review.root",
+    "source_agent": "multi-model:pi",
+    "priority": "P1"
+  }
+)
+
+# Get Pi's perspective and append to the task description via TaskUpdate
+# PI_REVIEW=$(cat design.md | pi exec "User experience analysis")
+# TaskUpdate(taskId, description="{previous}\n\nPi (user advocacy): ${PI_REVIEW}")
+```
+
+## Command Reference
+
+| Command | Description |
+|---------|-------------|
+| `pi [PROMPT]` | Interactive session |
+| `pi -p PROMPT` | Non-interactive, one-shot |
+| `pi -p PROMPT @FILE` | Non-interactive with file attached |
+| `pi --continue` | Continue previous session |
+| `pi --resume` | Select a session to resume |
+
+## Options Reference
+
+| Option | Description |
+|--------|-------------|
+| `-p`, `--print` | Non-interactive mode |
+| `--provider NAME` | `google` (default), `openai`, `anthropic`, `github-copilot`, etc. |
+| `--model PATTERN` | e.g. `claude-sonnet-4-5`, `openai/gpt-4o`, `sonnet:high` |
+| `--thinking LEVEL` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |
+| `--system-prompt TEXT` | Override default system prompt |
+| `--append-system-prompt TEXT` | Append to default system prompt |
+| `--no-tools` | Disable tool use (pure Q&A) |
+| `--no-session` | Do not persist this session |
+| `@FILE` | Attach file content to the message |
+
+## Council Sessions
+
+Pi is particularly valuable in `/wicked-garden:jam:council` sessions. Pi's voice represents
+user empathy and human-centered design in a panel of technical perspectives:
+
+```bash
+/wicked-garden:jam:council "Should we use biometric auth or PIN codes for mobile login?"
+# Pi's persona argues for user comfort, accessibility, and emotional safety
+# Technical personas argue implementation and security trade-offs
+```
+
+## Best Practices
+
+1. **Use for human factors** — Pi excels at evaluating user impact and communication
+2. **Review communications** — Error messages, announcements, onboarding copy all benefit from Pi
+3. **Pipe content** — Use stdin or `-f` for context
+4. **Council sessions** — Pi's empathetic voice is essential in decision councils
+5. **Track insights** — Record Pi's perspectives via native TaskUpdate or wicked-brain:memory
+
+## Common Prompts
+
+```bash
+# Error message review
+pi -p "Are these error messages helpful and non-alarming for users?" @src/errors.ts
+
+# Onboarding flow
+pi -p "Where will new users get confused? What's missing?" @docs/onboarding.md
+
+# Technical decision — user impact
+pi -p "What is the user impact of this technical choice? Who is most affected and how?" @decision.md
+
+# Stakeholder communication
+pi -p "How will engineers, managers, and end-users each interpret this announcement? What's unclear or alarming?" @announcement.md
+
+# Trade-off analysis
+pi --thinking high -p "Analyze these options from a human perspective. Which is more intuitive? Which creates more user burden?" @options.md
+```