@axiomantic/garden 0.1.5 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +22 -22
- package/SKILL.md +29 -3
- package/bin/binaries/garden-darwin-arm64 +0 -0
- package/bin/binaries/garden-darwin-x64 +0 -0
- package/bin/binaries/garden-linux-arm64 +0 -0
- package/bin/binaries/garden-linux-x64 +0 -0
- package/bin/binaries/garden-win32-x64.exe +0 -0
- package/package.json +1 -1
- package/skills/garden/SKILL.md +29 -3
- package/skills/launch-workers/SKILL.md +69 -57
- package/skills/orchestrate-swarm/SKILL.md +46 -12
package/README.md
CHANGED
|
@@ -5,9 +5,9 @@
|
|
|
5
5
|
**Multi-Agent Swarm Orchestration, Empirical Dialectics & Ceremonies on top of Rhizo & Vine**
|
|
6
6
|
|
|
7
7
|
[](LICENSE)
|
|
8
|
-
[](https://github.com/axiomantic/rhizo)
|
|
9
|
+
[](https://github.com/axiomantic/vine)
|
|
10
|
+
[](README.md)
|
|
11
11
|
[](README.md)
|
|
12
12
|
|
|
13
13
|
*Where `rhizo` provides inter-agent transport and `vine` provides workspace virtualization, `garden` provides the institutional intellect, empirical deliberation, and synchronized swarm execution.*
|
|
@@ -20,7 +20,7 @@
|
|
|
20
20
|
|
|
21
21
|
**Garden** is an agentic engineering framework and skill library for orchestrating heterogeneous teams of AI coding assistants (Claude Code, OpenCode, Antigravity, Cursor, Codex).
|
|
22
22
|
|
|
23
|
-
Instead of treating AI agents as isolated single-turn chatbots, Garden provisions **
|
|
23
|
+
Instead of treating AI agents as isolated single-turn chatbots, Garden provisions **prompt-bootstrapped worker swarms** across your favorite AI coding harnesses (Claude Code, OpenCode, Antigravity, Pi, Cursor), balances specialized personas with designated foundation models, drives **empirically grounded dialectical deliberation**, schedules distributed fencing mutexes, and integrates code through isolated APFS Copy-on-Write strands verified by Vine's Two-Key Gate.
|
|
24
24
|
|
|
25
25
|
```mermaid
|
|
26
26
|
flowchart TD
|
|
@@ -28,7 +28,7 @@ flowchart TD
|
|
|
28
28
|
direction TB
|
|
29
29
|
GardenSkill["garden (Master Entrypoint)"]
|
|
30
30
|
P1["choose-personas (Team & Models)"]
|
|
31
|
-
P2["launch-workers (
|
|
31
|
+
P2["launch-workers (Prompt-Based Session Bootstrapping)"]
|
|
32
32
|
P3["dialectical-pump (Research ➔ Design ➔ Audit)"]
|
|
33
33
|
P4["plan-implementation (Locks & Strands)"]
|
|
34
34
|
P5["orchestrate-swarm (Dispatch & Weave)"]
|
|
@@ -62,19 +62,19 @@ Garden is organized into a clean, batteries-included catalog of self-explanatory
|
|
|
62
62
|
| :--- | :--- | :--- |
|
|
63
63
|
| **[`garden`](skills/garden/SKILL.md)** | **Master Entrypoint** | The sovereign ceremony director. Guides orchestrator and operator step-by-step across all phases from initial task to woven code. |
|
|
64
64
|
| **[`choose-personas`](skills/choose-personas/SKILL.md)** | **Team Calibration** | Formulates a balanced triad of specialized personas (e.g. Architect, Auditor, DevEx Lead) with explicitly recommended **coding harnesses** and **model tiers**, confirmed interactively with the operator. |
|
|
65
|
-
| **[`launch-workers`](skills/launch-workers/SKILL.md)** | **
|
|
65
|
+
| **[`launch-workers`](skills/launch-workers/SKILL.md)** | **Session Bootstrapping** | Generates self-contained, 10-backtick raw markdown prompt cards for pasting into separate terminal sessions (Claude Code, OpenCode, Antigravity, Pi). Configures environment variables, registers identities via `rhizo open`, and arms single-shot listeners. |
|
|
66
66
|
| **[`dialectical-pump`](skills/dialectical-pump/SKILL.md)** | **Empirical Deliberation** | Drives multi-perspective thesis/antithesis/synthesis debates. Strictly prohibits theatrical roleplay: every turn requires tool execution (reading files, running tests, checking ASTs). Produces `understanding.md`, `design.md`, and `audit_report.md`. |
|
|
67
67
|
| **[`plan-implementation`](skills/plan-implementation/SKILL.md)** | **Master Scheduling** | Authors `implementation_plan.md` defining task assignment matrices, `rhizo` distributed fencing locks, `vine` strand workflows, dynamic markdown checkboxes, harness To-Do integration, and emergent design addenda. |
|
|
68
68
|
| **[`orchestrate-swarm`](skills/orchestrate-swarm/SKILL.md)** | **Main-Chat Governor** | Governs execution from the primary chat session: dispatches tasks over Redis, tracks heartbeats, ratifies emergent design addenda, verifies Two-Key gate passes, and triggers `vine weave`. |
|
|
69
69
|
|
|
70
70
|
## Standalone Yet Designed for the Axiomantic Triad
|
|
71
71
|
|
|
72
|
-
Garden is completely standalone and can direct multi-agent dialectics, persona selection, and
|
|
72
|
+
Garden is completely standalone and can direct multi-agent dialectics, persona selection, and prompt-bootstrapped worker swarms on any codebase.
|
|
73
73
|
|
|
74
74
|
However, Garden is designed from the ground up to pair seamlessly with **Rhizo** and **Vine**:
|
|
75
75
|
- [**Rhizo**](https://github.com/axiomantic/rhizo) (Transport & Concurrency): Inter-agent messaging bus, monotonic fencing locks, and task queues over Redis.
|
|
76
76
|
- [**Vine**](https://github.com/axiomantic/vine) (Workspaces & Verification): Sub-second APFS Copy-on-Write strands, polyglot build-cache normalization, and the Two-Key integration gate (`git merge-tree` mechanical + compiler/test suite semantic checks).
|
|
77
|
-
- **Garden** (Swarm Ceremonies):
|
|
77
|
+
- **Garden** (Swarm Ceremonies): Prompt-based worker session bootstrapping, 3-stage empirical dialectical pump (research, architecture, audit), and master ceremonial implementation planning.
|
|
78
78
|
|
|
79
79
|
---
|
|
80
80
|
|
|
@@ -127,22 +127,20 @@ garden guide install
|
|
|
127
127
|
|
|
128
128
|
## System Prerequisites
|
|
129
129
|
|
|
130
|
-
1. **`
|
|
131
|
-
```bash
|
|
132
|
-
brew install tmux
|
|
133
|
-
```
|
|
134
|
-
2. **`rhizo`** (Coordination Engine):
|
|
130
|
+
1. **`rhizo`** (Coordination Engine):
|
|
135
131
|
```bash
|
|
136
132
|
npm install -g @axiomantic/rhizo
|
|
137
133
|
```
|
|
138
|
-
|
|
134
|
+
2. **`vine`** (Workspace Virtualization Engine):
|
|
139
135
|
```bash
|
|
140
|
-
npm install -g @axiomantic/vine
|
|
136
|
+
npm install -g @axiomantic/vine rift-snapshot
|
|
141
137
|
```
|
|
142
|
-
|
|
138
|
+
3. **Redis or Valkey** (local or remote):
|
|
143
139
|
```bash
|
|
144
140
|
brew install redis && brew services start redis
|
|
145
141
|
```
|
|
142
|
+
4. **`tmux`** (Optional):
|
|
143
|
+
Only required if explicitly running legacy headless panes via `garden launch --tmux`.
|
|
146
144
|
|
|
147
145
|
---
|
|
148
146
|
|
|
@@ -163,12 +161,14 @@ Garden inspects your repository and suggests a balanced persona roster with reco
|
|
|
163
161
|
|
|
164
162
|
Confirm or adjust the roster with a single click.
|
|
165
163
|
|
|
166
|
-
### 3.
|
|
167
|
-
Garden
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
-
|
|
164
|
+
### 3. Prompt-Based Swarm Bootstrapping (`launch-workers`)
|
|
165
|
+
Garden generates raw markdown prompt cards wrapped in 10 backticks for each worker:
|
|
166
|
+
```bash
|
|
167
|
+
garden prompts
|
|
168
|
+
```
|
|
169
|
+
- The operator copies and pastes each prompt block into a separate terminal window or coding harness (Claude Code, OpenCode, Antigravity, Pi, Cursor).
|
|
170
|
+
- Each session enters the project directory, sets `RHIZO_AGENT_NAME`, registers on the bus with `rhizo open`, and arms its single-shot listener with `rhizo listen`.
|
|
171
|
+
- The Orchestrator verifies readiness via `rhizo who --json` before dispatching tasks.
|
|
172
172
|
|
|
173
173
|
### 4. The Dialectical Pump (`dialectical-pump`)
|
|
174
174
|
The personas deliberate across three empirical stages:
|
package/SKILL.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: garden
|
|
3
|
-
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,
|
|
3
|
+
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, prompt-based worker fleet bootstrapping with 10-backtick copy-paste prompt cards, 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'."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Garden: Multi-Agent Swarm Ceremony & Orchestration Engine
|
|
@@ -25,7 +25,7 @@ Garden directs multi-agent swarms using Rhizo for transport and Vine for workspa
|
|
|
25
25
|
flowchart TD
|
|
26
26
|
subgraph Garden["Garden Layer (Methodology & Ceremonies)"]
|
|
27
27
|
Phase1["Phase 1: choose-personas (Team Selection & Models)"]
|
|
28
|
-
Phase2["Phase 2: launch-workers (
|
|
28
|
+
Phase2["Phase 2: launch-workers (Prompt-Based Session Bootstrapping)"]
|
|
29
29
|
Phase3["Phase 3: dialectical-pump (Research ➔ Design ➔ Audit)"]
|
|
30
30
|
Phase4["Phase 4: plan-implementation (Locking & Strands)"]
|
|
31
31
|
Phase5["Phase 5: orchestrate-swarm (Dispatch & Vine Weaving)"]
|
|
@@ -52,7 +52,7 @@ Execute all five phases sequentially. Never skip phases or invert the order.
|
|
|
52
52
|
| Phase | Sub-Skill | Action | Quality Gate to Proceed |
|
|
53
53
|
| :--- | :--- | :--- | :--- |
|
|
54
54
|
| **Phase 1** | [`choose-personas`](../choose-personas/SKILL.md) | Formulate 3 balanced personas with harness/model pairings. | Operator ratifies `garden-swarm.json`. |
|
|
55
|
-
| **Phase 2** | [`launch-workers`](../launch-workers/SKILL.md) |
|
|
55
|
+
| **Phase 2** | [`launch-workers`](../launch-workers/SKILL.md) | Generate 10-backtick worker prompt cards for operator pasting into sessions. | `rhizo who --json` confirms 100% of workers active. |
|
|
56
56
|
| **Phase 3** | [`dialectical-pump`](../dialectical-pump/SKILL.md) | Grounded triadic deliberation: research, design, adversarial audit. | Zero open `CRIT` or `BLOCKER` defects in `audit_report.md`. |
|
|
57
57
|
| **Phase 4** | [`plan-implementation`](../plan-implementation/SKILL.md) | Author master implementation plan with locking schedules and strands. | Complete `implementation_plan.md` with task-locking matrix. |
|
|
58
58
|
| **Phase 5** | [`orchestrate-swarm`](../orchestrate-swarm/SKILL.md) | Main-chat governor: task dispatch, heartbeat monitoring, trunk weaving. | All plan tasks woven via `vine weave` after passing Two-Key Gate. |
|
|
@@ -76,3 +76,29 @@ Never merge code into the canonical trunk without a verified Two-Key Gate pass (
|
|
|
76
76
|
<FORBIDDEN>
|
|
77
77
|
Never stage coordination metadata (*.lock, .rhizo.*, .vine.json, workspaces/) into Git. Keep all agent state ignored.
|
|
78
78
|
</FORBIDDEN>
|
|
79
|
+
|
|
80
|
+
<CRITICAL>
|
|
81
|
+
Compaction Preservation Rider (GVR-010):
|
|
82
|
+
Whenever context summarization or compaction occurs, the coding harness MUST preserve the `SWARM_RUNTIME_STATE` block verbatim in the compacted summary preamble so the agent immediately retains its operational identity, assigned workspace, peers, and active listeners without operator re-prompting.
|
|
83
|
+
|
|
84
|
+
Maintain this exact block in the working context:
|
|
85
|
+
<!-- SWARM_RUNTIME_STATE: DO NOT DISCARD OR ABBREVIATE IN COMPACTION -->
|
|
86
|
+
- AGENT_NAME: <codename> (Role: <role>)
|
|
87
|
+
- WORKSPACE_MODE: Root Trunk | Strand (<path>)
|
|
88
|
+
- ACTIVE_STRAND: <branch> (Parent: <parent_branch>)
|
|
89
|
+
- ACTIVE_PEERS:
|
|
90
|
+
* <peer_codename> (<project>: <current_task_description>)
|
|
91
|
+
- ACTIVE_LISTENER: <task_id_or_pid> (Listening on inbox: <codename>)
|
|
92
|
+
- ACTIVE_FENCING_TOKENS: <lock_key>=<token_int>
|
|
93
|
+
<!-- END_SWARM_RUNTIME_STATE -->
|
|
94
|
+
</CRITICAL>
|
|
95
|
+
|
|
96
|
+
---
|
|
97
|
+
|
|
98
|
+
## 4. Responsiveness Watchdog & Operator Escalation Protocol (GVR-011)
|
|
99
|
+
|
|
100
|
+
To prevent silent deadlocks when workers stall, crash, or fail to re-arm listeners:
|
|
101
|
+
1. **Health Probing**: Run `rhizo probe <agent> [--json]` to inspect listener PID liveness, inbox unread depth, and heartbeat age.
|
|
102
|
+
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:
|
|
103
|
+
- **Escalate Immediately**: Prompt the operator via `ask_question` with the diagnostic status.
|
|
104
|
+
- **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>`.
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
package/package.json
CHANGED
package/skills/garden/SKILL.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: garden
|
|
3
|
-
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,
|
|
3
|
+
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, prompt-based worker fleet bootstrapping with 10-backtick copy-paste prompt cards, 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'."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Garden: Multi-Agent Swarm Ceremony & Orchestration Engine
|
|
@@ -25,7 +25,7 @@ Garden directs multi-agent swarms using Rhizo for transport and Vine for workspa
|
|
|
25
25
|
flowchart TD
|
|
26
26
|
subgraph Garden["Garden Layer (Methodology & Ceremonies)"]
|
|
27
27
|
Phase1["Phase 1: choose-personas (Team Selection & Models)"]
|
|
28
|
-
Phase2["Phase 2: launch-workers (
|
|
28
|
+
Phase2["Phase 2: launch-workers (Prompt-Based Session Bootstrapping)"]
|
|
29
29
|
Phase3["Phase 3: dialectical-pump (Research ➔ Design ➔ Audit)"]
|
|
30
30
|
Phase4["Phase 4: plan-implementation (Locking & Strands)"]
|
|
31
31
|
Phase5["Phase 5: orchestrate-swarm (Dispatch & Vine Weaving)"]
|
|
@@ -52,7 +52,7 @@ Execute all five phases sequentially. Never skip phases or invert the order.
|
|
|
52
52
|
| Phase | Sub-Skill | Action | Quality Gate to Proceed |
|
|
53
53
|
| :--- | :--- | :--- | :--- |
|
|
54
54
|
| **Phase 1** | [`choose-personas`](../choose-personas/SKILL.md) | Formulate 3 balanced personas with harness/model pairings. | Operator ratifies `garden-swarm.json`. |
|
|
55
|
-
| **Phase 2** | [`launch-workers`](../launch-workers/SKILL.md) |
|
|
55
|
+
| **Phase 2** | [`launch-workers`](../launch-workers/SKILL.md) | Generate 10-backtick worker prompt cards for operator pasting into sessions. | `rhizo who --json` confirms 100% of workers active. |
|
|
56
56
|
| **Phase 3** | [`dialectical-pump`](../dialectical-pump/SKILL.md) | Grounded triadic deliberation: research, design, adversarial audit. | Zero open `CRIT` or `BLOCKER` defects in `audit_report.md`. |
|
|
57
57
|
| **Phase 4** | [`plan-implementation`](../plan-implementation/SKILL.md) | Author master implementation plan with locking schedules and strands. | Complete `implementation_plan.md` with task-locking matrix. |
|
|
58
58
|
| **Phase 5** | [`orchestrate-swarm`](../orchestrate-swarm/SKILL.md) | Main-chat governor: task dispatch, heartbeat monitoring, trunk weaving. | All plan tasks woven via `vine weave` after passing Two-Key Gate. |
|
|
@@ -76,3 +76,29 @@ Never merge code into the canonical trunk without a verified Two-Key Gate pass (
|
|
|
76
76
|
<FORBIDDEN>
|
|
77
77
|
Never stage coordination metadata (*.lock, .rhizo.*, .vine.json, workspaces/) into Git. Keep all agent state ignored.
|
|
78
78
|
</FORBIDDEN>
|
|
79
|
+
|
|
80
|
+
<CRITICAL>
|
|
81
|
+
Compaction Preservation Rider (GVR-010):
|
|
82
|
+
Whenever context summarization or compaction occurs, the coding harness MUST preserve the `SWARM_RUNTIME_STATE` block verbatim in the compacted summary preamble so the agent immediately retains its operational identity, assigned workspace, peers, and active listeners without operator re-prompting.
|
|
83
|
+
|
|
84
|
+
Maintain this exact block in the working context:
|
|
85
|
+
<!-- SWARM_RUNTIME_STATE: DO NOT DISCARD OR ABBREVIATE IN COMPACTION -->
|
|
86
|
+
- AGENT_NAME: <codename> (Role: <role>)
|
|
87
|
+
- WORKSPACE_MODE: Root Trunk | Strand (<path>)
|
|
88
|
+
- ACTIVE_STRAND: <branch> (Parent: <parent_branch>)
|
|
89
|
+
- ACTIVE_PEERS:
|
|
90
|
+
* <peer_codename> (<project>: <current_task_description>)
|
|
91
|
+
- ACTIVE_LISTENER: <task_id_or_pid> (Listening on inbox: <codename>)
|
|
92
|
+
- ACTIVE_FENCING_TOKENS: <lock_key>=<token_int>
|
|
93
|
+
<!-- END_SWARM_RUNTIME_STATE -->
|
|
94
|
+
</CRITICAL>
|
|
95
|
+
|
|
96
|
+
---
|
|
97
|
+
|
|
98
|
+
## 4. Responsiveness Watchdog & Operator Escalation Protocol (GVR-011)
|
|
99
|
+
|
|
100
|
+
To prevent silent deadlocks when workers stall, crash, or fail to re-arm listeners:
|
|
101
|
+
1. **Health Probing**: Run `rhizo probe <agent> [--json]` to inspect listener PID liveness, inbox unread depth, and heartbeat age.
|
|
102
|
+
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:
|
|
103
|
+
- **Escalate Immediately**: Prompt the operator via `ask_question` with the diagnostic status.
|
|
104
|
+
- **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>`.
|
|
@@ -1,106 +1,118 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: launch-workers
|
|
3
|
-
description: "
|
|
3
|
+
description: "Generates and formats X distinct copy-pasteable bootstrap prompts for new agent sessions (Claude Code, Pi, OpenCode, Antigravity, etc.) to join the Garden work group on Rhizo and Vine. Reads garden-swarm.json, configures identities, environment setup (RHIZO_AGENT_NAME, cd, rhizo open), single-shot listener discipline, task claiming, and Vine strand isolation. Spits out prompt blocks wrapped in 10 backticks for clean, unrendered raw markdown copying, and verifies cluster heartbeat readiness via rhizo who --json before handing off. Triggers: 'launch workers', 'spin up workers', 'start worker swarm', 'generate worker prompts', 'bootstrap swarm', 'launch fleet'."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
# `launch-workers`:
|
|
6
|
+
# `launch-workers`: Prompt-Based Swarm Bootstrapping & Work Group Onboarding
|
|
7
7
|
|
|
8
|
-
> **From Manifest to
|
|
9
|
-
> *
|
|
8
|
+
> **From Manifest to Coordinated Sessions Across Any AI Harness**
|
|
9
|
+
> *Garden generates self-contained, 10-backtick-fenced prompt cards for the human operator to paste into separate terminal tabs or coding harnesses (Claude Code, OpenCode, Antigravity, Pi, Cursor). Each session is immediately grounded in its identity, joins the Rhizo work group, and arms its listener.*
|
|
10
10
|
|
|
11
11
|
---
|
|
12
12
|
|
|
13
|
-
## 1. System
|
|
14
|
-
|
|
15
|
-
1.
|
|
16
|
-
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
13
|
+
## 1. System Philosophy & Invariants
|
|
14
|
+
|
|
15
|
+
1. **Human-in-the-Loop Session Autonomy**:
|
|
16
|
+
- We do not blindly spawn tmux background processes or attempt to drive terminal multiplexers with fragile subshell scripting.
|
|
17
|
+
- The operator chooses the harness and model for each worker (e.g. Claude Code CLI in one tab, OpenCode in another, Antigravity in a third).
|
|
18
|
+
2. **Raw Markdown 10-Backtick Fencing**:
|
|
19
|
+
<CRITICAL>
|
|
20
|
+
When outputting prompt cards in stdout, artifacts, or chat, every prompt block MUST be wrapped in exactly 10 backticks:
|
|
21
|
+
``````````markdown
|
|
22
|
+
...
|
|
23
|
+
``````````
|
|
24
|
+
This guarantees that nested backtick fences (```bash) and internal markdown headers inside the prompts do NOT prematurely terminate the code block or render markdown, preserving pristine raw text for one-click clipboard copying.
|
|
25
|
+
</CRITICAL>
|
|
26
|
+
3. **Single-Shot Listener Discipline**:
|
|
27
|
+
<CRITICAL>
|
|
28
|
+
Inside worker prompts, `rhizo listen <name>` must always be presented as a single-shot, blocking foreground command with zero timeout (infinite wait).
|
|
29
|
+
NEVER wrap `rhizo listen` in a shell loop (`while true; do rhizo listen; done` or `until rhizo listen; do ...`). Loops trap message payloads inside unmonitored subshell logs and hang coordination.
|
|
30
|
+
</CRITICAL>
|
|
31
|
+
4. **Zero Dirty Commits**:
|
|
32
|
+
- Never stage coordination state (`.rhizo.*`, `*.lock`, `.vine.json`, `workspaces/`) into Git.
|
|
27
33
|
|
|
28
34
|
---
|
|
29
35
|
|
|
30
|
-
## 2. The
|
|
36
|
+
## 2. The Bootstrapping Flow
|
|
31
37
|
|
|
32
38
|
```mermaid
|
|
33
39
|
sequenceDiagram
|
|
34
40
|
autonumber
|
|
35
41
|
participant Orch as Main Chat (Orchestrator)
|
|
36
|
-
participant
|
|
37
|
-
participant
|
|
38
|
-
participant
|
|
42
|
+
participant Garden as garden prompts / launch
|
|
43
|
+
participant Op as Human Operator
|
|
44
|
+
participant Workers as New Terminal Sessions (Claude, OpenCode, etc.)
|
|
39
45
|
participant Redis as Rhizo (Redis Bus)
|
|
40
46
|
|
|
41
|
-
Orch->>
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
47
|
+
Orch->>Garden: Runs garden prompts (or garden launch)
|
|
48
|
+
Garden-->>Orch: Emits X prompt cards wrapped in 10 backticks
|
|
49
|
+
Orch->>Op: Displays formatted prompt blocks to operator
|
|
50
|
+
Op->>Workers: Pastes Prompt #1 into Session 1, Prompt #2 into Session 2...
|
|
51
|
+
loop Each Pasted Worker Session
|
|
52
|
+
Workers->>Workers: Sets RHIZO_AGENT_NAME & enters target directory
|
|
53
|
+
Workers->>Redis: Runs rhizo open <name> "<tags>"
|
|
54
|
+
Workers->>Redis: Runs rhizo listen <name> (blocks waiting for tasks)
|
|
49
55
|
end
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
Orch->>
|
|
56
|
+
Orch->>Redis: Runs rhizo who --json to verify readiness gate
|
|
57
|
+
Redis-->>Orch: All workers active and listening
|
|
58
|
+
Orch->>Op: Confirms swarm is ready for task dispatch
|
|
53
59
|
```
|
|
54
60
|
|
|
55
61
|
---
|
|
56
62
|
|
|
57
63
|
## 3. Execution Procedure
|
|
58
64
|
|
|
59
|
-
### Step 1:
|
|
60
|
-
|
|
65
|
+
### Step 1: Generate Worker Bootstrap Prompts
|
|
66
|
+
Run `garden prompts` (or `garden launch`) from the project root:
|
|
61
67
|
|
|
62
68
|
```bash
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
69
|
+
# Output all worker prompts to terminal (and optionally write to file):
|
|
70
|
+
garden prompts --write garden-prompts.md
|
|
71
|
+
|
|
72
|
+
# Or generate for a specific worker:
|
|
73
|
+
garden prompts --worker architect
|
|
67
74
|
```
|
|
68
75
|
|
|
69
|
-
-
|
|
70
|
-
-
|
|
76
|
+
If `garden-swarm.json` exists in the repository, Garden uses its configured personas, mandates, harnesses, and models. If missing, Garden automatically synthesizes the standard balanced triad:
|
|
77
|
+
- `@architect` (Marcus Vance - Staff Systems Architect)
|
|
78
|
+
- `@auditor` (Caleb Thorne - Verification & Adversarial Auditor)
|
|
79
|
+
- `@implementer` (Elena Rostova - DevEx & Implementation Lead)
|
|
80
|
+
|
|
81
|
+
### Step 2: Present & Paste Prompts into Sessions
|
|
82
|
+
The operator opens a separate terminal window, tab, or harness session for each worker, then copies and pastes the corresponding raw block from the 10-backtick pre block.
|
|
83
|
+
|
|
84
|
+
Each prompt immediately instructs the agent to:
|
|
85
|
+
1. `cd "<project_dir>"`
|
|
86
|
+
2. `export RHIZO_AGENT_NAME="<name>"`
|
|
87
|
+
3. `rhizo open "<name>" "<tags>"`
|
|
88
|
+
4. `rhizo listen "<name>"` (blocking until the Orchestrator delivers a task)
|
|
71
89
|
|
|
72
|
-
### Step
|
|
73
|
-
Before dispatching tasks, verify that every worker
|
|
90
|
+
### Step 3: Verify Cluster Readiness Gate
|
|
91
|
+
Before dispatching tasks, verify that every worker has registered in Redis and is showing active heartbeats:
|
|
74
92
|
|
|
75
93
|
```bash
|
|
76
94
|
rhizo who --json
|
|
77
95
|
```
|
|
78
96
|
|
|
79
97
|
**Pass Criteria**:
|
|
80
|
-
1. All worker
|
|
98
|
+
1. All worker codenames from the manifest appear in `active_agents`.
|
|
81
99
|
2. Heartbeats have active TTLs (> 0).
|
|
82
|
-
3.
|
|
83
|
-
|
|
84
|
-
### Step 3: Inspect Terminal Buffer (Health Check)
|
|
85
|
-
To check the initial logs or output of any worker without leaving your chat:
|
|
86
|
-
|
|
87
|
-
```bash
|
|
88
|
-
# Capture last 20 lines of worker 'architect' (window 0)
|
|
89
|
-
tmux capture-pane -p -t garden-<project>:0 | tail -n 20
|
|
90
|
-
```
|
|
100
|
+
3. `rhizo probe <agent>` shows an active listener PID ready to receive work.
|
|
91
101
|
|
|
92
102
|
---
|
|
93
103
|
|
|
94
104
|
## 4. Teardown & Swarm Cleanup
|
|
95
105
|
|
|
96
|
-
When the
|
|
106
|
+
When the swarm mission is completed, or when canceling a run:
|
|
97
107
|
|
|
98
108
|
```bash
|
|
99
109
|
# Gracefully deregister all swarm agents from Redis:
|
|
110
|
+
garden teardown
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Or manually:
|
|
114
|
+
```bash
|
|
100
115
|
for worker in $(python3 -c "import json; [print(w['name']) for w in json.load(open('garden-swarm.json'))['workers']]"); do
|
|
101
116
|
rhizo close "$worker" 2>/dev/null || true
|
|
102
117
|
done
|
|
103
|
-
|
|
104
|
-
# Terminate the tmux session:
|
|
105
|
-
tmux kill-session -t garden-<project> 2>/dev/null || true
|
|
106
118
|
```
|
|
@@ -17,6 +17,22 @@ The main chat session assumes the role of **Supreme Orchestrator**:
|
|
|
17
17
|
- **Strict Transport Discipline**: All task assignments, handoffs, and cancellation interrupts flow exclusively over the Rhizo Redis bus (`rhizo send`, `rhizo reply`, `rhizo enqueue`).
|
|
18
18
|
- **Gated Integration**: Never run `git merge` directly. Only weave branches that have passed both Key 1 (mechanical merge-tree) and Key 2 (live compiler/tests) inside their Vine strands.
|
|
19
19
|
|
|
20
|
+
<CRITICAL>
|
|
21
|
+
Compaction Preservation Rider (GVR-010):
|
|
22
|
+
Whenever context summarization or compaction occurs, the coding harness MUST preserve the `SWARM_RUNTIME_STATE` block verbatim in the compacted summary preamble so the agent immediately retains its operational identity, assigned workspace, peers, and active listeners without operator re-prompting.
|
|
23
|
+
|
|
24
|
+
Maintain this exact block in the working context:
|
|
25
|
+
<!-- SWARM_RUNTIME_STATE: DO NOT DISCARD OR ABBREVIATE IN COMPACTION -->
|
|
26
|
+
- AGENT_NAME: <codename> (Role: Supreme Orchestrator)
|
|
27
|
+
- WORKSPACE_MODE: Root Trunk (/Users/eek/Development/<project>)
|
|
28
|
+
- ACTIVE_STRAND: canonical trunk
|
|
29
|
+
- ACTIVE_PEERS:
|
|
30
|
+
* <peer_codename> (<project>: <current_task_description>)
|
|
31
|
+
- ACTIVE_LISTENER: <task_id_or_pid> (Listening on inbox: <codename>)
|
|
32
|
+
- ACTIVE_FENCING_TOKENS: <lock_key>=<token_int>
|
|
33
|
+
<!-- END_SWARM_RUNTIME_STATE -->
|
|
34
|
+
</CRITICAL>
|
|
35
|
+
|
|
20
36
|
---
|
|
21
37
|
|
|
22
38
|
## 2. The Runtime Governance Loop
|
|
@@ -59,15 +75,39 @@ Depending on the task distribution model in `implementation_plan.md`:
|
|
|
59
75
|
--body '{"task_id": "task-test-harness", "strand": "strand/task-test-harness"}'
|
|
60
76
|
```
|
|
61
77
|
|
|
62
|
-
### SOP 2: Monitoring Swarm Health &
|
|
63
|
-
Check active workers and
|
|
78
|
+
### SOP 2: Monitoring Swarm Health, Watchdog & Escalation (GVR-011)
|
|
79
|
+
Check active workers and cluster status:
|
|
64
80
|
```bash
|
|
65
81
|
rhizo who --json
|
|
66
82
|
```
|
|
67
83
|
|
|
68
|
-
|
|
84
|
+
#### Responsiveness Watchdog & Health Probing
|
|
85
|
+
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):
|
|
86
|
+
```bash
|
|
87
|
+
rhizo probe <worker> --json
|
|
88
|
+
```
|
|
89
|
+
The probe returns:
|
|
90
|
+
- `inbox_depth`: Number of unconsumed messages (if > 0, the worker hasn't picked up the task).
|
|
91
|
+
- `listener`: Whether the listener process PID is active (`LISTENING (pid: N)`) or dead (`NO_LISTENER`).
|
|
92
|
+
- `heartbeat`: Last seen age in seconds and heartbeat TTL.
|
|
93
|
+
|
|
94
|
+
#### Operator Escalation Protocol
|
|
95
|
+
If `rhizo probe` indicates a stalled or dead worker (`NO_LISTENER` or `STALE` with unread inbox messages):
|
|
96
|
+
1. **Never Hang Silently**: The Supreme Orchestrator must immediately surface an escalation to the operator via `ask_question`.
|
|
97
|
+
2. **Present Diagnostic**:
|
|
98
|
+
- Alert: `⚠️ SWARM STALL DETECTED: @<worker> has not responded to <subject>`
|
|
99
|
+
- Diagnostic: `Inbox: N unread | Listener: NO_LISTENER | Status: STALE`
|
|
100
|
+
3. **Select Remediation Action**:
|
|
101
|
+
- Option 1 (Re-arm): Execute `rhizo listen <worker>` in the worker's assigned terminal pane.
|
|
102
|
+
- Option 2 (Reboot): Restart the worker harness process in that pane.
|
|
103
|
+
- Option 3 (Reassign): Re-route the task atomically to another active worker:
|
|
104
|
+
```bash
|
|
105
|
+
rhizo reroute <stalled_worker> <new_worker> --all
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
If a worker is waiting for a lease or has held a lock too long, probe its listener and inbox status:
|
|
69
109
|
```bash
|
|
70
|
-
|
|
110
|
+
rhizo probe <worker>
|
|
71
111
|
```
|
|
72
112
|
|
|
73
113
|
### SOP 3: Verifying Two-Key Gate & Weaving
|
|
@@ -117,12 +157,6 @@ When all checkboxes in `implementation_plan.md` are marked `- [x]`:
|
|
|
117
157
|
1. Run final repository-wide test suite and linter on the canonical trunk.
|
|
118
158
|
2. Gracefully deregister all swarm agents:
|
|
119
159
|
```bash
|
|
120
|
-
|
|
121
|
-
rhizo close "$worker" 2>/dev/null || true
|
|
122
|
-
done
|
|
123
|
-
```
|
|
124
|
-
3. Kill the tmux session:
|
|
125
|
-
```bash
|
|
126
|
-
tmux kill-session -t garden-<project> 2>/dev/null || true
|
|
160
|
+
garden teardown
|
|
127
161
|
```
|
|
128
|
-
|
|
162
|
+
3. Output the final executive summary to the human operator.
|