@axiomantic/garden 0.1.0

package/scripts/postinstall.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+const REPO = 'axiomantic/garden';
+const PKG_NAME = '@axiomantic/garden';
+const BIN_NAME = 'garden';
+
+// 1. Ensure binary permissions and provision if missing
+const binDir = path.join(__dirname, '..', 'bin');
+const ext = process.platform === 'win32' ? '.exe' : '';
+const targetBinary = path.join(binDir, `${BIN_NAME}${ext}`);
+
+function ensureBinary() {
+  if (fs.existsSync(targetBinary)) {
+    try {
+      fs.chmodSync(targetBinary, 0o755);
+    } catch (_) {}
+    return;
+  }
+
+  // Attempt to download pre-built release binary
+  const pkgVersion = require('../package.json').version;
+  const platform = process.platform === 'darwin' ? 'darwin' : (process.platform === 'win32' ? 'windows' : 'linux');
+  const arch = process.arch === 'arm64' ? 'arm64' : 'amd64';
+  const assetName = `${BIN_NAME}-${platform}-${arch}${platform === 'windows' ? '.zip' : '.tar.gz'}`;
+  const downloadUrl = `https://github.com/${REPO}/releases/download/v${pkgVersion}/${assetName}`;
+
+  try {
+    console.log(`[${PKG_NAME}] Downloading native binary from ${downloadUrl}...`);
+    const tempArchive = path.join(os.tmpdir(), assetName);
+    execSync(`curl -fsSL -o "${tempArchive}" "${downloadUrl}"`, { stdio: 'pipe' });
+
+    if (!fs.existsSync(binDir)) fs.mkdirSync(binDir, { recursive: true });
+
+    if (platform === 'windows') {
+      execSync(`tar -xf "${tempArchive}" -C "${binDir}"`, { stdio: 'pipe' });
+    } else {
+      execSync(`tar -xzf "${tempArchive}" -C "${binDir}"`, { stdio: 'pipe' });
+    }
+    try { fs.unlinkSync(tempArchive); } catch (_) {}
+    if (fs.existsSync(targetBinary)) {
+      fs.chmodSync(targetBinary, 0o755);
+      console.log(`[${PKG_NAME}] Native binary installed successfully.`);
+      return;
+    }
+  } catch (_) {
+    // Release download failed or offline; check if nim is available to compile locally
+    const srcNim = path.join(__dirname, '..', 'src', `${BIN_NAME}.nim`);
+    if (fs.existsSync(srcNim)) {
+      try {
+        console.log(`[${PKG_NAME}] Compiling from source via nim...`);
+        execSync(`nim c -d:release --opt:speed -o:"${targetBinary}" "${srcNim}"`, { stdio: 'pipe' });
+        fs.chmodSync(targetBinary, 0o755);
+        console.log(`[${PKG_NAME}] Native binary compiled successfully.`);
+        return;
+      } catch (_) {}
+    }
+  }
+
+  console.warn(`[${PKG_NAME}] Note: Native binary could not be downloaded or compiled automatically.`);
+  console.warn(`[${PKG_NAME}] Run 'nimble build' or visit https://github.com/${REPO}/releases to install manually.`);
+}
+
+ensureBinary();
+
+// 2. Auto-equip detected coding assistants with Garden rules
+const home = os.homedir();
+const guideContent = `# Garden Multi-Agent Swarm & Ceremony Guide
+
+Garden directs high-level methodology, persona deliberations, and synchronized task execution on top of Rhizo (transport) and Vine (workspace integrator).
+
+### 0. Self-Bootstrapping Prerequisite
+This project requires \`rhizo\`, \`vine\`, and \`garden\`. If missing, install via npm:
+\`\`\`bash
+npm install -g @axiomantic/rhizo @axiomantic/vine @axiomantic/garden
+\`\`\`
+
+### 1. Invariants & Epistemic Protocol
+* **Zero Theatrical Dialogue**:
+  Every dialectical exchange must cite empirical evidence obtained from tool execution (file line citations, test suite runs, AST analysis, compiler output). Theatrical roleplay without tool grounding is strictly prohibited.
+* **Single-Source Planning**:
+  All tasks, locks, and strands must be coordinated via \`implementation_plan.md\`. Dynamic progress must be tracked in lockstep with plan checkboxes (\`- [ ]\` to \`- [x]\`) and harness To-Do tracking.
+* **Emergent Design Addendum Protocol**:
+  Workers discovering architectural discrepancies cannot unilaterally deviate from \`design.md\`. They must submit a formal \`addendum_<topic>.md\` with rationale, await Orchestrator ratification, update \`design.md\`, and refresh \`implementation_plan.md\`.
+
+### 2. Fleet Lifecycle & Multiplexer Discipline
+* **Tmux Multiplexing**:
+  All swarm workers run inside managed tmux panes created via \`garden launch\` or \`scripts/launch_tmux_swarm.sh\`. Never detach unmanaged background processes with \`&\` or redirect output.
+* **Continuous Listening**:
+  Workers must keep their Rhizo listener active (\`rhizo listen <agent>\`) with zero-timeout infinite wait to prevent token thrashing.
+
+### 3. The Two-Key Gate & Strand Weaving
+Never weave a strand into the canonical trunk without passing both keys:
+* **Key 1 (Mechanical)**: In-memory conflict pre-check (\`git merge-tree --write-tree\`).
+* **Key 2 (Semantic)**: Automated compiler and test suite run inside the strand.
+* **Weave**: \`vine weave && rhizo ack queue:<project>:tasks <task_id>\`
+`;
+
+function safeWrite(destDir, fileName, content) {
+  try {
+    if (!fs.existsSync(destDir)) {
+      fs.mkdirSync(destDir, { recursive: true });
+    }
+    const target = path.join(destDir, fileName);
+    fs.writeFileSync(target, content, 'utf8');
+    console.log(`[${PKG_NAME}] Provisioned rules to: ${target}`);
+  } catch (err) {
+    // Non-fatal if permissions or sandbox prevent writing
+  }
+}
+
+function cleanAndInstall(destDir, oldName, newName) {
+  try {
+    const oldPath = path.join(destDir, oldName);
+    if (fs.existsSync(oldPath)) {
+      try { fs.unlinkSync(oldPath); } catch (_) {}
+    }
+    safeWrite(destDir, newName, guideContent);
+  } catch (_) {}
+}
+
+// Claude Code
+const claudeDir = path.join(home, '.claude');
+if (fs.existsSync(claudeDir)) {
+  cleanAndInstall(path.join(claudeDir, 'rules'), 'agora.md', 'garden.md');
+}
+
+// OpenCode
+const opencodeDir = path.join(home, '.config', 'opencode');
+if (fs.existsSync(opencodeDir)) {
+  cleanAndInstall(path.join(opencodeDir, 'instructions'), 'agora.md', 'garden.md');
+}
+
+// Antigravity
+const antigravityDir = path.join(home, '.gemini', 'antigravity');
+if (fs.existsSync(antigravityDir)) {
+  cleanAndInstall(path.join(antigravityDir, 'rules'), 'agora.md', 'garden.md');
+}

package/skills/choose-personas/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: choose-personas
+description: "Selects, balances, and configures specialized agent personas for a Garden swarm task. Analyzes codebase context, domain complexity, and task requirements to formulate a triad of complementary personas with opposing priorities. For every persona, explicitly recommends the optimal coding harness (e.g. OpenCode Desktop, Claude Code CLI, Antigravity, OpenAI Codex) and foundation model (e.g. Gemini 3.8 Flash, Claude 3.5 Sonnet, Claude 3 Opus, GPT-4o, local models) aligned with operator preferences. Solicits operator confirmation or edits with candidate alternatives via interactive questions, and outputs garden-swarm.json. Triggers: 'choose personas', 'select personas', 'set up agent team', 'assemble personas for this task', 'recommend agents'."
+---
+
+# `choose-personas`: Dynamic Swarm Persona Selection & Harness/Model Pairing
+
+> **Calibrate the Minds Before Booting the Hands**  
+> *A multi-agent swarm is only as effective as the diversity, specialization, and cognitive balance of its personas. This skill pairs domain roles with their optimal coding harnesses and foundation models.*
+
+---
+
+## 1. The Triadic Balance Heuristic
+
+Every engineering task benefits from a triad of three distinct, tension-generating archetypes:
+
+```mermaid
+graph TD
+    A["Archetype 1: The Systems Architect<br/>(Macro Architecture, Invariants, Coherence)"]
+    B["Archetype 2: The Purist Auditor<br/>(Code Quality, Standards, Rigorous Proof, Zero Sloppiness)"]
+    C["Archetype 3: The DevEx & Implementation Lead<br/>(Ergonomics, API Utility, Frictionless Execution)"]
+
+    A <-->|Structural Tension| B
+    B <-->|Pragmatic Tension| C
+    C <-->|Coherence Tension| A
+```
+
+1. **The Systems Architect** (e.g., Marcus Vance):
+   - **Focus**: Global system topology, invariants, lifecycle management, failure modes, cross-component boundaries.
+   - **Bias**: Prefers structural purity and comprehensive conceptual models.
+2. **The Purist Auditor / Refactoring Specialist** (e.g., Caleb Thorne / Dr. Vance):
+   - **Focus**: Single-source of truth (SSOT), ISO standards compliance, dead-code elimination, zero green mirages, edge-case failure proofs.
+   - **Bias**: Adversarial skeptic. Assumes claims are unproven until verified by an automated test or compiler run.
+3. **The DevEx & Implementation Lead** (e.g., Elena Rostova):
+   - **Focus**: Developer experience, API ergonomics, ease of adoption, idiomatic conventions, pragmatic delivery.
+   - **Bias**: Champions the human engineer using the tool; eliminates cognitive overhead and unnecessary friction.
+
+---
+
+## 2. Harness & Model Matching Matrix
+
+When proposing personas, the assistant must explicitly pair each persona with an appropriate **coding harness** and **foundation model**, taking operator preferences into account (defaulting to Antigravity + Gemini 3.8 Flash for rapid implementation, and invoking Claude for deep adversarial auditing):
+
+| Role Mandate | Recommended Harness | Recommended Model Tier | Rationale |
+| :--- | :--- | :--- | :--- |
+| **Architectural Design & Systems Modeling** | **Antigravity** or **OpenCode** | **Gemini 3.8 Flash** or **Claude 3.5 Sonnet** | Fast token throughput, deep reasoning, superior multi-file architectural comprehension, and native background ear support. |
+| **Adversarial Audit & Code Quality Purism** | **Claude Code CLI** | **Claude 3 Opus** or **Claude 3.5 Sonnet** | Uncompromising adherence to instructions, meticulous attention to negative controls, zero tolerance for superficial green tests. |
+| **DevEx, Rapid Prototyping & Implementation** | **Antigravity** | **Gemini 3.8 Flash** | Native reactive tool execution (`run_command`), rapid file modification, direct terminal feedback. |
+| **Hermetic / Local Security Analysis** | **Headless Terminal Worker** | **Ollama / Local DeepSeek-R1** | Air-gapped execution for proprietary credentials, licensing checks, or sensitive security audits. |
+
+---
+
+## 3. The Calibration Workflow
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant Orch as Orchestrator Chat
+    participant Repo as Codebase Context
+    participant User as Human Operator
+
+    Orch->>Repo: Inspects project language, repo structure & open issues
+    Note over Orch: Formulates primary triad + 2 alternate candidates
+    Orch->>User: Renders interactive ask_question modal with recommendations & alternatives
+    User-->>Orch: Submits chosen triad (or specifies custom modifications)
+    Orch->>Repo: Writes garden-swarm.json manifest
+```
+
+### Step 1: Codebase & Task Analysis
+1. Inspect repository stack (e.g., Nim, Rust, Python, TypeScript, C).
+2. Read project `AGENTS.md` and `README.md` to identify existing conventions.
+3. Determine task scope:
+   - *Refactoring / Technical Debt*: Prioritize Refactoring Purist + Test Auditor.
+   - *Greenfield Subsystem*: Prioritize Systems Architect + API Designer.
+   - *Security / Compliance*: Prioritize ISO Compliance Auditor + Security Adversary.
+
+### Step 2: Formulate Recommendation & Alternatives
+Synthesize the primary triad and at least two alternative candidates:
+- **Primary Triad**:
+  - Persona 1: Name, Role title, Mandate, Suggested Harness, Suggested Model.
+  - Persona 2: Name, Role title, Mandate, Suggested Harness, Suggested Model.
+  - Persona 3: Name, Role title, Mandate, Suggested Harness, Suggested Model.
+- **Alternative Candidates**:
+  - Alternate A: e.g. Performance Benchmarking Engineer.
+  - Alternate B: e.g. Documentation & Developer Education Lead.
+
+### Step 3: Interactive Operator Ratification (`ask_question`)
+Invoke `ask_question` with structured, selectable options:
+- Option 1 (Recommended): Primary Triad (with explicit harnesses and models listed).
+- Option 2: Alternative balance (e.g. replacing Purist with Performance Engineer).
+- Option 3: Custom configuration (allows user write-in).
+
+### Step 4: Generate Swarm Manifest (`garden-swarm.json`)
+Once ratified, write `garden-swarm.json` to the target project directory:
+
+```json
+{
+  "project": "my-project",
+  "created_at": "2026-09-28T12:00:00Z",
+  "workers": [
+    {
+      "name": "architect",
+      "persona": "Marcus Vance",
+      "role": "Staff Systems Architect",
+      "harness": "antigravity",
+      "model": "gemini-3-8-flash",
+      "tags": ["systems", "architecture", "coordinator"],
+      "system_prompt": "You are Marcus Vance, Staff Systems Architect...",
+      "startup_command": "rhizo listen architect"
+    },
+    {
+      "name": "auditor",
+      "persona": "Caleb Thorne",
+      "role": "Code Quality & Refactoring Purist",
+      "harness": "claude-code",
+      "model": "claude-3-5-sonnet",
+      "tags": ["qa", "audit", "purist"],
+      "system_prompt": "You are Caleb Thorne, Refactoring Purist...",
+      "startup_command": "claude --agent auditor"
+    },
+    {
+      "name": "implementer",
+      "persona": "Elena Rostova",
+      "role": "DevEx & Implementation Lead",
+      "harness": "antigravity",
+      "model": "gemini-3-8-flash",
+      "tags": ["dev", "devex", "build"],
+      "system_prompt": "You are Elena Rostova, DevEx Lead...",
+      "startup_command": "rhizo listen implementer"
+    }
+  ]
+}
+```
+
+---
+
+## 4. Verification & Handoff
+
+Before concluding:
+1. Verify `garden-swarm.json` is syntactically valid JSON.
+2. Confirm each worker has unique `name` and non-empty `tags`.
+3. Proceed directly to [`launch-workers`](../launch-workers/SKILL.md).

package/skills/dialectical-pump/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: dialectical-pump
+description: "Drives empirical multi-perspective deliberation and synthesis across agent personas. Enforces the strict invariant that dialectical exchanges are NOT theatrical dialogue: every turn must be grounded in tool calls (reading file lines, executing tests, running benchmarks, checking git history). Operates across three sequential stages: (1) Research & Understanding Doc with automated Fact-Check Gate, (2) Product & System Architecture Design Doc, and (3) Adversarial Design Review, Audit Report generation, and finding remediation. Triggers: 'dialectical pump', 'run dialectical pump', 'pump perspectives', 'triadic deliberation', 'dialectical research', 'dialectical design', 'dialectical review'."
+---
+
+# `dialectical-pump`: Grounded Multi-Persona Deliberation Engine
+
+> **Thesis $\times$ Antithesis $\to$ Empirical Synthesis**  
+> *The Dialectical Pump is an epistemic machine. It prevents hallucinated consensus and green mirages by forcing opposing personas to prove every assertion through real tool execution.*
+
+---
+
+## 1. The Core Invariant: Zero Theatrical Dialogue
+
+> [!CAUTION] **STRICT PROHIBITION: Theatrical Dialogue is Rejected**
+> A common failure mode in LLM roleplay is generating conversational chit-chat:  
+> *"Persona A: I think we should use Redis! Persona B: I agree, but what about memory? Persona A: Good point!"*  
+> **This is banned.**
+
+Every turn taken by a persona in the Dialectical Pump must follow the **Empirical Grounding Protocol**:
+1. **Tool Invocation**: Every claim must be substantiated by a tool call:
+   - Reading exact line numbers: `view_file(AbsolutePath=..., StartLine=..., EndLine=...)`.
+   - Running test suites: `run_command(CommandLine="pytest ...")`.
+   - Measuring execution or memory: `run_command(CommandLine="time ...")`.
+   - Checking git history/diffs: `run_command(CommandLine="git log -S ...")`.
+2. **Hard Evidence Citations**: Every critique must cite verifiable evidence:
+   - *Prohibited*: "This function looks inefficient."
+   - *Mandated*: "Profiling `parsePayload` at `src/resp.nim:88` reveals an allocation of a 64KB temporary string per message; under 10k messages/sec, this triggers 640MB/sec of GC churn as verified by `nimble bench`."
+
+---
+
+## 2. The Three Dialectical Stages
+
+The Dialectical Pump executes across three distinct stages of a project:
+
+```mermaid
+flowchart TD
+    subgraph Stage1["Stage 1: Grounded Research"]
+        S1A["1. Triad plans research questions"]
+        S1B["2. Workers explore code & tests"]
+        S1C["3. Synthesize understanding.md"]
+        S1D["4. Automated Fact-Check Gate"]
+        S1A --> S1B --> S1C --> S1D
+    end
+
+    subgraph Stage2["Stage 2: Architecture & Design"]
+        S2A["1. Systems Architect drafts thesis"]
+        S2B["2. Purist Auditor attacks failure modes"]
+        S2C["3. DevEx Lead balances ergonomics"]
+        S2D["4. Synthesize design.md"]
+        S2A --> S2B --> S2C --> S2D
+    end
+
+    subgraph Stage3["Stage 3: Adversarial Review & Audit"]
+        S3A["1. Auditor files audit_report.md"]
+        S3B["2. Personas resolve findings"]
+        S3C["3. Ratified design.md"]
+        S3A --> S3B --> S3C
+    end
+
+    Stage1 --> Stage2 --> Stage3
+```
+
+---
+
+## 3. Stage 1: Grounded Research & Fact-Check Gate
+
+### Step 1.1: Research Plan Formulation
+The triadic personas inspect the assignment and agree on the empirical questions:
+- What are the existing invariants in the codebase?
+- What dependencies and protocols exist?
+- What test suites cover this subsystem?
+
+### Step 1.2: Codebase Exploration
+Workers read actual files, verify test suites, and map domain structures.
+
+### Step 1.3: Generate Understanding Document (`understanding.md`)
+The triad synthesizes their findings into `understanding.md` containing:
+- Domain Glossary & Invariants.
+- Data Flow Diagrams.
+- Identified Constraints & Technical Debt.
+
+### Step 1.4: The Strict Fact-Check Gate
+Before proceeding to design, a dedicated Auditor persona audits `understanding.md`:
+- Every file reference must exist (`test -f <path>`).
+- Every function signature cited must match reality.
+- If any claim is ungrounded or fabricated, the pump repeats Step 1.2 until 100% verified.
+
+---
+
+## 4. Stage 2: Architecture & System Design (`design.md`)
+
+Once research is fact-checked, the pump shifts to product and technical design:
+
+### Step 2.1: The Thesis (Systems Architect)
+The Systems Architect proposes the macro architecture:
+- Module decomposition.
+- Data structures and wire formats.
+- Concurrency model and lifecycle states.
+
+### Step 2.2: The Antithesis (Purist Auditor)
+The Purist Auditor stress-tests the proposal against concrete failure modes:
+- Concurrency race conditions: "What happens if process A dies between lines X and Y?"
+- Resource leaks: "Where are file descriptors closed during exception unwinding?"
+- Backwards compatibility: "Does this break existing configs or CLI arguments?"
+
+### Step 2.3: The Synthesis (DevEx & Implementation Lead)
+The DevEx Lead resolves the dialectic:
+- Eliminates unnecessary abstractions that create ergonomics drag.
+- Hardens the API contracts.
+- Produces the ratified **`design.md`**.
+
+---
+
+## 5. Stage 3: Adversarial Review & Audit Report
+
+### Step 3.1: Forensic Audit Inspection
+An Auditor persona performs a line-by-line inspection of `design.md` against single-source truth and ISO standards, generating **`audit_report.md`**:
+- Defect codes: `CRIT-01`, `WARN-02`, `DOC-03`.
+- Root cause analysis.
+- Specific non-prescriptive recommendation options.
+
+### Step 3.2: Remediation & Resolution
+The triad meets to address every finding in `audit_report.md`:
+- For each defect code: select an option, update `design.md`, and record the resolution in the audit report.
+- The gate only clears when **0 critical or blocker defects remain open**.
+
+---
+
+## 6. Output Artifacts
+
+At the conclusion of the Dialectical Pump:
+1. `understanding.md` (Grounded and fact-checked).
+2. `design.md` (Debated, hardened, and synthesized).
+3. `audit_report.md` (All findings addressed and closed).
+
+Proceed immediately to [`plan-implementation`](../plan-implementation/SKILL.md).

package/skills/garden/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: garden
+description: "Master entrypoint and end-to-end ceremony director for multi-agent swarms operating on top of Rhizo (transport) and Vine (workspace integrator). Guides the user and orchestrator session through the full lifecycle: persona selection with harness/model pairing, tmux worker fleet provisioning with live terminal viewer, 3-stage empirical dialectical pump (research, design, audit), master implementation planning with locking/strand schedules, and live swarm execution with Two-Key gate verification and fast-forward trunk weaving. Triggers: 'garden', 'run garden', 'swarm this project', 'orchestrate with garden', 'start garden swarm', 'run the full garden ceremony'."
+---
+
+# Garden: Multi-Agent Swarm Ceremony & Orchestration Engine
+
+> **The Sovereign Orchestration Layer for Autonomous AI Swarms**  
+> *Where `rhizo` is the transport nervous system and `vine` is the workspace integrator, `garden` is the institutional intellect, deliberation crucible, and master ceremony conductor.*
+
+---
+
+## 1. Architectural Architecture & Layering
+
+Garden coordinates teams of heterogeneous AI coding assistants across terminals and machines:
+
+```mermaid
+flowchart TD
+    subgraph Garden["Garden Layer (Methodology & Ceremonies)"]
+        Phase1["Phase 1: choose-personas (Team Selection & Models)"]
+        Phase2["Phase 2: launch-workers (tmux & Terminal Viewer)"]
+        Phase3["Phase 3: dialectical-pump (Research ➔ Design ➔ Audit)"]
+        Phase4["Phase 4: plan-implementation (Locking & Strands)"]
+        Phase5["Phase 5: orchestrate-swarm (Dispatch & Vine Weaving)"]
+    end
+
+    subgraph Infrastructure["Coordination Infrastructure"]
+        Rhizo["Rhizo (Redis Bus, Fencing Mutexes, Work Queues)"]
+        Vine["Vine (APFS CoW Strands, Two-Key Gate, Weaving)"]
+    end
+
+    Phase1 --> Phase2 --> Phase3 --> Phase4 --> Phase5
+    Phase2 -.-> Rhizo
+    Phase3 -.-> Rhizo
+    Phase4 -.-> Rhizo & Vine
+    Phase5 -.-> Rhizo & Vine
+```
+
+---
+
+## 2. The 5-Phase End-to-End Ceremony
+
+When invoked, the Orchestrator (the primary conversation chat) executes these five phases sequentially. Never skip phases or invert the order.
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User as Human Operator
+    participant Orch as Main Chat (Orchestrator)
+    participant Swarm as Tmux Worker Swarm
+    participant Bus as Rhizo (Redis)
+    participant Gate as Vine (Strands & Gate)
+
+    User->>Orch: "garden: implement feature X"
+    Note over Orch: Phase 1: Team Calibration
+    Orch->>User: Suggests Persona Roster (Roles, Harnesses, Models) via ask_question
+    User-->>Orch: Ratifies / Adjusts Roster
+
+    Note over Orch: Phase 2: Fleet Provisioning
+    Orch->>Swarm: Executes launch-workers (tmux panes + Ghostty/Terminal viewer)
+    Swarm->>Bus: rhizo open + rhizo listen (Workers armed)
+
+    Note over Orch: Phase 3: Empirical Dialectic
+    Orch->>Swarm: Dispatches dialectical-pump
+    Note over Swarm: 1. Research ➔ understanding.md ➔ Fact-Check Gate<br/>2. Architecture ➔ design.md<br/>3. Adversarial Audit ➔ audit_report.md ➔ Remediation
+    Swarm-->>Orch: Ratified design.md & cleared audit report
+
+    Note over Orch: Phase 4: Master Planning
+    Orch->>Orch: Authors implementation_plan.md (Locks, Strands, To-Do list)
+
+    Note over Orch: Phase 5: Swarm Execution & Weaving
+    loop For Each Plan Task
+        Orch->>Bus: Dispatch task (rhizo send / enqueue)
+        Bus->>Swarm: Worker claims lease (rhizo claim)
+        Swarm->>Gate: Creates strand (vine new)
+        Swarm->>Swarm: Implements code + verifies tests
+        Swarm->>Gate: Verifies Two-Key Gate (vine gate)
+        Swarm->>Orch: Reports gate pass (rhizo reply)
+        Orch->>Gate: Fast-forward merge (vine weave)
+        Orch->>Orch: Updates plan checkbox & Harness To-Do
+    end
+    Orch->>User: Mission Accomplished Summary
+```
+
+---
+
+## 3. Phase Transition Protocols & Quality Gates
+
+### Gate 1 $\to$ 2: Persona Ratification Gate
+- **Condition**: Operator has confirmed the roster via `ask_question`.
+- **Artifact**: `garden-swarm.json` persisted in the project directory.
+- **Action**: Call `launch-workers`.
+
+### Gate 2 $\to$ 3: Cluster Readiness Gate
+- **Condition**: All worker panes booted, heartbeats active in Redis.
+- **Verification**: `rhizo who --json` confirms 100% of agents online and tagged.
+- **Action**: Call `dialectical-pump`.
+
+### Gate 3 $\to$ 4: Design Audit Clearance Gate
+- **Condition**:
+  1. `understanding.md` passed the Fact-Check Gate (zero ungrounded claims).
+  2. `design.md` authored and debated by the triadic pump.
+  3. `audit_report.md` contains 0 open `CRIT` or `BLOCKER` defects.
+- **Action**: Call `plan-implementation`.
+
+### Gate 4 $\to$ 5: Plan Alignment Gate
+- **Condition**: `implementation_plan.md` complete with task matrix, locking schedule, vine strand lifecycles, and emergent design addendum protocol.
+- **Action**: Call `orchestrate-swarm`.
+
+---
+
+## 4. Sub-Skill Reference Map
+
+When executing Garden, invoke the sub-skills at their designated phases:
+
+| Phase | Skill Name | Description | Primary Artifacts |
+| :--- | :--- | :--- | :--- |
+| **Phase 1** | [`choose-personas`](../choose-personas/SKILL.md) | Analyzes task, formulates 3 balanced personas with suggested **coding harness** and **model**, and confirms with operator. | `garden-swarm.json` |
+| **Phase 2** | [`launch-workers`](../launch-workers/SKILL.md) | Provisions tmux session with worker panes, registers `rhizo open`, arms listeners, and launches OS terminal viewer (Ghostty / Terminal.app). | Live tmux session, visible terminal |
+| **Phase 3** | [`dialectical-pump`](../dialectical-pump/SKILL.md) | Drives empirical multi-persona debate grounded in tool calls (file reading, test running, AST inspecting). Produces research, design, and audit docs. | `understanding.md`, `design.md`, `audit_report.md` |
+| **Phase 4** | [`plan-implementation`](../plan-implementation/SKILL.md) | Authors master implementation plan detailing task assignments, `rhizo` locks (`--fencing`), `vine` strands, dynamic checkboxes, and To-Do tracking. | `implementation_plan.md` |
+| **Phase 5** | [`orchestrate-swarm`](../orchestrate-swarm/SKILL.md) | Main-chat governor: dispatches tasks over Redis, tracks heartbeats, approves emergent design addenda, and executes `vine weave` upon Two-Key gate pass. | Completed code, woven trunk, git commits |
+
+---
+
+## 5. Invariants & Rules of Engagement
+
+1. **The Supreme Orchestrator Invariant**:
+   The primary conversation session acts as the Supreme Orchestrator. It coordinates, plans, reviews, and merges. It delegates intensive multi-file edits to the worker fleet.
+2. **Zero Theatrical Dialogue**:
+   In dialectical deliberations, every assertion must be backed by empirical evidence (line citations, test execution outputs, compiler errors).
+3. **No Unmanaged Daemons / Zero Dirty Commits**:
+   All coordination metadata (`.rhizo.*`, `.vine.*`, `*.lock`) must remain in `.gitignore`. Workers must adhere to the Two-Key Gate before any code touches the canonical trunk.

package/skills/launch-workers/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: launch-workers
+description: "Provisions an active worker fleet inside a dedicated tmux session and launches an OS-level terminal viewer (Ghostty / Terminal.app). Reads garden-swarm.json, creates named tmux windows/panes for each worker, configures environment variables (RHIZO_AGENT_NAME, project path), registers each agent in Redis with rhizo open, arms background listeners, and runs AppleScript or open commands on macOS to display the live worker windows to the operator. Verifies cluster heartbeat readiness via rhizo who --json before handing off. Triggers: 'launch workers', 'spin up workers', 'start worker swarm', 'open tmux swarm', 'launch fleet'."
+---
+
+# `launch-workers`: Automated Tmux Swarm Provisioning & Terminal Viewer
+
+> **From Manifest to Live Terminals in Under 2 Seconds**  
+> *Tmux multiplexes the background worker processes while OS-level desktop scripting opens your preferred terminal app so you can observe the swarm in real time.*
+
+---
+
+## 1. System Requirements & Invariants
+
+1. **`tmux` is Required**:
+   - `tmux 3.0+` must be installed on the host (`command -v tmux`). If missing, fail fast and instruct the operator to install (`brew install tmux`).
+2. **`rhizo` is Required**:
+   - Rhizo engine must be present (`npm install -g @axiomantic/rhizo`).
+3. **No Terminal Fallbacks**:
+   - Workers are strictly managed inside tmux windows/panes. We do not detach headless rogue background processes with `nohup` or `&`.
+4. **Desktop Viewer Priority on macOS**:
+   - Automatically detects installed terminal emulators:
+     - **Priority 1: Ghostty** (`/Applications/Ghostty.app`)
+     - **Priority 2: iTerm2** (`/Applications/iTerm.app`)
+     - **Priority 3: macOS Terminal** (`/System/Applications/Utilities/Terminal.app`)
+   - Pops open a visible terminal window running `tmux attach-session -t garden-<project>`.
+
+---
+
+## 2. The Provisioning Flow
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant Orch as Main Chat (Orchestrator)
+    participant Script as launch_tmux_swarm.sh
+    participant Tmux as tmux Daemon
+    participant OS as macOS Window Server (Ghostty / Terminal)
+    participant Redis as Rhizo (Redis Bus)
+
+    Orch->>Script: Invokes with --swarm-file garden-swarm.json
+    Script->>Tmux: Creates session garden-<project>
+    loop For Each Worker in Manifest
+        Script->>Tmux: Creates named window/pane
+        Script->>Tmux: Injects RHIZO_AGENT_NAME & cd <project>
+        Script->>Tmux: Sends rhizo open <name> "<tags>"
+        Script->>Tmux: Arms listener (rhizo listen or custom startup command)
+        Tmux->>Redis: Registers heartbeat & listener lock
+    end
+    Script->>OS: Opens Ghostty/Terminal attached to tmux session
+    Script-->>Orch: Returns JSON status
+    Orch->>Redis: Verifies cluster readiness (rhizo who --json)
+```
+
+---
+
+## 3. Execution Procedure
+
+### Step 1: Run the Swarm Provisioner
+Execute [`scripts/launch_tmux_swarm.sh`](file:///Users/eek/Development/garden/scripts/launch_tmux_swarm.sh) with the active project path and manifest:
+
+```bash
+/Users/eek/Development/garden/scripts/launch_tmux_swarm.sh \
+  --project-dir "$(pwd)" \
+  --swarm-file "garden-swarm.json" \
+  --force
+```
+
+- `--force`: Kills any stale prior session with the same project name before provisioning a clean fleet.
+- Automatically launches Ghostty or Terminal.app on macOS attached to the new session.
+
+### Step 2: Verify Cluster Readiness Gate
+Before dispatching tasks, verify that every worker from `garden-swarm.json` is actively registered in Redis and displaying valid heartbeats:
+
+```bash
+rhizo who --json
+```
+
+**Pass Criteria**:
+1. All worker names in `garden-swarm.json` appear in `active_agents`.
+2. Heartbeats have active TTLs (> 0).
+3. Assigned tags match the manifest.
+
+### Step 3: Inspect Terminal Buffer (Health Check)
+To check the initial logs or output of any worker without leaving your chat:
+
+```bash
+# Capture last 20 lines of worker 'architect' (window 0)
+tmux capture-pane -p -t garden-<project>:0 | tail -n 20
+```
+
+---
+
+## 4. Teardown & Swarm Cleanup
+
+When the entire project is completed, or when canceling a run:
+
+```bash
+# Gracefully deregister all swarm agents from Redis:
+for worker in $(python3 -c "import json; [print(w['name']) for w in json.load(open('garden-swarm.json'))['workers']]"); do
+  rhizo close "$worker" 2>/dev/null || true
+done
+
+# Terminate the tmux session:
+tmux kill-session -t garden-<project> 2>/dev/null || true
+```