@pi-agents/orchid 0.1.0-beta.0

package/prompts/parallel-handoff-plan.md

@@ -0,0 +1,59 @@
+---
+description: Parallel research/context builders into an implementation handoff plan
+---
+
+Use parallel subagents to understand the request, compare any external references, inspect the local codebase, and produce a grounded implementation handoff plan with a final implementation-ready meta-prompt.
+
+Primary request, target, or focus:
+
+$@
+
+Use `context: "fresh"` unless I explicitly ask for forked context. First read or fetch any URLs, issue links, PRs, screenshots, plans, docs, or local files mentioned in the request. Treat them as primary scope, not optional context.
+
+Use the `subagent` tool in chain mode:
+
+1. First step: a parallel group.
+   - `researcher`, when the request includes external references, APIs, libraries, docs, current best practices, or prompt-guidance research.
+   - `context-builder` for local codebase context.
+   - Add a second `context-builder` only when the scope is large enough to benefit from a separate implementation-strategy pass.
+
+2. Second step: a synthesis `context-builder` that reads the parallel findings and writes the final handoff plan and meta-prompt.
+
+Use distinct output paths under the chain directory. Example outputs:
+- `handoff/external-reference.md`
+- `handoff/local-context.md`
+- `handoff/implementation-strategy.md`
+- `handoff/final-handoff-plan.md`
+
+Do not write these artifacts into the repository unless I explicitly ask for persistent files.
+
+Role guidance:
+
+External reference researcher:
+- Study linked projects, docs, issues, examples, source code, or prompt guidance.
+- Identify the behavior, API, implementation files, constraints, and transferable ideas.
+- Conduct web research if needed. Use `web_search` if it is available; otherwise use whatever equivalent research capability is available.
+- Return source links, repo paths, key evidence, risks, and what matters for this implementation.
+
+Local context-builder:
+- Read all files needed to fully understand the local issue, not just the first match.
+- Follow imports, callers, tests, fixtures, configuration, docs, and adjacent patterns until the local problem, solution space, and validation path are clear.
+- Return relevant file paths and line ranges, current architecture, constraints, tests, risks, and open questions.
+
+Implementation-strategy context-builder, when used:
+- Compare the external evidence against the local architecture.
+- Propose the safest implementation shape, files likely to change, edge cases, validation commands, and decisions that need approval.
+- Stay review/planning-only unless I explicitly ask for implementation.
+
+Final synthesis context-builder:
+- Read the parallel outputs and produce one concise handoff plan.
+- Include what the feature/change should do, what the external reference teaches, what the local codebase implies, the recommended approach, likely files to change, constraints, non-goals, validation, risks, and unresolved questions.
+- End with a compact implementation-ready meta-prompt for the next worker/planner.
+
+After the chain returns, synthesize the result for me with:
+- the recommended approach;
+- artifact paths;
+- the final meta-prompt;
+- any questions or assumptions that remain.
+
+Do not start implementation from this command unless I explicitly ask for it.

package/prompts/parallel-research.md

@@ -0,0 +1,50 @@
+---
+description: Parallel subagents research
+---
+
+Launch parallel research subagents to build a grounded answer to the current question or decision.
+
+Use fresh context, not forked context, unless I explicitly ask for forked context. Researchers and scouts should inspect sources directly instead of relying on the main conversation history.
+
+Use a combination of `researcher` and `scout` subagents:
+- Use `researcher` for web, docs, standards, ecosystem, recent changes, benchmarks, and primary-source evidence.
+- Use `scout` for local codebase context, existing implementation patterns, repo constraints, and files that would be affected.
+
+Give each subagent a distinct angle. Unless I specify angles, use these three:
+
+1. External evidence
+   Use `researcher` to find current, authoritative sources: official docs, specs, release notes, benchmarks, issue threads, or primary explanations.
+
+2. Local code context
+   Use `scout` to inspect the repository for relevant files, existing patterns, constraints, tests, and likely integration points.
+
+3. Practical tradeoffs
+   Use `researcher` or `scout`, whichever fits the question, to compare options, risks, edge cases, maintenance cost, and what would be easiest to validate.
+
+Adapt the angles when the question calls for it:
+- Library/API questions: include official docs and recent examples.
+- Architecture decisions: include local module boundaries, dependency direction, and migration cost.
+- Debugging questions: include likely failure modes, local call paths, and exact error evidence.
+- UI/product questions: include user flow, accessibility, design precedent, and implementation constraints.
+- Time-sensitive topics: include a recent-developments angle and prefer 2026/2025 sources.
+
+Prefer two or three strong subagents over many vague ones. The parent agent should frame the question and assign angles; the child agents should research or scout, not invent broad plans.
+
+Ask each subagent to return concise findings with evidence:
+- file paths and line ranges for local findings
+- source links for external findings
+- confidence level and gaps
+- recommended next step or decision implication
+
+Do not ask subagents to edit files. This is a research pass only unless I explicitly ask for implementation.
+
+After the subagents return, synthesize the answer into:
+- what we know
+- what the local codebase implies
+- tradeoffs and risks
+- gaps or assumptions
+- the recommended next move
+
+If findings disagree, call out the disagreement instead of smoothing it over.
+
+$@

package/prompts/parallel-review.md

@@ -0,0 +1,54 @@
+---
+description: Parallel subagents review
+---
+
+Launch parallel reviewers for an adversarial review of the current work.
+
+Use fresh context, not forked context, unless I explicitly ask for forked context. Reviewers should inspect the repository, relevant instructions, and current diff directly from files and commands. Do not rely on the main conversation history.
+
+Give each reviewer a distinct angle. Generate the angles dynamically from the user's intent, the plan, the implemented code, and the current diff. If I specify angles, use mine. Otherwise, choose the highest-value review angles for this specific work.
+
+These are examples, not fixed defaults:
+
+1. Correctness and regressions
+   Check whether the change satisfies the request, preserves existing behavior, handles edge cases, and avoids hidden runtime failures.
+
+2. Tests and validation
+   Check whether tests or validation were added at the right layer, whether assertions are meaningful, and whether the chosen verification commands are enough.
+
+3. Simplicity and maintainability
+   Check for unnecessary complexity, duplicate structure, single-use wrappers, brittle abstractions, confusing names, verbosity, and cleanup that is clearly worth doing.
+
+Choose or adapt angles when the work calls for it:
+- TypeScript-heavy changes: include type safety, source-of-truth types, casts, and error-boundary discipline.
+- UI-heavy changes: include UX, accessibility, copy, and visual quality.
+- Security-sensitive changes: include unsafe input/output handling, auth boundaries, privacy, and data exposure.
+- Docs-heavy changes: include clarity, accuracy, completeness, reader flow, and non-robotic prose.
+- Large multi-file changes: consider a fourth reviewer for structural friction, module boundaries, and testability.
+
+Prefer three strong reviewers over many vague reviewers.
+
+Give every reviewer a specific task prompt naming its angle. Ask reviewers to return concise, evidence-backed findings with file/line references and suggested fixes. The response should be review feedback, not a context summary. Reviewers must not edit files unless I explicitly ask for a writer pass.
+
+While reviewers run, do your own narrow inspection if useful. After they return, synthesize the feedback into:
+- fixes worth doing now
+- optional improvements
+- feedback to ignore or defer, with a short reason
+
+Do not blindly apply every reviewer suggestion.
+
+Autofix mode: if the invocation contains the exact word `autofix`, treat it as workflow control, not review scope. Remove it before deciding the review target. After synthesis, apply only fixes worth doing now, validate, and summarize. Do not apply optional improvements unless explicitly requested. If there are no fixes worth doing now, do not edit.
+
+Without autofix mode, ask before applying fixes unless I already told you to address review feedback. When you ask, end with a compact numbered menu so I can respond with a number. Use wording suited to the findings, but include these choices when applicable:
+
+```text
+Reply with [1], [2], or further instructions:
+[1] Apply only the fixes worth doing now.
+[2] Apply the fixes worth doing now plus optional improvements.
+```
+
+Additional review target or focus from the slash command invocation:
+
+$@
+
+If the invocation provides a URL, issue link, file path, plan path, or freeform focus, treat it as the primary review scope. Read or fetch that target before assigning reviewer angles, and pass the target explicitly into each reviewer task.

package/prompts/review-loop.md

@@ -0,0 +1,41 @@
+---
+description: Review/fix loop until clean
+---
+
+Run a parent-orchestrated review loop for the requested work.
+
+Use the `subagent` tool. Keep the parent session as the loop controller and final decision-maker. Child subagents must receive concrete role-specific tasks; they must not run subagents or manage the loop themselves unless the parent intentionally selected an explicit fanout agent whose builtin `tools` includes `subagent` for that assigned fanout.
+
+Default to a maximum of 3 review rounds unless I specify a different cap. Count a review round each time fresh-context reviewers inspect the current diff after a worker pass. Stop early when reviewers find no blockers or fixes worth doing now.
+
+If the invocation includes an implementation request, first launch one async `worker` to implement the approved scope. If the current diff is already the target, start with review. The sequence can be launched up front as an async/background chain when the workflow is already clear, or continued as follow-up subagent runs after each async completion. For an initial chain, pass `async: true` so the main chat is unblocked; do not set `clarify: true` unless I explicitly want the foreground clarify UI. Use only one writer against the active worktree at a time unless I explicitly ask for isolated worktrees.
+
+For each review round, launch fresh-context `reviewer` agents in parallel. Reviewers must inspect the repository, relevant instructions, and current diff directly from files and commands. They must not rely on the main conversation history and must not edit files.
+
+Choose review angles from the actual change. Common angles are correctness/regressions, tests/validation, and simplicity/maintainability. Add security, performance, docs/API contracts, or user-flow validation when the work calls for it. Prefer three strong reviewers over many vague reviewers.
+
+After reviewers return, synthesize their feedback into:
+- blockers or scope/product/architecture decisions that need user approval;
+- fixes worth doing now;
+- optional improvements;
+- feedback to ignore or defer, with a short reason.
+
+Do not blindly apply every reviewer suggestion. If reviewers surface an unapproved product, scope, or architecture decision, pause and ask me before launching a fix worker.
+
+When an async implementation worker completes, treat its handoff as the transition into review, not as final completion, unless I explicitly asked for worker-only work, review-only output, or to stop after implementation.
+
+When there are fixes worth doing now and the workflow is implementation-authorized, launch one async forked `worker` to apply only those synthesized fixes. Ask it to preserve the approved scope, run focused validation, and report changed files, commands run with exit codes, validation evidence, surprises, and anything left undone.
+
+After a fix worker returns, run another review round only when it made material changes or addressed non-trivial findings. Do not keep looping for optional polish, speculative improvements, or findings already deferred by the parent.
+
+Stop and summarize when one of these is true:
+- reviewers find no blockers or fixes worth doing now;
+- remaining feedback is optional, speculative, or intentionally deferred;
+- reviewers surface an unapproved decision that needs me;
+- the max review-round cap is reached.
+
+On completion, inspect the final diff yourself, run or confirm focused validation where appropriate, and summarize the loop: rounds run, fixes applied, validation, remaining deferred items, and why the loop stopped.
+
+Additional target, implementation request, max-iteration cap, or review focus from the slash command invocation:
+
+$@

package/skills/orchid/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: orchid
+description: "Modular orchestration pipeline — 9-phase workflow for multi-agent development. Investigate → Decompose → Launch → Converge → Review → Cleanup. Each phase is a composable sub-skill with its own agents, Ralph loops, and dependencies. Triggers on 'pipeline', 'orchestration', 'orchid', 'decompose and launch', 'run the pipeline', 'start a sprint', 'run the orchid'. Always run orchid-doctor first."
+---
+
+# orchid — Orchestration Identification Pipeline
+
+**Version**: 2.0.0 (modular — sub-skills)
+**Role**: Orchestrator/PM meta-skill
+**Depends on**: See DEPENDENCIES section below.
+
+## ⛔ Orchestrator Identity (Non-Negotiable)
+
+```
+You DO NOT implement. You DO NOT edit code files.
+You investigate, document, decompose, delegate, and review.
+```
+
+| ✅ Your Job | ❌ NOT Your Job |
+|------------|----------------|
+| Read code, understand architecture | Write `.rs`, `.ts`, `.py` files |
+| Create GH EPIC + sub-issues | Debug compiler errors yourself |
+| Author `.ralph/` task files for lanes | Refactor code yourself |
+| Launch lane agents via `subagent()` dispatch | Fix failing tests yourself |
+| Wire `lib.rs` module declarations at convergence | Implement features yourself |
+| Run `cargo check && cargo test` to verify convergence | Write unit tests yourself |
+| Review lane output, request revisions | Make code changes beyond wiring |
+
+**Exception**: 1-2 line config edits (`lib.rs` module declarations, `Cargo.toml` dep additions) are allowed when wiring convergence.
+
+## ⛔ Delegation Rules (Non-Negotiable)
+
+### subagent() — Internal Work (USE THIS)
+
+For ALL coding, investigation, review, and testing delegation:
+
+```javascript
+subagent({
+  agent: "worker",
+  task: "Implement X...",
+  async: true,
+  skill: "ms-rust"        // project-specific skills injected here
+})
+```
+
+### interactive_shell — External Eval ONLY (DO NOT USE for work)
+
+`interactive_shell` is PROHIBITED for any implementation, debugging, review, or testing task.
+It is EXCLUSIVELY for launching external coding agent CLIs for evaluation/benchmarking:
+
+```javascript
+interactive_shell({ command: 'claude "Review the diffs"', mode: "dispatch" })
+```
+
+| Dimension | subagent() | interactive_shell |
+|-----------|-----------|-------------------|
+| Token cost | One agent | Two agents (you + child) |
+| Model control | Explicit per-task | Whatever pi launches with |
+| Context | Clean fork | TUI overlay burns context |
+| Progress | Structured output | Must poll/parse terminal |
+| Parallelism | Unlimited async | One per terminal tab |
+| Chaining | chain/parallel support | Manual glue |
+| Skills | Inject per-task | Inherit from parent |
+
+## Model Policy
+
+1. **Default**: Omit `model` param → subagent inherits orchestrator's model
+2. **User-specified**: Use exactly what the user requested
+3. **Ask if needed**: If user wants cost optimization, ask which model for workers
+4. **Agent-defined**: `.agents/*.md` files already declare model preferences — respect those
+
+**NEVER hardcode a model.** The model decision belongs to the user or the agent definition.
+
+## Pipeline Phases
+
+```
+PHASE 1-2: INVESTIGATE + DOCUMENT  →  orchid-investigate
+     ↓
+PHASE 3-5: ISSUES + DECOMPOSE + .ralph/ FILES  →  orchid-decompose
+     ↓
+PHASE 6: LAUNCH LANES  →  orchid-launch
+     ↓
+PHASE 7-8: CONVERGE + REVIEW  →  orchid-converge
+     ↓
+PHASE 9: GAP CLOSURE + CLEANUP  →  orchid-cleanup
+```
+
+**Before starting ANY phase — run orchid-doctor.**
+
+## Decision Trees
+
+### Which phase to load when?
+
+```
+User says "start pipeline" or "orchestrate X"
+  │
+  ├─→ Is this the first time? → orchid-doctor → orchid-investigate
+  │
+  ├─→ Do you have an investigation doc but no lanes? → orchid-decompose
+  │
+  ├─→ Do you have .ralph/ lane files but no running agents? → orchid-launch
+  │
+  ├─→ Are lanes running but reporting done? → orchid-converge
+  │
+  └─→ Is convergence done but review found issues? → orchid-cleanup
+```
+
+### What to do when a phase fails?
+
+```
+Phase fails
+  │
+  ├─→ Doctor fails → Fix missing deps. Do NOT proceed.
+  │
+  ├─→ Investigate fails → Likely permission or access issue. Check git/gh.
+  │
+  ├─→ Decompose fails → Lane overlap detected. Re-do ownership matrix.
+  │
+  ├─→ Launch fails → Subagent API down. Retry after 2 min. If persistent, implement directly as last resort.
+  │
+  ├─→ Converge fails → Build broken after merge. Identify which lane caused it. Send back to that lane's worker.
+  │
+  └─→ Cleanup fails → Gaps too large for single pass. Write additional lane file, re-launch.
+```
+
+### When to abort vs recover?
+
+| Situation | Action |
+|-----------|--------|
+| 1-2 lanes failed, rest green | Re-launch failed lanes only |
+| Build broken at convergence | Send specific fix task to offending lane's worker |
+| All lanes failed | Abort. Re-investigate. Root cause is likely in decomposition. |
+| Subagent API down >10 min | Abort. Queue for retry when API recovers. |
+| User requests stop | Abort gracefully. Archive .ralph/ state for resume. |
+| Reviewer finds critical issues | Do NOT proceed. Send fix task, re-review. |
+| Reviewer finds minor issues | Proceed to cleanup, include fixes in gap-closure. |
+
+## Sub-Skills
+
+| Sub-Skill | Phases | Primary Agent | Ralph Loop | Input | Output |
+|-----------|--------|---------------|------------|-------|--------|
+| `orchid-doctor` | Pre-flight | (orchestrator) | No | Project directory | ✅/⚠️/❌ health report |
+| `orchid-investigate` | 1-2 | scout, researcher | No (one-shot) | Project directory, GH repo | Architecture map, tracking doc, gap list |
+| `orchid-decompose` | 3-5 | planner | No (one-shot) | Tracking doc, gap list | EPIC + issues, .ralph/ lane files |
+| `orchid-launch` | 6 | worker, dev-1 | Yes (per lane) | .ralph/ lane files | Running subagents, commit SHAs |
+| `orchid-converge` | 7-8 | reviewer, tester | No | Commit SHAs, changed files | Green build, review report |
+| `orchid-cleanup` | 9 | worker | Yes (gap closure) | Review report, gap list | Clean repo, closed EPIC |
+
+## Dependencies
+
+### Required Agents
+
+| Agent | Role | Used By | Model Default |
+|-------|------|---------|---------------|
+| scout | Codebase recon | orchid-investigate | (inherit) |
+| researcher | Web research | orchid-investigate | (inherit) |
+| planner | Implementation planning | orchid-decompose | (inherit) |
+| worker | Implementation execution | orchid-launch, orchid-cleanup | (inherit) |
+| dev-1 | Focused coding | orchid-launch | (inherit) |
+| reviewer | Code review | orchid-converge | (inherit) |
+| tester | Test verification | orchid-converge | (inherit) |
+| brain | Architecture reasoning | Escalation | (inherit) |
+| delegate | Lightweight passthrough | Simple tasks | (inherit) |
+
+### Required Skills
+
+| Skill | Source | Version | Used By |
+|-------|--------|---------|---------|
+| pi-ralph-wiggum | npm (@tmustier) | ≥0.2.0 | orchid-launch, orchid-cleanup |
+| pi-subagents | npm | ≥0.25.0 | orchid-launch (all delegation) |
+| create-taskplane-task | npm (taskplane) | ≥0.30.0 | orchid-decompose |
+| multi-lane-orchestration | local | — | orchid-decompose, orchid-launch |
+
+### Project-Specific Skills (auto-detected)
+
+| Skill | When | Detection | Source |
+|-------|------|-----------|--------|
+| ms-rust | Rust projects | `Cargo.toml` present | ~/.pi/agent/skills/ms-rust-guidelines |
+| rustic-prompt | Rust projects | `Cargo.toml` present | ~/.pi/agent/skills/rustic-prompt |
+
+### Required Tools
+
+| Tool | Check | Required By | Fallback |
+|------|-------|-------------|----------|
+| git | `git --version` | All phases | None — mandatory |
+| gh | `gh auth status` | orchid-decompose | Create issues manually |
+| cargo | `cargo --version` | Rust projects | None — mandatory for Rust |
+| Telepathine bus | `agent_memory_telepath_list()` | orchid-launch, orchid-converge | Coordinate via git commits |
+
+## Quick-Start
+
+```
+1. /skill orchid-doctor        ← Verify all deps
+2. /skill orchid-investigate   ← Scout the codebase
+3. /skill orchid-decompose     ← Plan lanes + write .ralph/ files
+4. /skill orchid-launch        ← Fire lane agents
+5. /skill orchid-converge      ← Merge + review
+6. /skill orchid-cleanup       ← Close gaps + archive
+```
+
+## Real-World Example: RustAPI Pilot (May 2026)
+
+The patterns in OrchID were proven on the RustAPI project — a Go→Rust API gateway rewrite:
+
+- **3 parallel lanes** closed 26 issues in a single session
+- Lane 1: Clippy cleanup + E2E tests (12 tests)
+- Lane 2: Provider auth hardening
+- Lane 3: Claude SSE format conversion
+- Full reviewer gate with clippy verification and Go→Rust fidelity audits
+- Build was green at convergence with zero conflicts (file ownership matrix worked)
+
+**What worked**: Parallel dispatch with zero file overlap, Telepath coordination, reviewer gates.
+**What failed**: Initial attempt without ownership matrix caused merge conflicts; re-do with matrix resolved it.
+**Key lesson**: The file ownership matrix is not optional. It is the law.

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

@@ -0,0 +1,122 @@
+---
+name: orchid-cleanup
+description: "Phase 9 of the orchid pipeline. Close remaining gaps from review, fire cheap gap-closure subagent, archive .ralph/ files, final verification. Triggers on 'cleanup', 'close gaps', 'archive', 'finalize'."
+---
+
+# orchid-cleanup — Gap Closure + Archive
+
+**Parent**: `orchid`
+**Phase**: 9
+**Agents used**: worker (gap closure)
+**Ralph loop**: YES (gap closure is iterative)
+
+## What This Does
+
+After review, there will be gaps (missing docs, clippy lints, minor fixes).
+Don't bloat your window fixing them — delegate to a gap-closure subagent.
+
+## Step 1: Write Gap Closure File
+
+Create `.ralph/close-gaps.md` with concrete, copy-paste-able fixes:
+
+```markdown
+# Final Gap Closure — <Project>
+
+**EPIC**: #NNN
+**All lanes complete**: ✅ merged
+
+## Remaining Gaps
+
+### Gap 1: <description>
+- **File**: path/to/file.rs
+- **Fix**: <exact change needed>
+- **Severity**: minor
+
+### Gap 2: <description>
+- **File**: path/to/other.rs
+- **Fix**: <exact change needed>
+- **Severity**: clippy
+
+## Verification
+cargo check && cargo test && cargo clippy --workspace --all-targets -- -D warnings
+```
+
+## Step 2: Fire Gap-Closure Subagent
+
+```
+subagent({
+  agent: "worker",
+  task: "Read .ralph/close-gaps.md. Execute every item exactly as written. Verify with the commands listed in the Verification section. Commit + push to main after each fix.",
+  async: true
+})
+```
+
+Note: Model is inherited — no override unless user specified one.
+
+## Step 3: Archive .ralph/ Files
+
+```bash
+mkdir -p .ralph/archive
+mv .ralph/lane-* .ralph/*.state.json .ralph/*-output.md .ralph/archive/ 2>/dev/null
+mv .ralph/close-gaps.md .ralph/archive/ 2>/dev/null
+```
+
+**What remains in .ralph/:**
+- `.ralph/master-<project>.md` ← orchestrator master (keep forever)
+
+**What goes to archive:**
+- All lane task files
+- All state JSONs
+- All output captures
+- Close-gaps file
+
+**Rule**: Only `master-<project>.md` stays in `.ralph/`. Everything else goes to `archive/` on completion.
+This prevents accidentally re-launching completed lanes.
+
+## Step 4: Final Verification
+
+```bash
+cargo fmt --check
+cargo check --workspace
+cargo test --workspace
+cargo clippy --workspace --all-targets -- -D warnings
+```
+
+## Step 5: Close EPIC
+
+```bash
+# Verify all sub-issues are closed
+gh issue list --repo <org/repo> --state open --label "EPIC" | grep "#NNN"
+
+# Close EPIC if all sub-issues resolved
+gh issue close #NNN --repo <org/repo> --comment "All sub-issues resolved. Build green. Tests pass."
+```
+
+## Completion Criteria
+
+- [ ] All review gaps fixed and committed
+- [ ] Build green, 0 warnings, all tests pass
+- [ ] .ralph/ files archived (only master remains)
+- [ ] All sub-issues closed
+- [ ] EPIC closed with summary
+- [ ] Tracking doc updated to final state
+- [ ] Project memory updated with decisions and changes
+
+## Final Output
+
+```
+✅ orchid Pipeline Complete
+
+Project: <name>
+EPIC: #NNN
+Issues closed: <N>
+Lanes executed: A, B, (C)
+Tests: <N> passing
+Build: green
+Clippy: clean
+Review: all findings addressed
+Archive: .ralph/archive/
+Master: .ralph/master-<project>.md
+
+Pipeline duration: <time>
+```

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

@@ -0,0 +1,124 @@
+---
+name: orchid-converge
+description: "Phases 7-8 of the orchid pipeline. Pull all changes, wire module declarations, verify build, run reviewer gate. Triggers on 'converge', 'merge lanes', 'review code', 'wire modules'."
+---
+
+# orchid-converge — Merge + Review Gate
+
+**Parent**: `orchid`
+**Phases**: 7-8
+**Agents used**: reviewer, tester
+**Ralph loop**: No (convergence is orchestrator-directed)
+
+## Phase 7: Convergence
+
+### When
+
+All parallel lanes report ✅ done with commit SHAs on #general.
+
+### Orchestrator Actions
+
+#### 1. Pull All Changes
+
+```bash
+git pull origin main
+```
+
+#### 2. Wire Module Declarations
+
+This is the ONLY code the orchestrator touches — adding `pub mod` declarations in shared files:
+
+```rust
+// In lib.rs — add new module declarations from completed lanes
+pub mod buffer;   // from Lane A
+pub mod naming;   // from Lane A
+pub mod handlers; // from Lane B
+```
+
+#### 3. Run Verification
+
+```bash
+cargo fmt --check
+cargo check --workspace
+cargo test --workspace
+cargo clippy --workspace --all-targets -- -D warnings
+```
+
+#### 4. Decision
+
+- **Green** → Launch Lane C (if sequential lane exists) via orchid-launch
+- **Red** → Report failure to specific lane:
+
+```
+❌ Convergence failed:
+Lane B: specific error in <file> — please fix and re-push
+```
+
+## Phase 8: Review
+
+### Launch Reviewer
+
+```
+subagent({
+  agent: "reviewer",
+  task: "Review all changes from the <project> implementation.
+
+  Files: <list all files changed>
+  Criteria:
+  - All code has language-appropriate guideline markers
+  - Canonical docs on public items
+  - No unsafe code (or justified)
+  - 0 compiler warnings
+  - All tests pass
+  - File ownership matrix was respected (no cross-lane edits)
+  - Go→Rust fidelity (if applicable)
+  - No hardcoded secrets or internal paths
+
+  Report: issues found, severity (critical/major/minor), and recommended fixes."
+})
+```
+
+### Launch Tester
+
+```
+subagent({
+  agent: "tester",
+  task: "Run full test suite for <project>.
+
+  Commands:
+  cargo fmt --check
+  cargo check --workspace
+  cargo test --workspace
+  cargo clippy --workspace --all-targets -- -D warnings
+
+  Report: pass/fail counts, any regressions, coverage gaps."
+})
+```
+
+### Review Gate Checklist
+
+- [ ] `cargo check -- -D warnings` → 0 warnings
+- [ ] `cargo test` → all green
+- [ ] `cargo clippy` → clean
+- [ ] All public items have canonical docs
+- [ ] No `unsafe` code (or justified with safety comment)
+- [ ] File ownership respected (git diff shows expected file owners)
+- [ ] All sub-issues closed or linked to commit
+- [ ] EPIC acceptance criteria met
+- [ ] No hardcoded secrets or internal paths
+- [ ] Go→Rust fidelity verified (if applicable)
+
+## Completion Criteria
+
+- [ ] All lanes merged (green build)
+- [ ] Sequential lane (if any) launched and completed
+- [ ] Reviewer reports delivered
+- [ ] Tester reports delivered
+- [ ] All review issues addressed or escalated
+
+## Handoff
+
+Pass to `orchid-cleanup` with:
+- Review findings (critical/major/minor)
+- Remaining gaps list
+- Files needing fixes