@pi-agents/orchid 0.1.0-beta.0

package/skills/orchid/orchid-decompose/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: orchid-decompose
+description: "Phases 3-5 of the orchid pipeline. Create GH EPIC + sub-issues, build file ownership matrix, decompose into parallel lanes, write .ralph/ task files with code skeletons. Triggers on 'decompose', 'create issues', 'plan lanes', 'write ralph files'."
+---
+
+# orchid-decompose — Issues + Lanes + Task Files
+
+**Parent**: `orchid`
+**Phases**: 3-5
+**Agents used**: planner (primary)
+**Ralph loop**: No (one-shot planning)
+
+## ⛔ Naming Convention (THIS IS WHERE AGENTS SCREW UP)
+
+Ralph appends `.md` automatically. You NEVER include `.md` in the name.
+
+| ❌ Creates empty template | ✅ Uses existing content |
+|--------------------------|------------------------|
+| `/ralph start lane-a.md` | `/ralph start lane-a` |
+| `ralph_start({ name: "lane-a.md" })` | `ralph_start({ name: "lane-a" })` |
+
+Cleanup if broken:
+```bash
+rm .ralph/lane-a.md.md .ralph/lane-a_md.state.json
+```
+
+## Phase 3: Issues
+
+### Create EPIC
+
+```bash
+gh issue create --repo <org/repo> \
+  --title "EPIC: <Project> Rewrite/Feature for <Scale/Benefit>" \
+  --label "EPIC,P1,<tech>,<domain>,architecture" \
+  --body "## Context
+<From investigation tracking doc>
+
+## Scope
+### In Scope
+- <items>
+### Out of Scope
+- <items>
+
+## Stack
+| Component | Tech |
+|-----------|------|
+
+## Acceptance Criteria
+- <from tracking doc>
+
+## Sub-Issues
+| # | Title | Priority | Phase |
+|---|-------|----------|-------|
+"
+```
+
+### Create Sub-Issues (one per module/work-item)
+
+```bash
+gh issue create --repo <org/repo> \
+  --title "<Tech>: <Action Verb> — <Specific Deliverable>" \
+  --label "P0|P1|P2,<tech>,<domain>,phase-N" \
+  --body "## Parent EPIC: #NNN
+
+## Current State
+<what exists now>
+
+## Tasks
+- [ ] <specific implementation task>
+- [ ] <tests>
+- [ ] <documentation>
+
+## Files
+<expected file changes>
+
+## Dependencies
+<Blocked by / blocks>
+
+## Acceptance Criteria
+<verifiable conditions>
+"
+```
+
+### Cross-Link
+
+- EPIC body lists all sub-issues in a table
+- Each sub-issue links back to EPIC
+- Tracking doc links to EPIC + all sub-issues
+
+## Phase 4: Decompose into Lanes
+
+### File Ownership Matrix
+
+Build a table where every file is assigned to exactly ONE lane:
+
+| File | Owner | Lane | Action |
+|------|-------|------|--------|
+| `src/a.rs` | Lane A | A | CREATE |
+| `src/b.rs` | Lane B | B | EDIT |
+| `src/lib.rs` | Orchestrator | — | Wire at convergence |
+
+**Validation**: No file appears in more than one lane.
+
+### Lane Design
+
+| Lane | Issues | Depends On | Files |
+|------|--------|------------|-------|
+| Lane A | #AAA, #BBB | None | isolated set |
+| Lane B | #CCC, #DDD | None | isolated set |
+| Lane C | #EEE | A+B converged | depends on A+B types |
+
+Lanes A+B have ZERO shared files → can run concurrently.
+Lane C depends on A+B → runs after convergence.
+
+## Phase 5: Write .ralph/ Task Files
+
+### Master Orchestrator File
+
+`.ralph/master-<project>.md`:
+
+```markdown
+# <Project> — Orchestrator Master
+
+## ⛔ ORCHESTRATOR RULES
+(From orchid master SKILL.md — delegation rules, model policy)
+
+## Launch Commands
+/ralph resume lane-a-<name>
+/ralph resume lane-b-<name>
+
+## File Ownership Matrix
+(Table from Phase 4)
+
+## Lanes Summary
+Lane A: ...
+Lane B: ...
+Lane C: ... (blocked on convergence)
+
+## Coordination Protocol
+- Claim files on #general channel
+- Commit + push after each task
+- Report done with commit SHA
+
+## Verification
+cargo check && cargo test
+```
+
+### Lane Task Files (per lane)
+
+`.ralph/lane-<x>-<name>.md`:
+
+```markdown
+# Lane X: <Name>
+
+**Parent**: `.ralph/master-<project>.md`
+**EPIC**: #NNN
+**Issues**: #AAA, #BBB
+
+## Files You Own (ONLY these)
+| File | Action | Issue |
+
+## Files You MUST NOT Touch
+(list every file owned by other lanes)
+
+## Checklist
+- [ ] #AAA: specific task + tests
+- [ ] #BBB: specific task + tests
+- [ ] cargo check passes
+- [ ] cargo test passes
+- [ ] Commit + push to main
+- [ ] Report on #general with SHA
+
+## Code Skeletons
+(provide function signatures with doc comments — not just "implement X")
+
+## Verification
+(exact commands)
+
+## Notes
+(gotchas, type hints, Go reference paths)
+```
+
+**KEY**: Each lane file MUST contain explicit code skeletons — function signatures with doc comments.
+This gives the lane agent everything it needs without guessing.
+
+## Completion Criteria
+
+- [ ] EPIC created with full body
+- [ ] 10-15 sub-issues created, cross-linked
+- [ ] File ownership matrix built (zero overlaps validated)
+- [ ] 2-3 parallel lanes defined + 1 convergence lane
+- [ ] Master .ralph/ file written
+- [ ] Per-lane .ralph/ files written with code skeletons
+- [ ] Ready to proceed to orchid-launch
+
+## Handoff
+
+Pass to `orchid-launch` with:
+- Lane definitions and file ownership
+- .ralph/ file paths
+- Expected parallelism (which lanes concurrent, which sequential)

package/skills/orchid/orchid-doctor/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: orchid-doctor
+description: "Pre-flight health check for orchid pipeline. Verifies all agents, skills, tools, and connectivity are available before starting any orchestration phase. Triggers on 'run doctor', 'check deps', 'verify pipeline', 'health check'. Run this FIRST before any orchid phase."
+---
+
+# orchid-doctor — Dependency Health Check
+
+**Parent**: `orchid`
+**Phases**: Pre-flight (before Phase 1)
+**Agents used**: None (orchestrator runs directly)
+
+## What This Does
+
+Verifies all dependencies are available before starting the pipeline.
+Fail fast, fail clear — don't discover missing deps mid-pipeline.
+
+## Checklist
+
+Run each check and report status:
+
+### 1. Agent Availability
+
+Check each required agent exists in the subagent registry:
+
+```
+subagent({ action: "list" })
+```
+
+Verify present:
+- [ ] scout — codebase recon
+- [ ] researcher — web research
+- [ ] planner — implementation planning
+- [ ] worker — implementation execution
+- [ ] dev-1 — focused coding
+- [ ] reviewer — code review
+- [ ] tester — test verification
+- [ ] brain — architecture reasoning
+- [ ] delegate — lightweight passthrough
+
+### 2. Skill Availability
+
+Check each required skill is loadable:
+
+- [ ] `pi-ralph-wiggum` — Ralph loops (npm)
+- [ ] `pi-subagents` — Subagent dispatch (npm)
+- [ ] `create-taskplane-task` — Task authoring (npm)
+- [ ] `multi-lane-orchestration` — Lane coordination (local)
+
+### 3. Project-Specific Skills
+
+Detect project language and check:
+
+- [ ] If Rust project: `ms-rust` and `rustic-prompt` available
+- [ ] If TypeScript project: (future: ts-specific skills)
+- [ ] If Python project: (future: py-specific skills)
+
+Detection: look for `Cargo.toml`, `package.json`, `pyproject.toml`, etc.
+
+### 4. Tool Availability
+
+```bash
+git --version          # Required
+gh auth status         # Required for issue creation
+cargo --version        # Required for Rust projects
+```
+
+### 5. Telepathine Bus
+
+```
+agent_memory_telepath_list({ project: "<project-name>" })
+```
+
+- [ ] Bus is reachable
+- [ ] At least 1 agent connected (or orchestrator alone if pre-launch)
+
+### 6. Git State
+
+```bash
+git status --porcelain     # Check for uncommitted changes
+git branch --show-current  # Verify correct branch
+git remote -v              # Verify remote
+```
+
+- [ ] Repo is clean or changes are intentional
+- [ ] On correct branch
+- [ ] Remote configured
+
+### 7. Build State
+
+```bash
+# Rust
+cargo check --workspace 2>&1 | tail -5
+
+# TypeScript (future)
+# npm run build 2>&1 | tail -5
+```
+
+- [ ] Build passes (or document known failures)
+
+## Output Format
+
+```
+🔍 orchid Doctor — Dependency Health Check
+
+AGENTS:
+  ✅ scout       — available (glm-5.1-claude)
+  ✅ researcher  — available (glm-5.1-claude)
+  ✅ planner     — available (deepseek-v4-pro)
+  ✅ worker      — available (deepseek-v4-flash)
+  ✅ dev-1       — available (deepseek-v4-flash)
+  ✅ reviewer    — available (glm-5.1-claude)
+  ✅ tester      — available (deepseek-v4-flash)
+  ✅ brain       — available (inherit)
+  ✅ delegate    — available (inherit)
+
+SKILLS:
+  ✅ pi-ralph-wiggum          — npm
+  ✅ pi-subagents              — npm
+  ✅ create-taskplane-task     — npm
+  ✅ multi-lane-orchestration  — local
+
+PROJECT SKILLS (Rust detected):
+  ✅ ms-rust          — local
+  ✅ rustic-prompt    — local
+
+TOOLS:
+  ✅ git 2.47.1
+  ✅ gh 2.67.0 (authenticated)
+  ✅ cargo 1.85.0
+
+CONNECTIVITY:
+  ✅ Telepathine bus — 2 agents connected
+
+PROJECT:
+  ✅ Git clean (main branch)
+  ✅ Build green
+
+⚠️ WARNINGS: None
+❌ MISSING: None
+
+→ Pipeline ready. All 9 phases available.
+```
+
+Or on failure:
+
+```
+❌ MISSING:
+  - planner agent not found in subagent registry
+  - gh CLI not authenticated (run: gh auth login)
+
+⚠️ WARNINGS:
+  - Telepathine bus: 0 agents connected (lanes won't coordinate)
+  - 78 clippy warnings (non-blocking)
+
+→ Pipeline NOT ready. Fix 2 missing before proceeding.
+```
+
+## Decision
+
+- **All ✅**: Proceed with orchid-investigate
+- **⚠️ only**: Proceed with caution, document warnings
+- **❌ any**: STOP. Fix missing deps before continuing.

package/skills/orchid/orchid-investigate/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: orchid-investigate
+description: "Phases 1-2 of the orchid pipeline. Scout the codebase, map module structure, identify gaps, write comprehensive tracking document. Delegates to scout and researcher agents. Triggers on 'investigate codebase', 'scout the project', 'map modules', 'phase 1'."
+---
+
+# orchid-investigate — Scout + Document
+
+**Parent**: `orchid`
+**Phases**: 1-2
+**Agents used**: scout (primary), researcher (supplementary)
+**Ralph loop**: No (one-shot investigation)
+
+## What This Does
+
+Reads every source file, maps module structure, identifies gaps vs reference implementations, and produces a comprehensive tracking document.
+
+## Phase 1: Investigate
+
+### Delegation
+
+```
+subagent({
+  agent: "scout",
+  task: "Read all source files in <target>. Map module structure, identify gaps vs <reference>. Report: file list, module purposes, test coverage, parity status per file, compiler warnings."
+})
+```
+
+### What to Collect
+
+- [ ] Full file listing (per crate/package)
+- [ ] Module structure (file → purpose → dependencies)
+- [ ] Public API surface (exports, traits, types)
+- [ ] Test coverage status per module
+- [ ] Build warnings and errors
+- [ ] Gaps vs reference implementation (if applicable)
+- [ ] Cross-references to existing issues
+
+### Tools
+
+- `bash`: `find`, `grep`, `wc -l` for file discovery
+- `read`: Deep-read each source file
+- `gh issue list`: Check existing issues
+
+## Phase 2: Document
+
+### Output
+
+Write a tracking document at `docs/<topic>/<PROJECT>-<TECH>.md`
+
+### Template
+
+```markdown
+# <Project> — <Tech> Implementation Plan
+
+**Date**: YYYY-MM-DD
+**Status**: 🟡 Investigation complete
+**EPIC**: (to be created in orchid-decompose)
+
+## Executive Summary
+(3-5 sentences: what, why, current state)
+
+## Architecture Decisions
+
+| # | Question | Decision | Rationale | Decided |
+|---|----------|----------|-----------|---------|
+
+## Module Status
+
+| Module | File | Status | Tests | Parity | Issues |
+|--------|------|--------|-------|--------|--------|
+
+## Missing Modules
+
+| Reference Module | Purpose | Priority | Proposed Location |
+|-----------------|---------|----------|-------------------|
+
+## File Ownership Matrix (placeholder — filled in orchid-decompose)
+
+| File | Owner | Lane | Action |
+|------|-------|------|--------|
+
+## Acceptance Criteria
+
+## Build Commands
+
+## Related Documentation
+```
+
+## Completion Criteria
+
+- [ ] Every source file has been read
+- [ ] Module map is complete
+- [ ] Gaps are identified and prioritized
+- [ ] Tracking doc is written and committed
+- [ ] Ready to proceed to orchid-decompose
+
+## Handoff
+
+Pass to `orchid-decompose` with:
+- Tracking doc path
+- Gap list with priorities
+- Suggested lane decomposition

package/skills/orchid/orchid-launch/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: orchid-launch
+description: "Phase 6 of the orchid pipeline. Launch lane agents via subagent() with Ralph loops. Parallel dispatch, model selection, Telepath coordination, progress monitoring. Triggers on 'launch lanes', 'start agents', 'fire lanes', 'dispatch workers'."
+---
+
+# orchid-launch — Dispatch Lane Agents
+
+**Parent**: `orchid`
+**Phase**: 6
+**Agents used**: worker, dev-1 (per lane)
+**Ralph loop**: YES (per lane — each lane runs its own Ralph loop)
+**Coordination**: Telepathine bus
+
+## ⛔ Delegation Method
+
+**subagent(async) is the ONLY acceptable method for launching lane agents.**
+
+```
+interactive_shell is PROHIBITED for coding tasks.
+```
+
+See orchid master SKILL.md for the full delegation rules.
+
+## Model Selection
+
+| Scenario | Action |
+|----------|--------|
+| User specified a model | Use exactly what they said |
+| User said "optimize cost" | ASK which model for workers |
+| No model specified | **Omit `model` param** → inherits orchestrator's model |
+| Agent has model preference | Check `.agents/*.md` — respect it |
+
+**NEVER hardcode a model.** The model decision belongs to the user or the agent definition.
+
+## Launch Pattern
+
+### Parallel Lanes (A + B simultaneously)
+
+```
+// Lane A
+subagent({
+  agent: "worker",
+  task: "Read .ralph/lane-a-<name> completely. Work through every item in the checklist sequentially. Update the file as you progress. When finished with all items, run the verification commands listed, commit to main, push, and report done on #general with commit SHA.",
+  async: true,
+  skill: "ms-rust,pi-subagents"    // project-specific skills injected
+})
+
+// Lane B (parallel — fire immediately)
+subagent({
+  agent: "worker",
+  task: "Read .ralph/lane-b-<name> completely. Work through every item in the checklist sequentially. Update the file as you progress. When finished with all items, run the verification commands listed, commit to main, push, and report done on #general with commit SHA.",
+  async: true,
+  skill: "ms-rust,pi-subagents"
+})
+```
+
+### Why subagent(async) beats interactive_shell
+
+| Dimension | interactive_shell | subagent(async) |
+|-----------|-------------------|-----------------|
+| Context cost | Polls TUI output (burns tokens) | Zero — fire and forget |
+| Model control | Whatever pi launches with | Explicit per-task or inherit |
+| Output capture | Must query/poll | `output` file, `subagent status` |
+| Overhead | TUI render, terminal emulation | Pure text in/out |
+| Parallelism | One per terminal tab | Unlimited async spawns |
+
+### Task Prompt Requirements
+
+Each task prompt MUST include:
+1. "Read .ralph/<lane-file> completely" — subagents don't auto-load Ralph state
+2. "Work through the checklist sequentially" — ordered execution
+3. "Update the file as you progress" — progress tracking
+4. "Verify, commit, push" — quality gate
+5. "Report done on #general" — Telepath coordination
+
+### Sequential/Convergence Lane (after A+B done)
+
+Only after parallel lanes confirm completion:
+
+```
+subagent({
+  agent: "worker",
+  task: "Read .ralph/lane-c-<name> completely. Lanes A and B are done and merged. Work through the checklist, verify, commit, push.",
+  async: true,
+  skill: "ms-rust,pi-subagents"
+})
+```
+
+## Monitoring
+
+### Subagent Status
+
+```
+subagent({ action: "status", id: "<run-id-prefix>" })
+```
+
+### Telepathine Bus
+
+```
+// Check who's online
+agent_memory_telepath_list({ project: "<project>" })
+
+// Read lane progress
+agent_memory_telepath_inbox({ project: "<project>", channel: "general", limit: 20 })
+
+// Send steering message if stuck
+agent_memory_telepath_send({
+  channel: "general",
+  message: "Lane A: status check — how far along?",
+  project: "<project>"
+})
+```
+
+### Before Launch — Telepath Announcement
+
+```
+agent_memory_telepath_send({
+  channel: "general",
+  message: "🟢 Orchestrator online. Lanes launching: A (<files>), B (<files>). File matrix in .ralph/master-<project>.md",
+  project: "<project>"
+})
+```
+
+## Gap-Closure Mini-Lanes
+
+For trivial post-merge cleanup, write a short `.ralph/close-gaps.md` and fire:
+
+```
+subagent({
+  agent: "worker",
+  task: "Read .ralph/close-gaps.md. Execute every item exactly as written. Verify with cargo check && cargo test && cargo clippy. Commit + push to main.",
+  async: true
+})
+```
+
+Note: Model is inherited — no override unless user specified one.
+
+## Completion Criteria
+
+- [ ] Parallel lanes launched (async subagents)
+- [ ] Telepath announcement sent
+- [ ] Monitoring in place (bus + subagent status)
+- [ ] Waiting for lane completion reports on #general
+
+## Handoff
+
+When all parallel lanes report ✅ with commit SHAs → proceed to `orchid-converge`.

package/skills/ralph/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: pi-ralph-wiggum
+description: Long-running iterative development loops with pacing control and verifiable progress. Use when tasks require multiple iterations, many discrete steps, or periodic reflection with clear checkpoints; avoid for simple one-shot tasks or quick fixes.
+---
+
+# Ralph Wiggum - Long-Running Development Loops
+
+Use the `ralph_start` tool to begin a loop:
+
+```
+ralph_start({
+  name: "loop-name",
+  taskContent: "# Task\n\n## Goals\n- Goal 1\n\n## Checklist\n- [ ] Item 1\n- [ ] Item 2",
+  maxIterations: 50,        // Default: 50
+  itemsPerIteration: 3,     // Optional: suggest N items per turn
+  reflectEvery: 10          // Optional: reflect every N iterations
+})
+```
+
+## Loop Behavior
+
+1. **Write the task file**: Create `.ralph/<name>.md` with the task content. The tool does NOT create this file—you must write it yourself using the Write tool.
+2. Work on the task and update the file each iteration.
+3. Record verification evidence (commands run, file paths, outputs) in the task file.
+4. Call `ralph_done` to proceed to the next iteration.
+5. Output `<promise>COMPLETE</promise>` when finished.
+6. Stop when complete or when max iterations is reached (default 50).
+
+## User Commands
+
+- `/ralph start <name|path>` - Start a new loop.
+- `/ralph resume <name>` - Resume loop.
+- `/ralph stop` - Pause loop (when agent idle).
+- `/ralph-stop` - Stop active loop (idle only).
+- `/ralph status` - Show loops.
+- `/ralph list --archived` - Show archived loops.
+- `/ralph archive <name>` - Move loop to archive.
+- `/ralph clean [--all]` - Clean completed loops.
+- `/ralph cancel <name>` - Delete loop.
+- `/ralph nuke [--yes]` - Delete all .ralph data.
+
+Press ESC to interrupt streaming, send a normal message to resume, and run `/ralph-stop` when idle to end the loop.
+
+## Task File Format
+
+```markdown
+# Task Title
+
+Brief description.
+
+## Goals
+- Goal 1
+- Goal 2
+
+## Checklist
+- [ ] Item 1
+- [ ] Item 2
+- [x] Completed item
+
+## Verification
+- Evidence, commands run, or file paths
+
+## Notes
+(Update with progress, decisions, blockers)
+```
+
+## Best Practices
+
+1. Write a clear checklist with discrete items.
+2. Update checklist and notes as you go.
+3. Capture verification evidence for completed items.
+4. Reflect when stuck to reassess approach.
+5. Output the completion marker only when truly done.