@cluesmith/codev 2.0.0-rc.13 → 2.0.0-rc.15
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.
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"kickoff.d.ts","sourceRoot":"","sources":["../../../src/agent-farm/commands/kickoff.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAWH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AA4KD;;GAEG;AACH,wBAAsB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,
|
|
1
|
+
{"version":3,"file":"kickoff.d.ts","sourceRoot":"","sources":["../../../src/agent-farm/commands/kickoff.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAWH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AA4KD;;GAEG;AACH,wBAAsB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CA2KpE"}
|
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
* 3. Starting the porch loop in the builder
|
|
8
8
|
*/
|
|
9
9
|
import { resolve, basename } from 'node:path';
|
|
10
|
-
import { existsSync, readFileSync, symlinkSync } from 'node:fs';
|
|
10
|
+
import { existsSync, readFileSync, symlinkSync, writeFileSync, mkdirSync } from 'node:fs';
|
|
11
11
|
import { readdir } from 'node:fs/promises';
|
|
12
12
|
import { getConfig, ensureDirectories } from '../utils/index.js';
|
|
13
13
|
import { logger, fatal } from '../utils/logger.js';
|
|
@@ -229,9 +229,43 @@ export async function kickoff(options) {
|
|
|
229
229
|
// Start builder session
|
|
230
230
|
const port = await findFreePort(config);
|
|
231
231
|
const sessionName = getSessionName(config, builderId);
|
|
232
|
+
// Create .af directory for launch scripts
|
|
233
|
+
const afDir = resolve(worktreePath, '.af');
|
|
234
|
+
if (!existsSync(afDir)) {
|
|
235
|
+
mkdirSync(afDir, { recursive: true });
|
|
236
|
+
}
|
|
237
|
+
// Create the builder prompt that instructs Claude to run porch
|
|
238
|
+
const builderPrompt = `You are a Builder agent working on project ${projectId}.
|
|
239
|
+
|
|
240
|
+
Your job is to execute the porch protocol loop until completion.
|
|
241
|
+
|
|
242
|
+
## Instructions
|
|
243
|
+
|
|
244
|
+
Run this command repeatedly until the protocol is complete:
|
|
245
|
+
|
|
246
|
+
\`\`\`bash
|
|
247
|
+
${porchCmd} run ${projectId}
|
|
248
|
+
\`\`\`
|
|
249
|
+
|
|
250
|
+
After each run:
|
|
251
|
+
1. If porch prints "🎉 PROTOCOL COMPLETE" - you're done, exit
|
|
252
|
+
2. If porch is waiting for a gate approval - wait for the architect to approve
|
|
253
|
+
3. Otherwise - run \`${porchCmd} run ${projectId}\` again
|
|
254
|
+
|
|
255
|
+
Keep running the porch loop. Do not stop until the protocol is complete or you hit a gate that requires approval.
|
|
256
|
+
|
|
257
|
+
Start now by running: ${porchCmd} run ${projectId}`;
|
|
258
|
+
const promptPath = resolve(afDir, 'builder-prompt.md');
|
|
259
|
+
writeFileSync(promptPath, builderPrompt);
|
|
260
|
+
// Create launch script that starts Claude with the builder prompt
|
|
261
|
+
const launchScript = resolve(afDir, 'launch.sh');
|
|
262
|
+
writeFileSync(launchScript, `#!/bin/bash
|
|
263
|
+
cd "${worktreePath}"
|
|
264
|
+
exec claude --dangerously-skip-permissions -p "$(cat '${promptPath}')"
|
|
265
|
+
`, { mode: 0o755 });
|
|
232
266
|
logger.info('Creating tmux session...');
|
|
233
|
-
// Create tmux session
|
|
234
|
-
await run(`tmux new-session -d -s "${sessionName}" -x 200 -y 50 -c "${worktreePath}"
|
|
267
|
+
// Create tmux session running the launch script (starts Claude automatically)
|
|
268
|
+
await run(`tmux new-session -d -s "${sessionName}" -x 200 -y 50 -c "${worktreePath}" "${launchScript}"`);
|
|
235
269
|
await run(`tmux set-option -t "${sessionName}" status off`);
|
|
236
270
|
await run('tmux set -g mouse on');
|
|
237
271
|
await run('tmux set -g set-clipboard on');
|
|
@@ -262,19 +296,12 @@ export async function kickoff(options) {
|
|
|
262
296
|
type: 'spec',
|
|
263
297
|
};
|
|
264
298
|
upsertBuilder(builder);
|
|
265
|
-
// Auto-start the porch loop in the tmux session
|
|
266
|
-
logger.info('Starting porch protocol loop...');
|
|
267
|
-
const porchRunCmd = `${porchCmd} run ${projectId}`;
|
|
268
|
-
// Use tmux send-keys to start porch in the builder terminal
|
|
269
|
-
// The -l flag sends literal keys (no special interpretation)
|
|
270
|
-
await run(`tmux send-keys -t "${sessionName}" -l '${porchRunCmd}'`);
|
|
271
|
-
await run(`tmux send-keys -t "${sessionName}" Enter`);
|
|
272
299
|
logger.blank();
|
|
273
300
|
logger.success(`Builder ${builderId} started!`);
|
|
274
301
|
logger.kv('Terminal', `http://localhost:${port}`);
|
|
275
302
|
logger.kv('Worktree', worktreePath);
|
|
276
303
|
logger.blank();
|
|
277
|
-
logger.info('
|
|
304
|
+
logger.info('Claude is running the porch protocol loop.');
|
|
278
305
|
logger.info('Watch the terminal or check status with: af status');
|
|
279
306
|
}
|
|
280
307
|
//# sourceMappingURL=kickoff.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"kickoff.js","sourceRoot":"","sources":["../../../src/agent-farm/commands/kickoff.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;
|
|
1
|
+
{"version":3,"file":"kickoff.js","sourceRoot":"","sources":["../../../src/agent-farm/commands/kickoff.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,383 +1,212 @@
|
|
|
1
1
|
# Role: Architect
|
|
2
2
|
|
|
3
|
-
The Architect is the
|
|
3
|
+
The Architect is the **project manager and gatekeeper** who decides what to build, spawns porch-driven builders, approves gates, and ensures integration quality.
|
|
4
4
|
|
|
5
5
|
> **Quick Reference**: See `codev/resources/workflow-reference.md` for stage diagrams and common commands.
|
|
6
6
|
|
|
7
|
-
## Key
|
|
8
|
-
|
|
9
|
-
The Architect relies on two primary tools:
|
|
10
|
-
|
|
11
|
-
### Agent Farm CLI (`af`)
|
|
7
|
+
## Key Concept: Porch-Driven Builders
|
|
12
8
|
|
|
13
|
-
|
|
14
|
-
- `af start/stop` - Dashboard management
|
|
15
|
-
- `af spawn -p XXXX` - Spawn a builder for a spec
|
|
16
|
-
- `af send` - Send short messages to builders
|
|
17
|
-
- `af cleanup` - Remove completed builders
|
|
18
|
-
- `af status` - Check builder status
|
|
19
|
-
- `af open <file>` - Open file for human review
|
|
9
|
+
Builders run autonomously under porch control. The builder (Claude) executes the full protocol:
|
|
20
10
|
|
|
21
|
-
|
|
11
|
+
```
|
|
12
|
+
Specify → Plan → Implement → Review
|
|
13
|
+
```
|
|
22
14
|
|
|
23
|
-
|
|
15
|
+
The Architect does NOT write specs or plans. The builder does that. The Architect:
|
|
16
|
+
1. **Decides** what to build
|
|
17
|
+
2. **Spawns** builders via `af kickoff`
|
|
18
|
+
3. **Approves** gates (spec-approval, plan-approval)
|
|
19
|
+
4. **Reviews** PRs for integration concerns
|
|
24
20
|
|
|
25
|
-
|
|
21
|
+
## Key Tools
|
|
26
22
|
|
|
27
|
-
|
|
28
|
-
- After completing a spec (before presenting to human)
|
|
29
|
-
- After completing a plan (before presenting to human)
|
|
30
|
-
- When reviewing builder PRs (3-way parallel review)
|
|
23
|
+
### Agent Farm CLI (`af`)
|
|
31
24
|
|
|
32
25
|
```bash
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
#
|
|
38
|
-
consult --model gemini --type integration-review pr 83 &
|
|
39
|
-
consult --model codex --type integration-review pr 83 &
|
|
40
|
-
consult --model claude --type integration-review pr 83 &
|
|
41
|
-
wait
|
|
26
|
+
af kickoff -p 0001 --title "feature-name" # Spawn porch-driven builder
|
|
27
|
+
af status # Check all builders
|
|
28
|
+
af cleanup -p 0001 # Remove completed builder
|
|
29
|
+
af start/stop # Dashboard management
|
|
30
|
+
af send 0001 "message" # Short message to builder
|
|
42
31
|
```
|
|
43
32
|
|
|
44
|
-
**
|
|
45
|
-
|
|
46
|
-
**Full reference:** See `consult --help`
|
|
33
|
+
**Note:** `af`, `consult`, `porch`, and `codev` are global commands. They work from any directory.
|
|
47
34
|
|
|
48
|
-
|
|
35
|
+
### Porch CLI
|
|
49
36
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
```
|
|
55
|
-
# Instead of:
|
|
56
|
-
See codev/specs/0022-consult-tool-stateless.md for details.
|
|
57
|
-
|
|
58
|
-
# Use:
|
|
59
|
-
See http://localhost:{PORT}/open-file?path=codev/specs/0022-consult-tool-stateless.md for details.
|
|
37
|
+
```bash
|
|
38
|
+
porch status 0001 # Check project state
|
|
39
|
+
porch approve 0001 spec-approval # Approve a gate
|
|
40
|
+
porch pending # List pending gates
|
|
60
41
|
```
|
|
61
42
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
**Finding the dashboard port**: Run `af status` to see the dashboard URL. The default is 4200, but varies when multiple projects are running.
|
|
43
|
+
### Consult Tool (for integration reviews)
|
|
65
44
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
3. **DO NOT commit directly to main** - All changes go through PRs.
|
|
74
|
-
4. **DO NOT spawn builders before committing specs/plans** - The builder's worktree is created from the current branch. If specs/plans aren't committed, the builder won't have access to them.
|
|
75
|
-
|
|
76
|
-
### ✅ ALWAYS Do These:
|
|
77
|
-
1. **Leave PR comments for reviews** - Use `gh pr comment` to post review feedback.
|
|
78
|
-
2. **Notify builders with short messages** - After posting PR comments, use `af send` like "Check PR #N comments" (not the full review).
|
|
79
|
-
3. **Let builders merge their PRs** - After approving, tell the builder to merge. Don't do it yourself.
|
|
80
|
-
4. **Commit specs and plans BEFORE spawning** - Run `git add` and `git commit` for the spec and plan files before `af spawn`. The builder needs these files in the worktree.
|
|
45
|
+
```bash
|
|
46
|
+
# 3-way parallel integration review of builder's PR
|
|
47
|
+
consult --model gemini --type integration-review pr 35 &
|
|
48
|
+
consult --model codex --type integration-review pr 35 &
|
|
49
|
+
consult --model claude --type integration-review pr 35 &
|
|
50
|
+
wait
|
|
51
|
+
```
|
|
81
52
|
|
|
82
53
|
## Responsibilities
|
|
83
54
|
|
|
84
|
-
1. **
|
|
85
|
-
2. **Maintain
|
|
86
|
-
3. **
|
|
87
|
-
4. **
|
|
88
|
-
5. **
|
|
89
|
-
6. **
|
|
90
|
-
7. **
|
|
91
|
-
8. **Review and integrate** - Review Builder PRs, let builders merge them
|
|
92
|
-
9. **Maintain quality** - Ensure consistency across Builder outputs
|
|
93
|
-
10. **Enforce spec compliance** - Verify implementations match specs exactly
|
|
94
|
-
|
|
95
|
-
## Spec Compliance Enforcement (CRITICAL)
|
|
55
|
+
1. **Decide what to build** - Identify features, prioritize work
|
|
56
|
+
2. **Maintain project list** - Track all projects in `codev/projectlist.md`
|
|
57
|
+
3. **Kickoff builders** - `af kickoff -p <id> --title "feature-name"`
|
|
58
|
+
4. **Approve gates** - Review specs and plans, approve to continue
|
|
59
|
+
5. **Monitor progress** - Track builder status, unblock when stuck
|
|
60
|
+
6. **Integration review** - Review PRs for architectural fit
|
|
61
|
+
7. **Manage releases** - Group projects into releases
|
|
96
62
|
|
|
97
|
-
|
|
63
|
+
## Workflow
|
|
98
64
|
|
|
99
|
-
###
|
|
65
|
+
### 1. Starting a New Feature
|
|
100
66
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
### The Trust Hierarchy
|
|
107
|
-
|
|
108
|
-
```
|
|
109
|
-
SPEC (source of truth)
|
|
110
|
-
↓
|
|
111
|
-
PLAN (implementation guide derived from spec)
|
|
112
|
-
↓
|
|
113
|
-
EXISTING CODE (NOT TRUSTED - must be validated against spec)
|
|
67
|
+
```bash
|
|
68
|
+
# 1. Reserve project number in projectlist.md
|
|
69
|
+
# 2. Kickoff the builder
|
|
70
|
+
af kickoff -p 0042 --title "user-authentication"
|
|
114
71
|
```
|
|
115
72
|
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
### Before Each Implementation Phase
|
|
119
|
-
|
|
120
|
-
Ask yourself:
|
|
121
|
-
1. "Have I read the spec in the last 30 minutes?"
|
|
122
|
-
2. "Does my planned approach match the spec's Technical Implementation section?"
|
|
123
|
-
3. "If the spec has code examples, am I following them?"
|
|
124
|
-
4. "If the spec has 'Traps to Avoid', have I checked each one?"
|
|
125
|
-
5. "Does the existing code I'm building on match the spec?"
|
|
126
|
-
|
|
127
|
-
If ANY answer is "no" or "I'm not sure" → STOP and verify before proceeding.
|
|
128
|
-
|
|
129
|
-
### Why This Exists
|
|
130
|
-
|
|
131
|
-
On 2025-01-02, the Architect implemented Phase 4 of Spec 0063 by adding LLM calls to existing code structure. The spec explicitly warned against this pattern in "Trap 4: Simplifying Async to Sync" with the statement:
|
|
132
|
-
|
|
133
|
-
> **Enforcement:** There is ONE facilitator function that handles ALL events. If you find yourself creating a "synthesis" function, STOP.
|
|
73
|
+
The builder starts in an isolated worktree and runs `porch run` automatically.
|
|
134
74
|
|
|
135
|
-
|
|
75
|
+
### 2. Approving Gates
|
|
136
76
|
|
|
137
|
-
|
|
77
|
+
The builder stops at gates requiring approval:
|
|
138
78
|
|
|
139
|
-
**
|
|
140
|
-
|
|
141
|
-
### Recognizing and Breaking "Fixing Mode"
|
|
142
|
-
|
|
143
|
-
A dangerous pattern: The agent starts looking at symptoms in code, making incremental fixes, copying existing patterns - without going back to the source of truth (spec). Signs include:
|
|
144
|
-
- Making multiple small fixes that don't resolve the issue
|
|
145
|
-
- Copying patterns from existing code without verifying they match the spec
|
|
146
|
-
- Building on top of code that may already be wrong
|
|
147
|
-
- Focusing on "what the code does" instead of "what the spec says it should do"
|
|
148
|
-
|
|
149
|
-
**Intervention phrases that work** (use these when you see the pattern):
|
|
150
|
-
1. **"What does the spec say about X?"** - Forces spec lookup
|
|
151
|
-
2. **"Check the spec's Traps to Avoid section"** - Targets specific guidance
|
|
152
|
-
3. **"Does this match the spec?"** - Creates verification checkpoint
|
|
153
|
-
4. **"ARE YOU SURE?"** - Triggers doubt and re-verification
|
|
154
|
-
5. **"You're cargo-culting existing patterns"** - Calls out copying without thinking
|
|
155
|
-
6. **"We've been through this cycle"** - Highlights the pattern of undoing/redoing
|
|
156
|
-
|
|
157
|
-
When reviewing builder work or your own work, actively look for signs of "fixing mode" and intervene early with these phrases.
|
|
158
|
-
|
|
159
|
-
## Project Tracking
|
|
160
|
-
|
|
161
|
-
**`codev/projectlist.md` is the canonical source of truth for all projects.**
|
|
162
|
-
|
|
163
|
-
The Architect is responsible for maintaining this file:
|
|
164
|
-
|
|
165
|
-
1. **Reserve numbers first** - Add entry to projectlist.md BEFORE creating spec files
|
|
166
|
-
2. **Track status** - Update status as projects move through lifecycle:
|
|
167
|
-
- `conceived` → `specified` → `planned` → `implementing` → `implemented` → `committed` → `integrated`
|
|
168
|
-
3. **Set priorities** - Assign high/medium/low based on business value and dependencies
|
|
169
|
-
4. **Note dependencies** - Track which projects depend on others
|
|
170
|
-
5. **Document decisions** - Use notes field for context, blockers, or reasons for abandonment
|
|
171
|
-
|
|
172
|
-
When asked "what should we work on next?" or "what's incomplete?":
|
|
79
|
+
**spec-approval** - After builder writes the spec
|
|
173
80
|
```bash
|
|
174
|
-
#
|
|
175
|
-
cat codev/
|
|
81
|
+
# Review the spec in the builder's worktree
|
|
82
|
+
cat worktrees/spider_0042_user-authentication/codev/specs/0042-user-authentication.md
|
|
176
83
|
|
|
177
|
-
#
|
|
178
|
-
|
|
84
|
+
# Approve if satisfactory
|
|
85
|
+
porch approve 0042 spec-approval
|
|
179
86
|
```
|
|
180
87
|
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
### Release Lifecycle
|
|
88
|
+
**plan-approval** - After builder writes the plan
|
|
89
|
+
```bash
|
|
90
|
+
# Review the plan
|
|
91
|
+
cat worktrees/spider_0042_user-authentication/codev/plans/0042-user-authentication.md
|
|
186
92
|
|
|
93
|
+
# Approve if satisfactory
|
|
94
|
+
porch approve 0042 plan-approval
|
|
187
95
|
```
|
|
188
|
-
planning → active → released → archived
|
|
189
|
-
```
|
|
190
|
-
|
|
191
|
-
- **planning**: Defining scope, assigning projects to the release
|
|
192
|
-
- **active**: The current development focus (only one release should be active)
|
|
193
|
-
- **released**: All projects integrated and deployed
|
|
194
|
-
- **archived**: Historical, no longer maintained
|
|
195
|
-
|
|
196
|
-
### Release Responsibilities
|
|
197
|
-
|
|
198
|
-
1. **Create releases** - Define new releases with semantic versions (v1.0.0, v1.1.0, v2.0.0)
|
|
199
|
-
2. **Assign projects** - Set each project's `release` field when scope is determined
|
|
200
|
-
3. **Track progress** - Monitor which projects are complete within a release
|
|
201
|
-
4. **Transition status** - Move releases through the lifecycle as work progresses
|
|
202
|
-
5. **Document releases** - Add release notes summarizing the release goals
|
|
203
|
-
|
|
204
|
-
### Release Guidelines
|
|
205
|
-
|
|
206
|
-
- Only **one release** should be `active` at a time
|
|
207
|
-
- Projects should be assigned to a release before reaching `implementing` status
|
|
208
|
-
- All projects in a release must be `integrated` before the release can be marked `released`
|
|
209
|
-
- **Unassigned integrated projects** - Some work (ad-hoc fixes, documentation, minor improvements) may not belong to any release. These go in the "Integrated (Unassigned)" section with `release: null`
|
|
210
|
-
- Use semantic versioning:
|
|
211
|
-
- **Major** (v2.0.0): Breaking changes or major new capabilities
|
|
212
|
-
- **Minor** (v1.1.0): New features, backward compatible
|
|
213
|
-
- **Patch** (v1.0.1): Bug fixes only
|
|
214
|
-
|
|
215
|
-
## Development Protocols
|
|
216
|
-
|
|
217
|
-
The Architect uses SPIDER or TICK protocols. **The Builder executes the full SPIDER protocol** (Specify → Plan → Implement → Defend → Evaluate → Review). The Architect's role is to spawn builders, approve gates, and integrate their work.
|
|
218
|
-
|
|
219
|
-
### Spawning a Builder
|
|
220
96
|
|
|
221
|
-
|
|
97
|
+
### 3. Monitoring Progress
|
|
222
98
|
|
|
223
99
|
```bash
|
|
224
|
-
af
|
|
100
|
+
af status # Overview of all builders
|
|
101
|
+
porch status 0042 # Detailed state for one project
|
|
225
102
|
```
|
|
226
103
|
|
|
227
|
-
|
|
228
|
-
1. **Specify** - Write the spec, run 3-way consultation, then hit `spec-approval` gate
|
|
229
|
-
2. **Plan** - Write the plan, run 3-way consultation, then hit `plan-approval` gate
|
|
230
|
-
3. **Implement/Defend/Evaluate** - Complete I→D→E cycles for each plan phase
|
|
231
|
-
4. **Review** - Create review document and PR
|
|
104
|
+
### 4. Integration Review
|
|
232
105
|
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
The builder stops at two gates that require human approval:
|
|
236
|
-
|
|
237
|
-
1. **spec-approval** - After the builder writes the spec
|
|
238
|
-
- Review the spec at `codev/specs/XXXX-name.md`
|
|
239
|
-
- Verify it captures requirements correctly
|
|
240
|
-
- Approve: `porch approve XXXX spec-approval --a-human-explicitly-approved-this`
|
|
241
|
-
|
|
242
|
-
2. **plan-approval** - After the builder writes the plan
|
|
243
|
-
- Review the plan at `codev/plans/XXXX-name.md`
|
|
244
|
-
- Verify phases are logical and complete
|
|
245
|
-
- Approve: `porch approve XXXX plan-approval --a-human-explicitly-approved-this`
|
|
246
|
-
|
|
247
|
-
**Important:** Update the project status in `codev/projectlist.md` as gates are approved.
|
|
248
|
-
|
|
249
|
-
### Monitoring Progress
|
|
106
|
+
When the builder creates a PR:
|
|
250
107
|
|
|
251
108
|
```bash
|
|
252
|
-
#
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
```
|
|
258
|
-
|
|
259
|
-
The Architect monitors progress and provides guidance when builders are blocked.
|
|
260
|
-
|
|
261
|
-
## Spikes: De-risking Technical Unknowns
|
|
262
|
-
|
|
263
|
-
When facing high-risk technical unknowns, use **spikes** - short, time-boxed experiments (1-2 hours max) that validate assumptions before full implementation.
|
|
109
|
+
# Run 3-way integration review
|
|
110
|
+
consult --model gemini --type integration-review pr 83 &
|
|
111
|
+
consult --model codex --type integration-review pr 83 &
|
|
112
|
+
consult --model claude --type integration-review pr 83 &
|
|
113
|
+
wait
|
|
264
114
|
|
|
265
|
-
|
|
115
|
+
# Post findings as PR comment
|
|
116
|
+
gh pr comment 83 --body "## Architect Integration Review
|
|
266
117
|
|
|
267
|
-
**
|
|
268
|
-
- Store in `codev/spikes/{spec-number}/`
|
|
269
|
-
- Typically 1-2 hours; check in if taking longer
|
|
270
|
-
- Output: PASS/FAIL + learnings (code is throwaway)
|
|
271
|
-
- Use when: Untested APIs, architectural uncertainty, integration questions
|
|
118
|
+
**Verdict: APPROVE**
|
|
272
119
|
|
|
273
|
-
|
|
120
|
+
Integration looks good. No conflicts with existing modules.
|
|
274
121
|
|
|
275
|
-
|
|
122
|
+
---
|
|
123
|
+
Architect integration review"
|
|
276
124
|
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
- Any relevant architecture context
|
|
281
|
-
- Constraints or patterns to follow
|
|
282
|
-
- Which protocol to use (SPIDER/TICK)
|
|
125
|
+
# Notify builder
|
|
126
|
+
af send 0042 "PR approved, please merge"
|
|
127
|
+
```
|
|
283
128
|
|
|
284
|
-
|
|
129
|
+
### 5. Cleanup
|
|
285
130
|
|
|
286
|
-
|
|
131
|
+
After builder merges and work is integrated:
|
|
287
132
|
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
3. The builder will continue once unblocked
|
|
133
|
+
```bash
|
|
134
|
+
af cleanup -p 0042
|
|
135
|
+
```
|
|
292
136
|
|
|
293
|
-
|
|
137
|
+
## Critical Rules
|
|
294
138
|
|
|
295
|
-
|
|
139
|
+
### NEVER Do These:
|
|
140
|
+
1. **DO NOT write specs or plans** - The builder does this via porch
|
|
141
|
+
2. **DO NOT merge PRs yourself** - Let builders merge their own PRs
|
|
142
|
+
3. **DO NOT commit directly to main** - All changes go through builder PRs
|
|
143
|
+
4. **DO NOT use `af send` for long messages** - Use GitHub PR comments instead
|
|
296
144
|
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
145
|
+
### ALWAYS Do These:
|
|
146
|
+
1. **Reserve project numbers first** - Update projectlist.md before kickoff
|
|
147
|
+
2. **Review artifacts before approving gates** - Read the spec/plan carefully
|
|
148
|
+
3. **Use PR comments for feedback** - Not tmux send-keys
|
|
149
|
+
4. **Let builders own their work** - Guide, don't take over
|
|
301
150
|
|
|
302
|
-
|
|
303
|
-
1. Check PR description for builder's 3-way review summary
|
|
304
|
-
2. Confirm any REQUEST_CHANGES from their review were addressed
|
|
305
|
-
3. All SPIDER artifacts are present (especially the review document)
|
|
151
|
+
## Project Tracking
|
|
306
152
|
|
|
307
|
-
|
|
153
|
+
**`codev/projectlist.md` is the canonical source of truth.**
|
|
308
154
|
|
|
309
155
|
```bash
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
Focus on:
|
|
313
|
-
- How changes integrate with existing codebase
|
|
314
|
-
- Impact on other modules/features
|
|
315
|
-
- Architectural consistency
|
|
316
|
-
- Potential side effects or regressions
|
|
317
|
-
- API contract changes
|
|
318
|
-
|
|
319
|
-
Give verdict: APPROVE or REQUEST_CHANGES with specific integration feedback."
|
|
156
|
+
# See what needs work
|
|
157
|
+
cat codev/projectlist.md
|
|
320
158
|
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
consult --model claude --type integration-review pr 35 &
|
|
324
|
-
wait
|
|
159
|
+
# Find high-priority items
|
|
160
|
+
grep -A5 "priority: high" codev/projectlist.md
|
|
325
161
|
```
|
|
326
162
|
|
|
327
|
-
|
|
163
|
+
Update status as projects progress:
|
|
164
|
+
- `conceived` → `specified` → `planned` → `implementing` → `committed` → `integrated`
|
|
328
165
|
|
|
329
|
-
|
|
330
|
-
# Post integration review findings as PR comment
|
|
331
|
-
gh pr comment 35 --body "## Architect Integration Review (3-Way)
|
|
166
|
+
## Handling Blocked Builders
|
|
332
167
|
|
|
333
|
-
|
|
168
|
+
When a builder reports blocked:
|
|
334
169
|
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
170
|
+
1. Check their status: `porch status <id>`
|
|
171
|
+
2. Read their output in the terminal: `http://localhost:<port>`
|
|
172
|
+
3. Provide guidance via short `af send` message
|
|
173
|
+
4. Or answer their question directly if they asked one
|
|
338
174
|
|
|
339
|
-
|
|
340
|
-
|
|
175
|
+
## Release Management
|
|
176
|
+
|
|
177
|
+
The Architect manages releases - deployable units grouping related projects.
|
|
341
178
|
|
|
342
|
-
|
|
343
|
-
|
|
179
|
+
```
|
|
180
|
+
planning → active → released → archived
|
|
344
181
|
```
|
|
345
182
|
|
|
346
|
-
**
|
|
183
|
+
- Only **one release** should be `active` at a time
|
|
184
|
+
- Projects should be assigned to a release before `implementing`
|
|
185
|
+
- All projects must be `integrated` before release is marked `released`
|
|
347
186
|
|
|
348
|
-
|
|
187
|
+
## UX Verification (Critical)
|
|
349
188
|
|
|
350
|
-
|
|
189
|
+
Before approving implementations with UX requirements:
|
|
351
190
|
|
|
352
|
-
1. **Read the spec's
|
|
191
|
+
1. **Read the spec's Goals section**
|
|
353
192
|
2. **Manually test** the actual user experience
|
|
354
|
-
3.
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
**Why this matters:** Code reviews catch syntax and logic errors, but miss UX gaps. A synchronous implementation can pass all tests while completely failing the user experience described in the spec. The only way to catch this is to actually USE the feature as a user would.
|
|
376
|
-
|
|
377
|
-
### Testing Requirements
|
|
378
|
-
|
|
379
|
-
Specs should explicitly require:
|
|
380
|
-
1. **Unit tests** - Core functionality
|
|
381
|
-
2. **Integration tests** - Full workflow
|
|
382
|
-
3. **Error handling tests** - Edge cases and failure modes
|
|
383
|
-
4. **UX tests** - For specs with UX requirements, verify timing and interaction patterns
|
|
193
|
+
3. Verify each UX requirement is met
|
|
194
|
+
|
|
195
|
+
**Auto-reject if:**
|
|
196
|
+
- Spec says "async" but implementation is synchronous
|
|
197
|
+
- Spec says "immediate" but user waits 30+ seconds
|
|
198
|
+
- Spec has flow diagram that doesn't match reality
|
|
199
|
+
|
|
200
|
+
## Quick Reference
|
|
201
|
+
|
|
202
|
+
| Task | Command |
|
|
203
|
+
|------|---------|
|
|
204
|
+
| Start new feature | `af kickoff -p <id> --title "name"` |
|
|
205
|
+
| Check all builders | `af status` |
|
|
206
|
+
| Check one project | `porch status <id>` |
|
|
207
|
+
| Approve spec | `porch approve <id> spec-approval` |
|
|
208
|
+
| Approve plan | `porch approve <id> plan-approval` |
|
|
209
|
+
| See pending gates | `porch pending` |
|
|
210
|
+
| Integration review | `consult --model X --type integration-review pr N` |
|
|
211
|
+
| Message builder | `af send <id> "short message"` |
|
|
212
|
+
| Cleanup builder | `af cleanup -p <id>` |
|