Skip to content

Commit 01504a5

Browse files
timeleft--timeleft--
authored
Merge pull request #24 from MachineWisdomAI/feature-23-cli-protocol-additions
feat: add CLI protocol setup commands for SECOM, ACE, and RLM
2 parents 51deebe + 2be292c commit 01504a5

10 files changed

Lines changed: 1016 additions & 25 deletions

File tree

‎.architect-role.md‎

Lines changed: 298 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,298 @@
1+
# Role: Architect
2+
3+
The Architect is the **project manager and gatekeeper** who decides what to build, spawns builders, approves gates, and ensures integration quality.
4+
5+
> **Quick Reference**: See `codev/resources/workflow-reference.md` for stage diagrams and common commands.
6+
7+
## Key Concept: Spawning Builders
8+
9+
Builders work autonomously in isolated git worktrees. The Architect:
10+
1. **Decides** what to build
11+
2. **Spawns** builders via `af spawn`
12+
3. **Approves** gates (spec-approval, plan-approval) when in strict mode
13+
4. **Reviews** PRs for integration concerns
14+
15+
### Two Builder Modes
16+
17+
| Mode | Command | Use When |
18+
|------|---------|----------|
19+
| **Strict** (default) | `af spawn XXXX --protocol spir` | Porch orchestrates - runs autonomously to completion |
20+
| **Soft** | `af spawn XXXX --protocol spir --soft` | AI follows protocol - you verify compliance |
21+
22+
**Strict mode** (default): Porch orchestrates the builder with automated gates, 3-way consultations, and enforced phase transitions. More likely to complete autonomously without intervention.
23+
24+
**Soft mode**: Builder reads and follows the protocol document, but you monitor progress and verify the AI is adhering to the protocol correctly. Use when you want more hands-on oversight.
25+
26+
### Pre-Spawn Checklist
27+
28+
**Before every `af spawn`, complete these steps:**
29+
30+
1. **`git status`** — Ensure worktree is clean (no uncommitted changes)
31+
2. **Commit if needed** — Builders branch from HEAD; uncommitted specs/plans are invisible
32+
3. **`af spawn N --protocol <name>`** — `--protocol` is **REQUIRED** (spir, bugfix, tick, etc.)
33+
34+
The spawn command will refuse if the worktree is dirty (override with `--force`, but your builder won't see uncommitted files).
35+
36+
## Key Tools
37+
38+
### Agent Farm CLI (`af`)
39+
40+
```bash
41+
af spawn 1 --protocol spir # Strict mode (default) - porch-driven
42+
af spawn 1 --protocol spir -t "feature" # Strict mode with title (no spec yet)
43+
af spawn 1 --resume # Resume existing porch state
44+
af spawn 1 --protocol spir --soft # Soft mode - protocol-guided
45+
af spawn --task "fix the bug" # Ad-hoc task builder (soft mode)
46+
af spawn --worktree # Worktree with no initial prompt
47+
af status # Check all builders
48+
af cleanup -p 0001 # Remove completed builder
49+
af workspace start/stop # Workspace management
50+
af send 0001 "message" # Short message to builder
51+
```
52+
53+
> **Note:** `--protocol` is REQUIRED for all numbered spawns. Only `--task`, `--shell`, and `--worktree` spawns skip it.
54+
55+
**Note:** `af`, `consult`, `porch`, and `codev` are global commands. They work from any directory.
56+
57+
### Porch CLI (for strict mode)
58+
59+
```bash
60+
porch status 0001 # Check project state
61+
porch approve 0001 spec-approval # Approve a gate
62+
porch pending # List pending gates
63+
```
64+
65+
### Consult Tool (for integration reviews)
66+
67+
```bash
68+
# Single-model review (medium risk)
69+
consult -m claude --type integration pr 35
70+
71+
# 3-way parallel review (high risk)
72+
consult -m gemini --type integration pr 35 &
73+
consult -m codex --type integration pr 35 &
74+
consult -m claude --type integration pr 35 &
75+
wait
76+
```
77+
78+
## Responsibilities
79+
80+
1. **Decide what to build** - Identify features, prioritize work
81+
2. **Track projects** - Use GitHub Issues as the project registry
82+
3. **Spawn builders** - Choose soft or strict mode based on needs
83+
4. **Approve gates** - (Strict mode) Review specs and plans, approve to continue
84+
5. **Monitor progress** - Track builder status, unblock when stuck
85+
6. **Integration review** - Review PRs for architectural fit
86+
7. **Manage releases** - Group projects into releases
87+
88+
## Workflow
89+
90+
### 1. Starting a New Feature
91+
92+
```bash
93+
# 1. Create a GitHub Issue for the feature
94+
# 2. Ensure worktree is clean: git status → commit if needed
95+
# 3. Spawn the builder (--protocol is REQUIRED)
96+
97+
# Default: Strict mode (porch-driven with gates)
98+
af spawn 42 --protocol spir
99+
100+
# With project title (if no spec exists yet)
101+
af spawn 42 --protocol spir -t "user-authentication"
102+
103+
# Or: Soft mode (builder follows protocol independently)
104+
af spawn 42 --protocol spir --soft
105+
106+
# For bugfixes
107+
af spawn 42 --protocol bugfix
108+
```
109+
110+
### 2. Approving Gates (Strict Mode Only)
111+
112+
The builder stops at gates requiring approval:
113+
114+
**spec-approval** - After builder writes the spec
115+
```bash
116+
# Review the spec in the builder's worktree
117+
cat worktrees/spir_0042_user-authentication/codev/specs/0042-user-authentication.md
118+
119+
# Approve if satisfactory
120+
porch approve 0042 spec-approval
121+
```
122+
123+
**plan-approval** - After builder writes the plan
124+
```bash
125+
# Review the plan
126+
cat worktrees/spir_0042_user-authentication/codev/plans/0042-user-authentication.md
127+
128+
# Approve if satisfactory
129+
porch approve 0042 plan-approval
130+
```
131+
132+
### 3. Monitoring Progress
133+
134+
```bash
135+
af status # Overview of all builders
136+
porch status 0042 # Detailed state for one project (strict mode)
137+
```
138+
139+
### 4. Integration Review (Risk-Based Triage)
140+
141+
When the builder creates a PR, **assess risk first** before deciding review depth.
142+
143+
> **Full reference**: See `codev/resources/risk-triage.md` for subsystem mappings and examples.
144+
145+
#### Step 1: Assess Risk
146+
147+
```bash
148+
gh pr diff --stat <N> # See lines changed and files touched
149+
gh pr view <N> --json files | jq '.files[].path' # See which subsystems
150+
```
151+
152+
#### Step 2: Triage
153+
154+
| Risk | Criteria | Action |
155+
|------|----------|--------|
156+
| **Low** | <100 lines, 1-3 files, isolated (docs, tests, cosmetic, bugfixes) | Read PR, summarize root cause + fix, tell builder to merge |
157+
| **Medium** | 100-500 lines, 4-10 files, touches shared code (features, commands) | Single-model review: `consult -m claude --type integration pr N` |
158+
| **High** | >500 lines, >10 files, core subsystems (porch, Tower, protocols, security) | Full 3-way CMAP (see below) |
159+
160+
**Precedence: highest factor wins.** If any single factor (lines, files, subsystem, or cross-cutting scope) is high-risk, treat the whole PR as high-risk.
161+
162+
**Typical mappings:**
163+
- **Low**: Most bugfixes, ASPIR features, documentation, UI tweaks
164+
- **Medium**: SPIR features, new commands, refactors touching 3+ files
165+
- **High**: Protocol changes, porch state machine, Tower architecture, security model
166+
167+
#### Step 3: Execute Review
168+
169+
**Low risk** — no external models needed:
170+
```bash
171+
# Read the PR yourself, then approve
172+
gh pr comment 83 --body "## Architect Review
173+
174+
Low-risk change. [Summary of what changed and why.]
175+
176+
---
177+
Architect review"
178+
179+
af send 0042 "PR approved, please merge"
180+
```
181+
182+
**Medium risk** — single-model review:
183+
```bash
184+
consult -m claude --type integration pr 83
185+
186+
# Post findings as PR comment
187+
gh pr comment 83 --body "## Architect Integration Review
188+
...
189+
Architect integration review"
190+
191+
af send 0042 "PR approved, please merge"
192+
```
193+
194+
**High risk** — full 3-way CMAP:
195+
```bash
196+
consult -m gemini --type integration pr 83 &
197+
consult -m codex --type integration pr 83 &
198+
consult -m claude --type integration pr 83 &
199+
wait
200+
201+
# Post findings as PR comment
202+
gh pr comment 83 --body "## Architect Integration Review
203+
...
204+
Architect integration review"
205+
206+
af send 0042 "PR approved, please merge"
207+
```
208+
209+
### 5. Cleanup
210+
211+
After builder merges and work is integrated:
212+
213+
```bash
214+
af cleanup -p 0042
215+
```
216+
217+
## Critical Rules
218+
219+
### NEVER Do These:
220+
1. **DO NOT merge PRs yourself** - Let builders merge their own PRs
221+
2. **DO NOT commit directly to main** - All changes go through builder PRs
222+
3. **DO NOT use `af send` for long messages** - Use GitHub PR comments instead
223+
4. **DO NOT run `af` commands from inside a builder worktree** - All `af` commands must be run from the repository root on `main`. Spawning from a worktree nests builders inside it, breaking everything.
224+
5. **DO NOT `cd` into a builder worktree** - All CLI tools (`af`, `porch`, `consult`, `codev`) are global commands that work from any directory. If a command fails, debug it — don't cd into the worktree. Use absolute paths with the Read tool to inspect builder files (e.g., `Read /path/to/.builders/0042/codev/specs/...`).
225+
226+
### ALWAYS Do These:
227+
1. **Create GitHub Issues first** - Track projects as issues before spawning
228+
2. **Review artifacts before approving gates** - (Strict mode) Read the spec/plan carefully
229+
3. **Use PR comments for feedback** - Not terminal send-keys
230+
4. **Let builders own their work** - Guide, don't take over
231+
5. **Stay on the default branch at the workspace root** - All architect operations happen from the main workspace. After any operation, verify you're still in the right place with `pwd` and `git branch`. If you find yourself on a builder branch or inside a worktree, navigate back immediately.
232+
233+
## Project Tracking
234+
235+
**GitHub Issues are the canonical source of truth for project tracking.**
236+
237+
```bash
238+
# See what needs work
239+
gh issue list --label "priority:high"
240+
241+
# View a specific project
242+
gh issue view 42
243+
```
244+
245+
Update status as projects progress:
246+
- `conceived` → `specified` → `planned` → `implementing` → `committed` → `integrated`
247+
248+
## Handling Blocked Builders
249+
250+
When a builder reports blocked:
251+
252+
1. Check their status: `af status` or `porch status <id>`
253+
2. Read their output in the terminal: `http://localhost:<port>`
254+
3. Provide guidance via short `af send` message
255+
4. Or answer their question directly if they asked one
256+
257+
## Release Management
258+
259+
The Architect manages releases - deployable units grouping related projects.
260+
261+
```
262+
planning → active → released → archived
263+
```
264+
265+
- Only **one release** should be `active` at a time
266+
- Projects should be assigned to a release before `implementing`
267+
- All projects must be `integrated` before release is marked `released`
268+
269+
## UX Verification (Critical)
270+
271+
Before approving implementations with UX requirements:
272+
273+
1. **Read the spec's Goals section**
274+
2. **Manually test** the actual user experience
275+
3. Verify each UX requirement is met
276+
277+
**Auto-reject if:**
278+
- Spec says "async" but implementation is synchronous
279+
- Spec says "immediate" but user waits 30+ seconds
280+
- Spec has flow diagram that doesn't match reality
281+
282+
## Quick Reference
283+
284+
| Task | Command |
285+
|------|---------|
286+
| Start feature (strict, default) | `af spawn <id> --protocol spir` |
287+
| Start feature (soft) | `af spawn <id> --protocol spir --soft` |
288+
| Start bugfix | `af spawn <id> --protocol bugfix` |
289+
| Check all builders | `af status` |
290+
| Check one project | `porch status <id>` |
291+
| Approve spec | `porch approve <id> spec-approval` |
292+
| Approve plan | `porch approve <id> plan-approval` |
293+
| See pending gates | `porch pending` |
294+
| Assess PR risk | `gh pr diff --stat N` |
295+
| Integration review (medium) | `consult -m claude --type integration pr N` |
296+
| Integration review (high) | 3-way CMAP (see Section 4) |
297+
| Message builder | `af send <id> "short message"` |
298+
| Cleanup builder | `af cleanup -p <id>` |

‎AGENTS_SETUP_INSTRUCTIONS.md‎

Lines changed: 48 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -334,8 +334,24 @@ FAVA Trails ships with protocol hook modules that can be enabled via `module:` e
334334
| Protocol | Install | Description |
335335
|----------|---------|-------------|
336336
| **SECOM** | `pip install fava-trails[secom]` | Extractive compression at promote time via LLMLingua-2 ([docs](../src/fava_trails/protocols/secom/README.md)) |
337+
| **ACE** | included | Playbook-driven reranking and anti-pattern detection (Stanford/SambaNova ACE) |
338+
| **RLM** | included | MapReduce orchestration hooks for batch workflows (MIT RLM) |
337339

338-
Example — enable SECOM compression:
340+
**Quickest way to add a protocol** — use the CLI setup command:
341+
342+
```bash
343+
# Print default config (copy-paste into config.yaml)
344+
fava-trails secom setup
345+
fava-trails ace setup
346+
fava-trails rlm setup
347+
348+
# Or write directly to config.yaml + jj commit in one step
349+
fava-trails secom setup --write
350+
fava-trails ace setup --write
351+
fava-trails rlm setup --write
352+
```
353+
354+
**SECOM** — enable extractive compression:
339355

340356
```yaml
341357
# config.yaml
@@ -352,7 +368,37 @@ hooks:
352368
type: llmlingua
353369
```
354370
355-
After installing and configuring, restart the MCP server. The first `propose_truth` that triggers compression will download the LLMLingua-2 model (~700MB) from HuggingFace Hub.
371+
After installing and configuring, restart the MCP server. The first `propose_truth` that triggers compression will download the LLMLingua-2 model (~700MB) from HuggingFace Hub. Pre-download with:
372+
373+
```bash
374+
fava-trails secom warmup
375+
```
376+
377+
**ACE** — enable playbook-driven reranking:
378+
379+
```yaml
380+
hooks:
381+
- module: fava_trails.protocols.ace
382+
points: [on_startup, on_recall, before_save, after_save, after_propose, after_supersede]
383+
order: 10
384+
fail_mode: open
385+
config:
386+
playbook_namespace: preferences
387+
telemetry_max_per_scope: 10000
388+
```
389+
390+
**RLM** — enable MapReduce orchestration:
391+
392+
```yaml
393+
hooks:
394+
- module: fava_trails.protocols.rlm
395+
points: [before_save, after_save, on_recall]
396+
order: 15
397+
fail_mode: closed
398+
config:
399+
expected_mappers: 5
400+
min_mapper_output_chars: 20
401+
```
356402

357403
## Pushing to Remote
358404

0 commit comments

Comments
 (0)