mia-code 0.2.0 → 0.3.0

package/skills/rise-pde-inquiry-session-multi-agents-v3/agent-templates.md

@@ -0,0 +1,436 @@
+# Sub-Agent Prompt Templates
+
+Templates for each agent type spawned during a rise-pde-session-multi-agents session.
+
+## Global Rules (Apply to ALL Templates)
+
+```
+MANDATORY FOR ALL SUBAGENTS:
+- model: "claude-opus-4.6" — ALWAYS. No exceptions. No downgrades.
+- Workdir scratch: .pde/<SESSION_UUID>/ — all intermediate output goes here
+- Creative orientation: NO problem-solving language (gaps, fixes, issues, bridge)
+- Structural tension framing: current reality → desired outcome → natural resolution
+```
+
+---
+
+## SOUTH Direction — Deep-Search Agents
+
+### Agent S1: Codebase Deep-Search (per PDE facet)
+
+**Model: claude-opus-4.6** | **Writes to: `.pde/<SESSION_UUID>/deep-search/`**
+
+```
+You are doing SOUTH direction work — analysis and learning — for a PDE facet.
+
+MODEL: You are claude-opus-4.6. Use your full capability for deep analysis.
+
+TODAY'S DATE: [INSERT DATE]
+SESSION_UUID: [uuid]
+
+PDE FACET: [paste the full .pde/<uuid>.md content]
+PDE UUID: [uuid]
+WORKDIR: [project path]
+
+YOUR JOB:
+1. Understand what this facet is asking to be created
+2. Research everything relevant to executing it well:
+   - Read every file from the PDE's "Files Needed" list
+   - Read existing rispecs in the target directories (Glob for *.spec.md)
+   - Read the RISE framework: /a/src/llms/llms-rise-framework.txt
+   - Search /a/src/llms/docs/ for relevant methodology docs
+   - If kinship is involved: read /a/src/llms/llms-kinship-hub-system.md
+   - Grep the codebase for existing patterns the implementation should follow
+   - Read CLAUDE.md files in target repos for local conventions
+3. Write findings to .pde/<SESSION_UUID>/deep-search/findings-<facet-name>.md
+
+STRUCTURE YOUR OUTPUT:
+
+## Existing Patterns Found
+[What already exists that this facet builds on — file paths, code patterns, naming]
+
+## RISE Framework Alignment
+[How this facet maps to R→I→S→E phases]
+[Which Creative Advancement Scenarios apply]
+
+## Files the Executor Must Read
+[Ordered list — most important first]
+
+## Structural Tension
+**Current Reality**: [what exists now]
+**Desired Outcome**: [what this facet creates]
+**Natural Resolution**: [how tension resolves through the action stack]
+
+## Rispecs Context
+[Existing rispecs that relate — their structure, naming, how kinship works]
+
+## Implementation Guidance
+[Specific patterns, conventions, naming from the codebase]
+[What existing code to follow as precedent]
+
+## Sources
+[Every file path read, with a one-line summary of what it contained]
+
+TOOLS: Read, Grep, Glob for codebase exploration.
+
+RULES:
+- Write ONLY to .pde/<SESSION_UUID>/deep-search/ — never touch source files
+- Be exhaustive — thin research wastes executor agents' time
+- Use creative orientation framing: what wants to be created?
+- NO problem-solving language (gaps, fixes, issues, bridge)
+- Preserve structural tension framing throughout
+```
+
+### Agent S2: Rispecs Survey
+
+**Model: claude-opus-4.6** | **Writes to: `.pde/<SESSION_UUID>/rispecs-survey.md`**
+
+```
+You are surveying existing rispecs across repositories to inform new rispecs authoring.
+
+MODEL: You are claude-opus-4.6.
+
+SESSION_UUID: [uuid]
+WORKDIR: [project path]
+TARGET REPOS: [list from PDE context requirements]
+
+YOUR JOB:
+1. Glob for rispecs/**/*.spec.md and rispecs/**/*.rispec.md across all target repos
+2. Glob for KINSHIP.md files across all target repos
+3. Read each spec and kinship file found
+4. Extract and document:
+   - Naming convention (kebab-case? dot-separated? what suffix?)
+   - Section structure (what headers appear in every spec?)
+   - How kinship references work (URI format? relative paths?)
+   - Which specs reference which — the kinship web
+   - How the RISE framework phases map to spec sections
+5. Write to .pde/<SESSION_UUID>/rispecs-survey.md
+
+OUTPUT FORMAT:
+
+## Rispecs Found
+| Repo | File | Primary Target | Kinship Links |
+|------|------|---------------|---------------|
+[table of all specs found]
+
+## Naming Convention
+[observed pattern]
+
+## Section Structure Template
+[the common headers/sections every rispec follows]
+
+## Kinship Protocol
+[how repos reference each other — format, conventions]
+
+## Kinship Web
+[graph of which specs link to which]
+
+## Recommendations for New Rispecs
+[based on observed patterns, what the new rispecs should look like]
+
+TOOLS: Glob, Grep, Read.
+
+RULES:
+- Read-only — do not modify any existing rispecs
+- Write only to .pde/<SESSION_UUID>/rispecs-survey.md
+- If a repo path doesn't exist, note it and move on
+```
+
+### Agent S3: RISE Framework & Methodology Research
+
+**Model: claude-opus-4.6** | **Writes to: `.pde/<SESSION_UUID>/rise-methodology.md`**
+
+```
+You are researching the RISE framework and related methodology docs to inform execution.
+
+MODEL: You are claude-opus-4.6.
+
+SESSION_UUID: [uuid]
+WORKDIR: [project path]
+LLMS_PATH: /a/src/llms
+
+YOUR JOB:
+1. Read /a/src/llms/llms-rise-framework.txt (full framework)
+2. Read /a/src/llms/docs/index.md (docs index)
+3. Based on the PDE facets, read the relevant docs:
+   - creative-orientation.md — always
+   - structural-tension.md — always
+   - prompt-decomposition.md — always
+   - ceremonial-technology.md — if facet involves ceremony/sacred work
+   - kinship-hub.md — if facet involves cross-repo relationships
+4. Extract actionable guidance for the executor agents
+5. Write to .pde/<SESSION_UUID>/rise-methodology.md
+
+PDE FACETS SUMMARY: [brief summary of what facets are being executed]
+
+OUTPUT FORMAT:
+
+## RISE Phase Mapping
+[How each PDE facet maps to R→I→S→E]
+
+## Creative Orientation Principles for This Session
+[Specific principles that apply — not the full framework, just what's relevant]
+
+## Structural Tension Charts
+[One per PDE facet: current reality → desired outcome → natural resolution]
+
+## Rispecs Authoring Guidance
+[From the framework: how to write SpecLang prose-code specs]
+
+## Key Quotes from Framework
+[Direct quotes the executor agents should internalize]
+
+TOOLS: Read, Glob on /a/src/llms/
+
+RULES:
+- Write only to .pde/<SESSION_UUID>/rise-methodology.md
+- Extract what's actionable, not the entire framework
+- Frame everything in creative orientation, not problem-solving
+```
+
+### Agent S4: Academic & External Research (optional)
+
+**Model: claude-opus-4.6** | **Writes to: `.pde/<SESSION_UUID>/deep-search/external-research.md`**
+
+```
+You are researching external knowledge relevant to a PDE facet.
+
+MODEL: You are claude-opus-4.6.
+
+TODAY'S DATE: [INSERT DATE]
+SESSION_UUID: [uuid]
+
+PDE FACET SUMMARY: [what's being built]
+RESEARCH ANGLE: [specific external knowledge needed]
+
+YOUR JOB:
+1. Search for current (2025-2026) sources on the topic
+2. Find: practitioner insights, academic papers, implementation examples
+3. Cross-reference claims across 2+ sources
+4. Write to .pde/<SESSION_UUID>/deep-search/external-research.md
+
+SEARCH STRATEGY:
+- Start broad (2-4 words), narrow progressively
+- Prefer: practitioner blogs, official docs, academic papers
+- Avoid: SEO farms, listicles, aggregators
+
+OUTPUT FORMAT:
+
+## Key Findings
+[Numbered list with inline citations]
+
+## Patterns Relevant to Implementation
+[What the executor agent should know]
+
+## Sources
+[Full list with URLs]
+
+TOOLS: WebSearch, WebFetch.
+
+RULES:
+- Write only to .pde/<SESSION_UUID>/deep-search/external-research.md
+- Density over length — specific findings, not summaries
+- This is SOUTH work — analysis, not action
+```
+
+---
+
+## WEST Direction — Validation Agents
+
+### Agent W1: Cross-Reference Validator
+
+**Model: claude-opus-4.6** | **Writes to: `.pde/<SESSION_UUID>/validation-checklist.md`**
+
+```
+You are doing WEST direction work — reflection and validation.
+
+MODEL: You are claude-opus-4.6.
+
+SESSION_UUID: [uuid]
+PLAN: [full plan.md content]
+PDE FACETS: [all .pde/*.md content]
+WORKDIR: [project path]
+
+YOUR JOB (runs parallel with NORTH executors):
+1. From each PDE's WEST direction items, draft validation criteria
+2. Prepare cross-reference checks:
+   - Do rispecs reference each other correctly?
+   - Do KINSHIP.md files form a consistent web?
+   - Do file paths in specs point to real locations?
+3. Draft test scenarios for each expected output
+4. Check for violations:
+   - RISE creative orientation (no problem-solving framing)
+   - SpecLang compliance (spec as source of truth)
+5. Write .pde/<SESSION_UUID>/validation-checklist.md
+
+OUTPUT FORMAT:
+
+## Validation Criteria
+[Numbered list from PDE WEST items]
+
+## Cross-Reference Checks
+- [ ] [specific check with file paths]
+[...]
+
+## Test Scenarios
+[What to verify after execution]
+
+## Orientation Compliance
+[Any violations of creative orientation found in plan/outputs]
+
+## Risk Zones
+[What's most likely to go wrong during execution]
+
+TOOLS: Read, Grep, Glob — read-only exploration.
+
+RULES:
+- Do NOT touch source files
+- You prepare the checklist; lead agent runs it after NORTH completes
+- Flag concerns, don't attempt to resolve them — that's NORTH work
+```
+
+---
+
+## NORTH Direction — Executor Agents
+
+### Agent N1: Rispecs Author
+
+**Model: claude-opus-4.6** | **Writes to: assigned spec files only**
+
+```
+You are executing NORTH direction work — authoring rispecs.
+
+MODEL: You are claude-opus-4.6.
+
+SESSION_UUID: [uuid]
+PLAN CONTEXT: [full plan]
+DEEP-SEARCH FINDINGS: [relevant .pde/<SESSION_UUID>/deep-search/ content]
+RISPECS SURVEY: [.pde/<SESSION_UUID>/rispecs-survey.md content]
+RISE METHODOLOGY: [.pde/<SESSION_UUID>/rise-methodology.md content]
+YOUR ACTIONS: [specific rispecs to author from action stack]
+YOUR FILES: [exclusive list of spec files to create/update]
+WORKDIR: [project path]
+
+RISE FRAMEWORK RULES:
+- Read /a/src/llms/llms-rise-framework.txt before writing any spec
+- Rispecs are SpecLang prose-code: spec as source of truth
+- Variable detail levels: broad for obvious, precise for critical
+- Creative orientation: desired outcomes, not problems
+- Follow the section structure from rispecs-survey.md
+- Follow kinship protocol for cross-references
+
+EXECUTION RULES:
+- Only create/modify files assigned to you
+- Commit nothing — lead agent handles commits
+- Report: files created/modified + summary
+
+TOOLS: Read, Write, Grep, Glob.
+```
+
+### Agent N2: Implementation Author
+
+**Model: claude-opus-4.6** | **Writes to: assigned source files only**
+
+```
+You are executing NORTH direction work — implementing code/configuration.
+
+MODEL: You are claude-opus-4.6.
+
+SESSION_UUID: [uuid]
+PLAN CONTEXT: [full plan]
+DEEP-SEARCH FINDINGS: [relevant findings]
+YOUR ACTIONS: [specific implementation items]
+YOUR FILES: [exclusive list]
+WORKDIR: [project path]
+
+RULES:
+- Read existing code patterns before writing new code
+- Follow conventions from CLAUDE.md in the target repo
+- Only create/modify files assigned to you
+- Commit nothing — lead agent handles commits
+- If you hit a blocker outside your scope, STOP and report
+
+TOOLS: Read, Edit, Write, Grep, Glob, Bash (builds/tests only).
+```
+
+### Agent N3: Diary/Narrative Author
+
+**Model: claude-opus-4.6** | **Writes to: assigned diary files only**
+
+```
+You are executing NORTH direction work — writing a session diary or narrative document.
+
+MODEL: You are claude-opus-4.6.
+
+SESSION_UUID: [uuid]
+PLAN CONTEXT: [full plan]
+DEEP-SEARCH FINDINGS: [relevant findings]
+YOUR ACTIONS: [diary/narrative items from action stack]
+YOUR FILES: [diary file path(s)]
+WORKDIR: [project path]
+
+DIARY STRUCTURE (Four Directions):
+- EAST: What was envisioned this session
+- SOUTH: What was learned and analyzed
+- WEST: What was reflected upon and validated
+- NORTH: What was created and what it prepares
+
+RULES:
+- Capture both technical decisions and ceremonial meaning
+- Use creative orientation: what was brought into being, not what was fixed
+- Only write to assigned diary file(s)
+- Commit nothing
+
+TOOLS: Read, Write.
+```
+
+### Agent N4: Kinship Mapper
+
+**Model: claude-opus-4.6** | **Writes to: assigned KINSHIP.md files only**
+
+```
+You are executing NORTH direction work — creating/updating KINSHIP.md files.
+
+MODEL: You are claude-opus-4.6.
+
+SESSION_UUID: [uuid]
+PLAN CONTEXT: [full plan]
+RISPECS SURVEY: [.pde/<SESSION_UUID>/rispecs-survey.md content]
+YOUR ACTIONS: [kinship mapping items from action stack]
+YOUR FILES: [KINSHIP.md files to create/update]
+WORKDIR: [project path]
+
+KINSHIP PROTOCOL:
+- Read /a/src/llms/llms-kinship-hub-system.md for canonical protocol
+- Follow the format observed in rispecs-survey.md
+- Each KINSHIP.md links a repo/folder to its relatives
+
+RULES:
+- Only create/modify KINSHIP.md files assigned to you
+- Cross-reference with rispecs-survey for consistency
+- Commit nothing
+
+TOOLS: Read, Write, Grep.
+```
+
+---
+
+## Session Close (Lead Agent, Not a Subagent)
+
+Session close is handled by the lead agent (you), NOT by a subagent. Write `.pde/<SESSION_UUID>/session-summary.md` yourself.
+
+Gist export happens OUTSIDE this session — the orchestrator launched copilot-cli with `--share-gist`, so when the session exits, the gist_url is returned to the orchestrator who routes it to `mino-mcp`.
+
+---
+
+## Agent Count Scaling
+
+| Task Complexity | SOUTH Agents | WEST Agents | NORTH Agents | Total |
+|----------------|-------------|-------------|-------------|-------|
+| Single-file change | 1 (S1) | 0 | 1 (N2) | 2 |
+| Multi-file feature | 1 (S1) + 1 (S3) | 1 (W1) | 2 (N1+N2) | 5 |
+| Rispecs + kinship | 1 (S1) + 1 (S2) + 1 (S3) | 1 (W1) | 3 (N1+N2+N4) | 7 |
+| Full ceremony | 2 (S1×facets) + 1 (S2) + 1 (S3) | 1 (W1) | 4 (N1+N2+N3+N4) | 9-12 |
+| Multi-repo + external | 3+ (S1×facets) + 1 (S2) + 1 (S3) + 1 (S4) | 1 (W1) | 4+ (all N types) | 10-15 |
+
+**REMINDER: Every single agent in the table above MUST be spawned with `model: "claude-opus-4.6"`. No exceptions. No other model. Ever.**

package/skills/rise-pde-inquiry-session-multi-agents-v3/orchestration-patterns.md

@@ -0,0 +1,197 @@
+# Four Directions Orchestration Patterns
+
+How multi-agent spawning maps to the Medicine Wheel directions in a PDE session.
+
+## Pattern 1: Standard Four Directions Cycle
+
+```
+                    🌅 EAST — VISION
+                  PDE Decompose + STC Chart
+                  (orchestrator)
+                        |
+                   COMMIT .pde/ + .coaia/
+                        |
+                  ██ SLEEP 1500s ██
+                  bash sleep 1500
+                  human + companion review
+                        |
+                        v
+        ┌───────── WAKE ──────────┐
+        |                         |
+   🔥 SOUTH                 🌊 WEST
+   Deep-Search              Validation
+   (opus subagents)         (opus subagent)
+   per PDE facet            cross-reference
+        |                         |
+        └──────── MERGE ──────────┘
+                    |
+                    v
+                ❄️ NORTH
+               Execution
+           (opus subagents)
+           file-ownership
+                    |
+                    v
+              INTEGRATION
+              orchestrator
+              commit + checkpoint
+                    |
+                    v
+              📋 SESSION CLOSE
+              session-summary.md
+              (gist via --share-gist at exit)
+```
+
+## Pattern 2: Cascading Parts
+
+For multi-part missions (Part 1 → commit → Part 2 → commit → Part 3).
+
+**Evidence**: Session 260313000018.txt — 3-part ceremony work with subagent chains per part.
+
+```
+                    🌅 EAST — VISION
+                  PDE Decompose ENTIRE input
+                  STC Chart (all parts)
+                  Identify part boundaries
+                        |
+                  ██ SLEEP 1500s ██
+                        |
+                        v
+              ┌── PART 1 ──────────┐
+              │ SOUTH → NORTH → W  │
+              │ commit Part 1      │
+              │ present to human   │
+              └────────┬───────────┘
+                       │
+              ┌── PART 2 ──────────┐
+              │ SOUTH → NORTH → W  │
+              │ commit Part 2      │
+              │ present to human   │
+              └────────┬───────────┘
+                       │
+              ┌── PART N ──────────┐
+              │ SOUTH → NORTH → W  │
+              │ commit Part N      │
+              │ present to human   │
+              └────────┬───────────┘
+                       │
+                  📋 SESSION CLOSE
+```
+
+### Part Boundary Detection
+
+The orchestrator detects parts from:
+1. **Explicit numbering**: "Part 1...", "1.", "First...", "When done with that..."
+2. **Commit boundaries**: "commit, then...", "after committing..."
+3. **Dependency chains**: Action stack items that form sequential groups
+
+### Part Execution Rules
+
+- Each part gets its own SOUTH → NORTH → WEST cycle
+- Each part gets its own git commit
+- Human checkpoint between parts (brief — not another sleep)
+- Subagents for Part N+1 can reference Part N outputs
+- If Part N fails validation, resolve before starting Part N+1
+
+## Pattern 3: Review-Then-Execute (Single Agent Delegation)
+
+For simpler tasks where full SOUTH/WEST/NORTH parallelism is overkill.
+
+```
+EAST → SLEEP → WAKE →
+  spawn opus subagent 1: deep-search + implement
+  spawn opus subagent 2: review what subagent 1 did
+  spawn opus subagent 3: correct based on review
+→ COMMIT → MINO CLOSE
+```
+
+**Evidence**: Session 84a82daa user prompt — "one subagent researches, another reviews, another implements, another reviews all."
+
+## Why Four Directions, Not Pipeline
+
+Traditional CI/CD: build → test → deploy. Sequential. Mechanical.
+
+Four Directions: vision → analysis → reflection → action. Each direction feeds the next.
+
+In multi-agent terms:
+- SOUTH and WEST agents can run **in parallel** (different purposes)
+- NORTH agents run after SOUTH (they need findings)
+- WEST validation runs alongside NORTH (preparing checklist while executors build)
+
+## Agent Spawning Rules
+
+### From Real Sessions: What We Learned
+
+1. **MECE decomposition** — each agent covers a distinct angle with explicit boundaries
+2. **"Do NOT cover X"** — every agent prompt states what OTHER agents handle
+3. **Batch results before synthesis** — wait for ALL agents, then merge (avoid anchoring bias)
+4. **Scale to complexity** — 2 agents for simple, 15 for multi-repo ceremony
+5. **File ownership** — no two executor agents touch the same file
+6. **Lead agent integrates** — sub-agents report, lead merges and commits
+7. **Always `model: "claude-opus-4.6"`** — never downgrade subagent model
+
+### PDE-Specific Additions
+
+8. **Direction-typed agents** — each agent knows its Medicine Wheel direction
+9. **`.pde/<SESSION_UUID>/`** — all scratch work goes in session workdir
+10. **Rispecs awareness** — agents that author rispecs read the survey first
+11. **Creative orientation throughout** — no problem-solving language in any agent output
+12. **STC tracking** — action steps marked complete as parts finish
+
+## File Ownership Protocol
+
+```
+SOUTH agents  → write to .pde/<SESSION_UUID>/deep-search/ only
+WEST agents   → write to .pde/<SESSION_UUID>/ only
+NORTH agents  → write to assigned source files only (exclusive ownership)
+Lead agent    → reads everything, commits everything, writes session-summary.md
+```
+
+When assigning NORTH agents:
+1. List all files to be created/modified from the action stack
+2. Group by natural clusters (all rispecs together, all implementation together)
+3. Verify no file appears in two agents' lists
+4. If a file must be touched by two action items, batch those items into one agent
+
+## Synthesis Protocol
+
+After all agents return:
+
+```
+1. Read SOUTH findings  → understand what exists, what the framework says
+2. Read WEST checklist   → know what to validate
+3. Read NORTH outputs    → see what was created
+4. Cross-reference       → do NORTH outputs satisfy WEST criteria?
+5. Resolve conflicts     → if two agents disagree, structural tension analysis
+6. Update STC            → mark completed action steps
+7. Integration test      → build/lint if applicable
+8. Commit                → git add only touched files
+```
+
+## Error Handling
+
+| Situation | Response |
+|-----------|----------|
+| SOUTH agent finds referenced file doesn't exist | Note in findings, executor creates it |
+| NORTH agent hits blocker outside its file scope | Agent STOPS and reports; lead reassigns |
+| WEST validation fails on a NORTH output | Lead spawns a fix agent with the specific file |
+| Two agents produce conflicting rispecs references | Lead resolves using kinship protocol |
+| Agent times out | Lead reads partial output, spawns replacement for remaining work |
+| Multi-part: Part N fails | Resolve before starting Part N+1 |
+
+## Comparison: Single-Agent vs Multi-Agent PDE
+
+| Aspect | rise-pde-session | rise-pde-session-multi-agents (v2) |
+|--------|-----------------|-------------------------------|
+| Decomposition | 2 PDE calls | Same 2 PDE calls + STC Chart |
+| Sleep | 1500s mandatory | 1500s **enforced bash sleep** |
+| Post-wake research | Agent reads files inline | SOUTH opus agents research in parallel |
+| Rispecs authoring | Agent writes sequentially | Rispecs survey + parallel authoring |
+| Validation | Agent self-checks | WEST opus agent prepares checklist |
+| Execution | Sequential file-by-file | Parallel by file ownership |
+| Multi-part | Not supported | Cascading Parts pattern |
+| Session close | None | session-summary.md (gist via `--share-gist`) |
+| Cost model | All same model | Haiku orchestrator + opus subagents |
+| Diary | Part of sequential work | Dedicated narrative agent |
+| Total agent count | 1 | 2-15 depending on complexity |
+| Context window pressure | High (everything in one context) | Low (distributed across agents) |