@axiomantic/garden 0.2.0 → 0.2.1

package/README.md

@@ -187,6 +187,74 @@ The main chat orchestrator dispatches work over Redis. Workers code in isolated
 
 ---
 
+## CLI Reference
+
+| Command | Arguments | Description |
+| :--- | :--- | :--- |
+| `garden prompts` | `[--worker <name>] [--write [file]] [--json] [--project-dir <dir>] [--swarm-file <file>]` | Generate 10-backtick raw markdown prompt cards for pasting into worker sessions. |
+| `garden launch` | `[--worker <name>] [--write [file]] [--json] [--tmux] [--session-name <name>]` | Bootstrap swarm worker sessions (defaults to generating prompt cards). |
+| `garden status` | `[--json] [--session-name <name>]` | Telemetry query across active Rhizo agents, listener status, and Vine strands. |
+| `garden init` | `[<target_dir>] [--force]` | Initialize `garden.toml`, docs scaffold, and install guide in `AGENTS.md`. |
+| `garden teardown`| `[--session-name <name>] [--swarm-file <file>]` | Gracefully close registered swarm agents on the Redis bus. |
+| `garden guide` | `<install\|check\|uninstall> [path]` | Install or manage Garden Multi-Agent Swarm Guide in `AGENTS.md`. |
+
+---
+
+## Configuration & Swarm Manifest Reference
+
+> [!TIP]
+> For the complete specification of `garden.toml`, `garden-swarm.json` schemas, and environment variables, see the [Garden Configuration & Swarm Manifest Reference](docs/configuration.md).
+
+### Environment Variables
+
+| Variable | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `GARDEN_SWARM_FILE` | Path | `garden-swarm.json` | Explicit path to swarm manifest JSON file. |
+| `GARDEN_CONFIG` | Path | `garden.toml` | Explicit path to project `garden.toml`. |
+| `GARDEN_PROJECT_DIR`| Path | *Auto-detected* | Target repository root directory. |
+| `GARDEN_TERMINAL_APP`| String | `auto` | Preferred terminal viewer for tmux sessions (`Ghostty`, `Terminal`, `iTerm`, `none`). |
+
+### Example `garden-swarm.json`
+
+```json
+{
+  "project": "myproject",
+  "target_repo": "/Users/developer/Development/myproject",
+  "orchestrator": "orchestrator",
+  "workers": [
+    {
+      "name": "architect",
+      "persona": "Dr. Marcus Vance (Systems Architect)",
+      "role": "Systems Architect & Formal Invariant Specifier",
+      "harness": "Claude Code",
+      "model": "claude-3-5-sonnet",
+      "tags": ["design", "spec"],
+      "opposing_priority": "Formal mathematical correctness and zero architectural drift."
+    },
+    {
+      "name": "auditor",
+      "persona": "Lyra Sterling (Adversarial Quality Auditor)",
+      "role": "Adversarial Code Reviewer & Security Auditor",
+      "harness": "OpenCode",
+      "model": "gemini-3.8-flash",
+      "tags": ["audit", "testing"],
+      "opposing_priority": "Aggressive edge-case fault injection and invariant verification."
+    },
+    {
+      "name": "implementer",
+      "persona": "Elena Rostova (Lead Implementation Engineer)",
+      "role": "Polyglot Systems & Performance Engineer",
+      "harness": "Antigravity",
+      "model": "claude-3-5-sonnet",
+      "tags": ["implementation", "perf"],
+      "opposing_priority": "Rapid implementation velocity and minimal dependency footprint."
+    }
+  ]
+}
+```
+
+---
+
 ## Core Invariants
 
 1. **The Supreme Orchestrator Invariant**:

package/SKILL.md

@@ -102,3 +102,14 @@ To prevent silent deadlocks when workers stall, crash, or fail to re-arm listene
 2. **Watchdog Window**: If a worker fails to respond within the expected turn window (e.g. 5–10 minutes) and `rhizo probe` reveals `NO_LISTENER` or unread inbox items:
    - **Escalate Immediately**: Prompt the operator via `ask_question` with the diagnostic status.
    - **Actionable Remediation**: Offer options to (1) re-arm the listener in the worker's terminal session (`rhizo listen <worker>`), (2) reboot the agent harness, or (3) reassign the task via `rhizo reroute <worker> <new_worker>`.
+
+---
+
+## 5. Configuration & Swarm Manifest Reference
+
+See [`docs/configuration.md`](docs/configuration.md) for full details on:
+- **Environment Variables**: `GARDEN_SWARM_FILE`, `GARDEN_CONFIG`, `GARDEN_PROJECT_DIR`, and `GARDEN_TERMINAL_APP`.
+- **`garden.toml`**: Project-level defaults (`name`, `preferred_terminal`, `session_prefix`, `default_triad`).
+- **`garden-swarm.json`**: Swarm specification schema (`project`, `target_repo`, `orchestrator`, `shared_workspace`, `workers` array: `name`, `persona`, `role`, `harness`, `model`, `tags`, `system_prompt`, `opposing_priority`).
+- **The 10-Backtick Protocol**: Clean raw markdown formatting for copy-paste worker bootstrap prompts.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiomantic/garden",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Multi-Agent Swarm Orchestration, Empirical Dialectics & Ceremonies on top of Rhizo & Vine",
   "main": "bin/run.js",
   "bin": {

package/skills/garden/SKILL.md

@@ -102,3 +102,19 @@ To prevent silent deadlocks when workers stall, crash, or fail to re-arm listene
 2. **Watchdog Window**: If a worker fails to respond within the expected turn window (e.g. 5–10 minutes) and `rhizo probe` reveals `NO_LISTENER` or unread inbox items:
    - **Escalate Immediately**: Prompt the operator via `ask_question` with the diagnostic status.
    - **Actionable Remediation**: Offer options to (1) re-arm the listener in the worker's terminal session (`rhizo listen <worker>`), (2) reboot the agent harness, or (3) reassign the task via `rhizo reroute <worker> <new_worker>`.
+3. **Orchestrator Self-Audit Watchdog & Debouncer Protocol (GVR-014)**:
+   - For harnesses supporting `schedule` (e.g. Antigravity), arm a debounced 15-minute watchdog timer (`schedule(DurationSeconds=900, Prompt="...", TimerCondition="any")`).
+   - Debouncer replaces (kills previous timer via `manage_task(Action='kill')` before arming a new one) on task dispatch, worker reports, and plan updates ("early and often"). Arriving worker traffic cancels the timer for free with 0 token overhead.
+   - When the timer fires, execute the short check: `rhizo watchdog check --agent <orchestrator> --json`. If `ACTION_REQUIRED: REARM_LISTENER`, revive `rhizo listen` in the background and debounce. When all tasks in the plan are complete (`- [x]`), stand down.
+
+---
+
+## 5. Configuration & Swarm Manifest Reference
+
+See [`docs/configuration.md`](../../docs/configuration.md) for full details on:
+- **Environment Variables**: `GARDEN_SWARM_FILE`, `GARDEN_CONFIG`, `GARDEN_PROJECT_DIR`, and `GARDEN_TERMINAL_APP`.
+- **`garden.toml`**: Project-level defaults (`name`, `preferred_terminal`, `session_prefix`, `default_triad`).
+- **`garden-swarm.json`**: Swarm specification schema (`project`, `target_repo`, `orchestrator`, `shared_workspace`, `workers` array: `name`, `persona`, `role`, `harness`, `model`, `tags`, `system_prompt`, `opposing_priority`).
+- **The 10-Backtick Protocol**: Clean raw markdown formatting for copy-paste worker bootstrap prompts.
+
+

package/skills/orchestrate-swarm/SKILL.md

@@ -33,6 +33,38 @@ Maintain this exact block in the working context:
 <!-- END_SWARM_RUNTIME_STATE -->
 </CRITICAL>
 
+<CRITICAL>
+Orchestrator Turn-End Listener Invariant (GVR-014):
+Coding harnesses (Antigravity, Claude Code, OpenCode) are event-driven: when the model yields a turn with text output, execution is completely suspended. Redis inbox state changes CANNOT wake an idle harness without an active child process registered in the task manager.
+
+Whenever the Supreme Orchestrator dispatches a task, broadcasts instructions, or awaits worker responses, THE FINAL ACTION OF THAT TURN MUST BE ARMING A BACKGROUND LISTENER:
+`run_command(CommandLine="rhizo listen <orchestrator>", IsDaemon=false, WaitMsBeforeAsync=500)`
+
+FORBIDDEN: Never yield the conversation turn to the operator after dispatching work without an active background listener running. Yielding a turn without a listener severs the swarm's physical lifeline, trapping worker replies in Redis and causing silent swarm stalls.
+
+Safety Net (Scheduled Timer Watchdog & Debouncer Protocol):
+In harnesses supporting `schedule` (e.g. Google Antigravity), arm a debounced watchdog timer to ensure an orchestrator session is never abandoned if a listener fails to arm or terminates prematurely.
+- **Cadence**: 15 minutes (`DurationSeconds=900`, range 10m–30m / 600s–1800s). Defaulting to 15m avoids slurping token budgets while guaranteeing a 15m upper bound on any stall.
+- **Replace, Never Stack Invariant**:
+  Harnesses prohibit concurrent timers with `TimerCondition="any"`. Before setting a timer, inspect running tasks with `manage_task(Action='list')`. If an existing watchdog task is active (`toolName == "schedule"` or prompt includes `[RHIZO WATCHDOG]`), cancel it via `manage_task(Action='kill', TaskId=...)`.
+- **Debounce Triggers (Early and Often)**:
+  Run the debouncer subroutine on:
+  1. Task Dispatch (`rhizo send`, `rhizo enqueue`).
+  2. Worker Message / Gate Report receipt.
+  3. Implementation Plan updates (`implementation_plan.md` checkboxes).
+  4. Watchdog Wakeup turn (if tasks are still in flight).
+- **Stand Down Invariant**:
+  When all tasks in `implementation_plan.md` are complete (`- [x]` 100%), kill any running watchdog timer and do not reschedule.
+- **Zero-Token Happy Path**:
+  Because `TimerCondition="any"` is set, any arriving worker message or background task completion automatically cancels the timer early before it expires. The timer only fires if the orchestrator was silent and deaf for a full 15 minutes.
+- **The Short Check (When Timer Fires)**:
+  Run `rhizo watchdog check --agent <name> --json`.
+  * If `ACTION_REQUIRED: REARM_LISTENER`: start `rhizo listen <name>` in background and debounce timer.
+  * If `ACTION_REQUIRED: UNREAD_MESSAGES`: drain messages with `rhizo drain 10 <name>`, start listener, and debounce.
+  * If `OK: LISTENING`: listener is healthy; debounce timer and return to sleep.
+  * If `STAND_DOWN: IDLE`: no tasks in flight; stand down.
+</CRITICAL>
+
 ---
 
 ## 2. The Runtime Governance Loop
@@ -75,12 +107,30 @@ Depending on the task distribution model in `implementation_plan.md`:
     --body '{"task_id": "task-test-harness", "strand": "strand/task-test-harness"}'
   ```
 
+- **Mandatory Turn-End Listener Arming**:
+  Immediately after executing `rhizo send` or `rhizo enqueue`, arm your single-shot background listener before completing your turn:
+  ```bash
+  run_command(CommandLine="rhizo listen orchestrator", IsDaemon=false, WaitMsBeforeAsync=500)
+  ```
+  *(Never end your turn without this active background task; without it, worker gate reports cannot wake you up).*
+
 ### SOP 2: Monitoring Swarm Health, Watchdog & Escalation (GVR-011)
 Check active workers and cluster status:
 ```bash
 rhizo who --json
 ```
 
+#### Orchestrator Self-Audit Watchdog
+Verify that the orchestrator itself is actively listening while tasks are in-flight:
+```bash
+rhizo watchdog check [--agent <orchestrator>] [--json]
+```
+Returns:
+- `status: OK (LISTENING)`: Listener process active and healthy.
+- `status: ACTION_REQUIRED (REARM_LISTENER)`: In-flight tasks exist but listener is dead/missing. Re-arm immediately.
+- `status: ACTION_REQUIRED (UNREAD_MESSAGES)`: Unconsumed inbox messages waiting. Drain immediately.
+- `status: STAND_DOWN (IDLE)`: Zero in-flight tasks and zero unread messages. Stand down.
+
 #### Responsiveness Watchdog & Health Probing
 When waiting for a worker to finish an assigned task, run a health probe if no message is received within the expected window (e.g. 5–10 minutes):
 ```bash