@cluesmith/codev 2.0.0-rc.56 → 2.0.0-rc.58
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/dashboard/dist/assets/index-BEs2fHhy.js +131 -0
- package/dashboard/dist/assets/index-BEs2fHhy.js.map +1 -0
- package/dashboard/dist/index.html +1 -1
- package/dist/agent-farm/commands/attach.d.ts.map +1 -1
- package/dist/agent-farm/commands/attach.js +31 -8
- package/dist/agent-farm/commands/attach.js.map +1 -1
- package/dist/agent-farm/commands/send.d.ts.map +1 -1
- package/dist/agent-farm/commands/send.js +55 -17
- package/dist/agent-farm/commands/send.js.map +1 -1
- package/dist/agent-farm/commands/spawn.d.ts.map +1 -1
- package/dist/agent-farm/commands/spawn.js +37 -27
- package/dist/agent-farm/commands/spawn.js.map +1 -1
- package/dist/agent-farm/commands/start.d.ts.map +1 -1
- package/dist/agent-farm/commands/start.js +3 -226
- package/dist/agent-farm/commands/start.js.map +1 -1
- package/dist/agent-farm/commands/status.d.ts.map +1 -1
- package/dist/agent-farm/commands/status.js +5 -2
- package/dist/agent-farm/commands/status.js.map +1 -1
- package/dist/agent-farm/db/index.d.ts.map +1 -1
- package/dist/agent-farm/db/index.js +45 -0
- package/dist/agent-farm/db/index.js.map +1 -1
- package/dist/agent-farm/db/schema.d.ts +1 -1
- package/dist/agent-farm/db/schema.d.ts.map +1 -1
- package/dist/agent-farm/db/schema.js +2 -2
- package/dist/agent-farm/hq-connector.d.ts +0 -4
- package/dist/agent-farm/hq-connector.d.ts.map +1 -1
- package/dist/agent-farm/hq-connector.js +0 -15
- package/dist/agent-farm/hq-connector.js.map +1 -1
- package/dist/agent-farm/servers/tower-server.js +228 -13
- package/dist/agent-farm/servers/tower-server.js.map +1 -1
- package/dist/commands/porch/protocol.d.ts.map +1 -1
- package/dist/commands/porch/protocol.js +26 -1
- package/dist/commands/porch/protocol.js.map +1 -1
- package/package.json +4 -6
- package/skeleton/porch/prompts/defend.md +1 -1
- package/skeleton/porch/prompts/evaluate.md +2 -2
- package/skeleton/porch/prompts/implement.md +1 -1
- package/skeleton/porch/prompts/plan.md +1 -1
- package/skeleton/porch/prompts/review.md +4 -4
- package/skeleton/porch/prompts/specify.md +1 -1
- package/skeleton/porch/prompts/understand.md +2 -2
- package/skeleton/protocol-schema.json +3 -3
- package/skeleton/protocols/bugfix/builder-prompt.md +1 -1
- package/skeleton/protocols/bugfix/prompts/pr.md +2 -17
- package/skeleton/protocols/experiment/protocol.md +3 -3
- package/skeleton/protocols/experiment/templates/notes.md +1 -1
- package/skeleton/protocols/maintain/protocol.md +1 -1
- package/skeleton/protocols/protocol-schema.json +1 -1
- package/skeleton/protocols/{spider → spir}/builder-prompt.md +1 -1
- package/skeleton/protocols/{spider → spir}/prompts/implement.md +1 -1
- package/skeleton/protocols/{spider → spir}/prompts/plan.md +6 -70
- package/skeleton/protocols/{spider → spir}/prompts/review.md +7 -25
- package/skeleton/protocols/{spider → spir}/prompts/specify.md +5 -58
- package/skeleton/protocols/{spider → spir}/protocol.json +2 -2
- package/skeleton/protocols/{spider → spir}/protocol.md +6 -8
- package/skeleton/protocols/{spider → spir}/templates/review.md +1 -1
- package/skeleton/protocols/tick/builder-prompt.md +1 -1
- package/skeleton/protocols/tick/protocol.md +18 -18
- package/skeleton/protocols/tick/templates/review.md +1 -1
- package/skeleton/resources/commands/overview.md +1 -1
- package/skeleton/resources/workflow-reference.md +2 -2
- package/skeleton/roles/architect.md +2 -2
- package/skeleton/roles/builder.md +2 -2
- package/skeleton/templates/AGENTS.md +1 -1
- package/skeleton/templates/CLAUDE.md +1 -1
- package/skeleton/templates/cheatsheet.md +3 -3
- package/skeleton/templates/projectlist.md +1 -1
- package/templates/dashboard/js/main.js +1 -1
- package/templates/open.html +26 -0
- package/dashboard/dist/assets/index-xOaDIZ0l.js +0 -132
- package/dashboard/dist/assets/index-xOaDIZ0l.js.map +0 -1
- /package/skeleton/protocols/{spider → spir}/templates/plan.md +0 -0
- /package/skeleton/protocols/{spider → spir}/templates/spec.md +0 -0
|
@@ -30,7 +30,7 @@ TICK is appropriate when:
|
|
|
30
30
|
- [ ] Requirements are clear
|
|
31
31
|
- [ ] No architectural changes needed
|
|
32
32
|
|
|
33
|
-
If NOT appropriate, signal: `<signal>
|
|
33
|
+
If NOT appropriate, signal: `<signal>NEEDS_SPIR</signal>`
|
|
34
34
|
|
|
35
35
|
### 3. Document Understanding
|
|
36
36
|
|
|
@@ -58,4 +58,4 @@ When understanding is complete:
|
|
|
58
58
|
|
|
59
59
|
- DO NOT start implementing
|
|
60
60
|
- DO NOT create new spec files (amend existing)
|
|
61
|
-
- Keep scope small - if > 300 LOC, recommend
|
|
61
|
+
- Keep scope small - if > 300 LOC, recommend SPIR instead
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
3
|
"$id": "https://codev.dev/protocol-schema.json",
|
|
4
4
|
"title": "Codev Protocol Definition",
|
|
5
|
-
"description": "Schema for porch protocol definitions (
|
|
5
|
+
"description": "Schema for porch protocol definitions (SPIR, TICK, BUGFIX, etc.)",
|
|
6
6
|
"type": "object",
|
|
7
7
|
"required": ["name", "phases"],
|
|
8
8
|
"properties": {
|
|
@@ -12,12 +12,12 @@
|
|
|
12
12
|
},
|
|
13
13
|
"name": {
|
|
14
14
|
"type": "string",
|
|
15
|
-
"description": "Protocol name (e.g., '
|
|
15
|
+
"description": "Protocol name (e.g., 'spir', 'tick', 'bugfix')",
|
|
16
16
|
"pattern": "^[a-z][a-z0-9-]*$"
|
|
17
17
|
},
|
|
18
18
|
"alias": {
|
|
19
19
|
"type": "string",
|
|
20
|
-
"description": "Alternative name for the protocol (e.g., '
|
|
20
|
+
"description": "Alternative name for the protocol (e.g., 'spider' for spir)"
|
|
21
21
|
},
|
|
22
22
|
"version": {
|
|
23
23
|
"type": "string",
|
|
@@ -39,7 +39,7 @@ Follow the BUGFIX protocol: `codev/protocols/bugfix/protocol.md`
|
|
|
39
39
|
|
|
40
40
|
If the fix is too complex (> 300 LOC or architectural changes), notify the Architect via:
|
|
41
41
|
```bash
|
|
42
|
-
af send architect "Issue #{{issue.number}} is more complex than expected. [Reason]. Recommend escalating to
|
|
42
|
+
af send architect "Issue #{{issue.number}} is more complex than expected. [Reason]. Recommend escalating to SPIR/TICK."
|
|
43
43
|
```
|
|
44
44
|
{{/if}}
|
|
45
45
|
|
|
@@ -42,24 +42,9 @@ EOF
|
|
|
42
42
|
)"
|
|
43
43
|
```
|
|
44
44
|
|
|
45
|
-
### 2.
|
|
45
|
+
### 2. Signal Completion
|
|
46
46
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
```bash
|
|
50
|
-
consult --model gemini pr <PR_NUMBER> &
|
|
51
|
-
consult --model codex pr <PR_NUMBER> &
|
|
52
|
-
consult --model claude pr <PR_NUMBER> &
|
|
53
|
-
```
|
|
54
|
-
|
|
55
|
-
All three should run in the background (`run_in_background: true`).
|
|
56
|
-
|
|
57
|
-
### 3. Address Feedback
|
|
58
|
-
|
|
59
|
-
Review the consultation results:
|
|
60
|
-
- Fix any issues identified by reviewers
|
|
61
|
-
- Push updates to the PR branch
|
|
62
|
-
- Re-run CMAP if substantial changes were made
|
|
47
|
+
After the PR is created, signal completion. Porch will run consultation automatically via the verify step. If reviewers request changes, you'll be respawned with their feedback.
|
|
63
48
|
|
|
64
49
|
## Signals
|
|
65
50
|
|
|
@@ -10,7 +10,7 @@ Disciplined experimentation: Each experiment gets its own directory with `notes.
|
|
|
10
10
|
|
|
11
11
|
**Use for**: Testing approaches, evaluating models, prototyping, proof-of-concept work, research spikes
|
|
12
12
|
|
|
13
|
-
**Skip for**: Production code (use
|
|
13
|
+
**Skip for**: Production code (use SPIR), simple one-off scripts, well-understood implementations (use TICK)
|
|
14
14
|
|
|
15
15
|
## Structure
|
|
16
16
|
|
|
@@ -141,7 +141,7 @@ What should be done based on findings?
|
|
|
141
141
|
|
|
142
142
|
## Integration with Other Protocols
|
|
143
143
|
|
|
144
|
-
### Experiment →
|
|
144
|
+
### Experiment → SPIR
|
|
145
145
|
When an experiment validates an approach for production use:
|
|
146
146
|
|
|
147
147
|
1. Create a specification referencing the experiment
|
|
@@ -225,5 +225,5 @@ Determine if Redis caching improves API response times for repeated queries.
|
|
|
225
225
|
- Memory usage: 50MB for 10k cached responses
|
|
226
226
|
|
|
227
227
|
## Next Steps
|
|
228
|
-
Create
|
|
228
|
+
Create SPIR spec for production caching implementation.
|
|
229
229
|
```
|
|
@@ -88,7 +88,7 @@ Based on these findings:
|
|
|
88
88
|
|
|
89
89
|
1. **Immediate**: What should happen right after this experiment?
|
|
90
90
|
2. **Follow-up experiments**: What new questions emerged?
|
|
91
|
-
3. **Production path**: If validated, what's needed for production? (
|
|
91
|
+
3. **Production path**: If validated, what's needed for production? (SPIR spec?)
|
|
92
92
|
|
|
93
93
|
## References
|
|
94
94
|
|
|
@@ -479,7 +479,7 @@ MAINTAIN is an **operational protocol**, not a feature development protocol:
|
|
|
479
479
|
| Review | No |
|
|
480
480
|
| 3-Way Consultation | **Yes** (before creating PR) |
|
|
481
481
|
|
|
482
|
-
**Exception**: If MAINTAIN reveals need for architectural changes, those should follow
|
|
482
|
+
**Exception**: If MAINTAIN reveals need for architectural changes, those should follow SPIR.
|
|
483
483
|
|
|
484
484
|
---
|
|
485
485
|
|
|
@@ -21,7 +21,7 @@ You are running in STRICT mode. This means:
|
|
|
21
21
|
{{/if}}
|
|
22
22
|
|
|
23
23
|
## Protocol
|
|
24
|
-
Follow the
|
|
24
|
+
Follow the SPIR protocol: `codev/protocols/spir/protocol.md`
|
|
25
25
|
Read and internalize the protocol before starting any work.
|
|
26
26
|
|
|
27
27
|
{{#if spec}}
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# PLAN Phase Prompt
|
|
2
2
|
|
|
3
|
-
You are executing the **PLAN** phase of the
|
|
3
|
+
You are executing the **PLAN** phase of the SPIR protocol.
|
|
4
4
|
|
|
5
5
|
## Your Goal
|
|
6
6
|
|
|
@@ -14,10 +14,6 @@ Transform the approved specification into an executable implementation plan with
|
|
|
14
14
|
- **Spec File**: `codev/specs/{{project_id}}-{{title}}.md`
|
|
15
15
|
- **Plan File**: `codev/plans/{{project_id}}-{{title}}.md`
|
|
16
16
|
|
|
17
|
-
## CRITICAL: Multi-Agent Consultation is MANDATORY
|
|
18
|
-
|
|
19
|
-
The SPIDER protocol **requires** consultation with GPT-5 Codex AND Gemini Pro at specific checkpoints. This is BLOCKING - you cannot proceed without completing consultations.
|
|
20
|
-
|
|
21
17
|
## Prerequisites
|
|
22
18
|
|
|
23
19
|
Before planning, verify:
|
|
@@ -72,51 +68,15 @@ Phase 3: API Endpoints (depends on Phase 2)
|
|
|
72
68
|
Phase 4: Frontend Integration (depends on Phase 3)
|
|
73
69
|
```
|
|
74
70
|
|
|
75
|
-
### 5.
|
|
76
|
-
|
|
77
|
-
After completing the initial plan draft:
|
|
78
|
-
|
|
79
|
-
```bash
|
|
80
|
-
# Run consultations in parallel (REQUIRED)
|
|
81
|
-
consult --model gemini plan {{project_id}} &
|
|
82
|
-
consult --model codex plan {{project_id}} &
|
|
83
|
-
wait
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
- Review ALL feedback from both models
|
|
87
|
-
- Update the plan with incorporated feedback
|
|
88
|
-
- Add a **Consultation Log** section documenting:
|
|
89
|
-
- Key feedback received
|
|
90
|
-
- Changes made in response
|
|
91
|
-
- Any feedback intentionally not incorporated (with reasoning)
|
|
92
|
-
|
|
93
|
-
### 6. Human Review
|
|
94
|
-
|
|
95
|
-
After consultation feedback is incorporated:
|
|
96
|
-
- Present the plan for human review
|
|
97
|
-
- Wait for approval or change requests
|
|
98
|
-
- If changes requested, make them and proceed to Step 7
|
|
99
|
-
|
|
100
|
-
### 7. MANDATORY: Second Consultation (After Human Feedback)
|
|
101
|
-
|
|
102
|
-
After incorporating human feedback:
|
|
71
|
+
### 5. Finalize
|
|
103
72
|
|
|
104
|
-
|
|
105
|
-
# Run consultations again (REQUIRED)
|
|
106
|
-
consult --model gemini plan {{project_id}} &
|
|
107
|
-
consult --model codex plan {{project_id}} &
|
|
108
|
-
wait
|
|
109
|
-
```
|
|
110
|
-
|
|
111
|
-
- Update Consultation Log with new feedback
|
|
112
|
-
- Incorporate changes
|
|
113
|
-
- Prepare final plan for approval
|
|
73
|
+
After completing the plan draft, signal completion. Porch will run 3-way consultation (Gemini, Codex, Claude) automatically via the verify step. If reviewers request changes, you'll be respawned with their feedback.
|
|
114
74
|
|
|
115
75
|
## Output
|
|
116
76
|
|
|
117
77
|
Create the plan file at `codev/plans/{{project_id}}-{{title}}.md`.
|
|
118
78
|
|
|
119
|
-
Use the plan template from `codev/protocols/
|
|
79
|
+
Use the plan template from `codev/protocols/spir/templates/plan.md` if available.
|
|
120
80
|
|
|
121
81
|
### Plan Structure
|
|
122
82
|
|
|
@@ -148,18 +108,6 @@ Brief summary of what will be implemented.
|
|
|
148
108
|
- [Risk 1]: [Mitigation]
|
|
149
109
|
- [Risk 2]: [Mitigation]
|
|
150
110
|
|
|
151
|
-
## Consultation Log
|
|
152
|
-
|
|
153
|
-
### First Consultation (After Draft)
|
|
154
|
-
- **Gemini Feedback**: [Summary]
|
|
155
|
-
- **Codex Feedback**: [Summary]
|
|
156
|
-
- **Changes Made**: [List]
|
|
157
|
-
- **Not Incorporated**: [List with reasons]
|
|
158
|
-
|
|
159
|
-
### Second Consultation (After Human Feedback)
|
|
160
|
-
- **Gemini Feedback**: [Summary]
|
|
161
|
-
- **Codex Feedback**: [Summary]
|
|
162
|
-
- **Changes Made**: [List]
|
|
163
111
|
```
|
|
164
112
|
|
|
165
113
|
## Signals
|
|
@@ -171,16 +119,6 @@ Emit appropriate signals based on your progress:
|
|
|
171
119
|
<signal>PLAN_DRAFTED</signal>
|
|
172
120
|
```
|
|
173
121
|
|
|
174
|
-
- After incorporating consultation feedback:
|
|
175
|
-
```
|
|
176
|
-
<signal>CONSULTATION_INCORPORATED</signal>
|
|
177
|
-
```
|
|
178
|
-
|
|
179
|
-
- After final plan is ready for human approval:
|
|
180
|
-
```
|
|
181
|
-
<signal>PLAN_READY_FOR_APPROVAL</signal>
|
|
182
|
-
```
|
|
183
|
-
|
|
184
122
|
## Commit Cadence
|
|
185
123
|
|
|
186
124
|
Make commits at these milestones:
|
|
@@ -196,16 +134,14 @@ git add codev/plans/{{project_id}}-{{title}}.md
|
|
|
196
134
|
|
|
197
135
|
## Important Notes
|
|
198
136
|
|
|
199
|
-
1. **
|
|
200
|
-
2. **No time estimates** - Don't include hours/days/weeks
|
|
137
|
+
1. **No time estimates** - Don't include hours/days/weeks
|
|
201
138
|
3. **Be specific about files** - Exact paths, not "the config file"
|
|
202
139
|
4. **Keep phases small** - 1-3 files per phase is ideal
|
|
203
140
|
5. **Document dependencies clearly** - Prevents blocked work
|
|
204
|
-
6. **Document consultations** - Maintain the Consultation Log section
|
|
205
141
|
|
|
206
142
|
## What NOT to Do
|
|
207
143
|
|
|
208
|
-
- Don't
|
|
144
|
+
- Don't run `consult` commands yourself (porch handles consultations)
|
|
209
145
|
- Don't write code (that's for Implement phase)
|
|
210
146
|
- Don't estimate time (meaningless in AI development)
|
|
211
147
|
- Don't create phases that can't be independently tested
|
|
@@ -1,14 +1,10 @@
|
|
|
1
1
|
# REVIEW Phase Prompt
|
|
2
2
|
|
|
3
|
-
You are executing the **REVIEW** phase of the
|
|
3
|
+
You are executing the **REVIEW** phase of the SPIR protocol.
|
|
4
4
|
|
|
5
5
|
## Your Goal
|
|
6
6
|
|
|
7
|
-
Perform a comprehensive review, document lessons learned,
|
|
8
|
-
|
|
9
|
-
## CRITICAL: Final Consultation Before PR
|
|
10
|
-
|
|
11
|
-
The SPIDER protocol **requires** a final consultation with GPT-5 Codex AND Gemini Pro before submitting the PR. This ensures the complete implementation is reviewed.
|
|
7
|
+
Perform a comprehensive review, document lessons learned, and prepare for PR submission.
|
|
12
8
|
|
|
13
9
|
## Context
|
|
14
10
|
|
|
@@ -92,7 +88,7 @@ Brief description of what was implemented.
|
|
|
92
88
|
- [Insight 2]
|
|
93
89
|
|
|
94
90
|
### Methodology Improvements
|
|
95
|
-
- [Suggested improvement to
|
|
91
|
+
- [Suggested improvement to SPIR protocol]
|
|
96
92
|
- [Suggested improvement to tooling]
|
|
97
93
|
|
|
98
94
|
## Technical Debt
|
|
@@ -118,22 +114,9 @@ Before PR:
|
|
|
118
114
|
- [ ] No uncommitted changes: `git status`
|
|
119
115
|
- [ ] Review document complete
|
|
120
116
|
|
|
121
|
-
### 6.
|
|
122
|
-
|
|
123
|
-
**Before creating the PR, run final consultation:**
|
|
124
|
-
|
|
125
|
-
```bash
|
|
126
|
-
# Run consultations in parallel (REQUIRED)
|
|
127
|
-
consult --model gemini --type pr-ready spec {{project_id}} &
|
|
128
|
-
consult --model codex --type pr-ready spec {{project_id}} &
|
|
129
|
-
wait
|
|
130
|
-
```
|
|
131
|
-
|
|
132
|
-
- Review ALL feedback from both models
|
|
133
|
-
- Address any final issues identified
|
|
134
|
-
- This is the last chance to catch problems before PR
|
|
117
|
+
### 6. Create Pull Request
|
|
135
118
|
|
|
136
|
-
|
|
119
|
+
After the review document is complete, signal completion. Porch will run 3-way consultation (Gemini, Codex, Claude) automatically via the verify step. If reviewers request changes, you'll be respawned with their feedback.
|
|
137
120
|
|
|
138
121
|
Prepare PR with:
|
|
139
122
|
|
|
@@ -187,8 +170,7 @@ Emit appropriate signals based on your progress:
|
|
|
187
170
|
|
|
188
171
|
## Important Notes
|
|
189
172
|
|
|
190
|
-
1. **
|
|
191
|
-
2. **Be honest in lessons learned** - Future you will thank present you
|
|
173
|
+
1. **Be honest in lessons learned** - Future you will thank present you
|
|
192
174
|
3. **Document deviations** - They're not failures, they're learnings
|
|
193
175
|
4. **Update methodology** - If you found a better way, document it
|
|
194
176
|
5. **Don't skip the checklist** - It catches last-minute issues
|
|
@@ -196,7 +178,7 @@ Emit appropriate signals based on your progress:
|
|
|
196
178
|
|
|
197
179
|
## What NOT to Do
|
|
198
180
|
|
|
199
|
-
- Don't
|
|
181
|
+
- Don't run `consult` commands yourself (porch handles consultations)
|
|
200
182
|
- Don't skip lessons learned ("nothing to report")
|
|
201
183
|
- Don't merge your own PR (Architect handles integration)
|
|
202
184
|
- Don't leave uncommitted changes
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# SPECIFY Phase Prompt
|
|
2
2
|
|
|
3
|
-
You are executing the **SPECIFY** phase of the
|
|
3
|
+
You are executing the **SPECIFY** phase of the SPIR protocol.
|
|
4
4
|
|
|
5
5
|
## Your Goal
|
|
6
6
|
|
|
@@ -13,10 +13,6 @@ Create a comprehensive specification document that thoroughly explores the probl
|
|
|
13
13
|
- **Current State**: {{current_state}}
|
|
14
14
|
- **Spec File**: `codev/specs/{{project_id}}-{{title}}.md`
|
|
15
15
|
|
|
16
|
-
## CRITICAL: Multi-Agent Consultation is MANDATORY
|
|
17
|
-
|
|
18
|
-
The SPIDER protocol **requires** consultation with GPT-5 Codex AND Gemini Pro at specific checkpoints. This is BLOCKING - you cannot proceed without completing consultations.
|
|
19
|
-
|
|
20
16
|
## Process
|
|
21
17
|
|
|
22
18
|
### 0. Check for Existing Spec (ALWAYS DO THIS FIRST)
|
|
@@ -80,45 +76,9 @@ Define measurable acceptance criteria:
|
|
|
80
76
|
- Non-functional requirements (performance, security)
|
|
81
77
|
- Test scenarios
|
|
82
78
|
|
|
83
|
-
### 6.
|
|
84
|
-
|
|
85
|
-
After completing the initial spec draft:
|
|
86
|
-
|
|
87
|
-
```bash
|
|
88
|
-
# Run consultations in parallel (REQUIRED)
|
|
89
|
-
consult --model gemini spec {{project_id}} &
|
|
90
|
-
consult --model codex spec {{project_id}} &
|
|
91
|
-
wait
|
|
92
|
-
```
|
|
93
|
-
|
|
94
|
-
- Review ALL feedback from both models
|
|
95
|
-
- Update the spec with incorporated feedback
|
|
96
|
-
- Add a **Consultation Log** section documenting:
|
|
97
|
-
- Key feedback received
|
|
98
|
-
- Changes made in response
|
|
99
|
-
- Any feedback intentionally not incorporated (with reasoning)
|
|
100
|
-
|
|
101
|
-
### 7. Human Review
|
|
102
|
-
|
|
103
|
-
After consultation feedback is incorporated:
|
|
104
|
-
- Present the spec for human review
|
|
105
|
-
- Wait for approval or change requests
|
|
106
|
-
- If changes requested, make them and proceed to Step 8
|
|
107
|
-
|
|
108
|
-
### 8. MANDATORY: Second Consultation (After Human Feedback)
|
|
79
|
+
### 6. Finalize
|
|
109
80
|
|
|
110
|
-
After
|
|
111
|
-
|
|
112
|
-
```bash
|
|
113
|
-
# Run consultations again (REQUIRED)
|
|
114
|
-
consult --model gemini spec {{project_id}} &
|
|
115
|
-
consult --model codex spec {{project_id}} &
|
|
116
|
-
wait
|
|
117
|
-
```
|
|
118
|
-
|
|
119
|
-
- Update Consultation Log with new feedback
|
|
120
|
-
- Incorporate changes
|
|
121
|
-
- Prepare final spec for approval
|
|
81
|
+
After completing the spec draft, signal completion. Porch will run 3-way consultation (Gemini, Codex, Claude) automatically via the verify step. If reviewers request changes, you'll be respawned with their feedback.
|
|
122
82
|
|
|
123
83
|
## Output
|
|
124
84
|
|
|
@@ -129,8 +89,6 @@ Create or update the specification file at `codev/specs/{{project_id}}-{{title}}
|
|
|
129
89
|
- Plan: `codev/plans/{{project_id}}-{{title}}.md`
|
|
130
90
|
- Review: `codev/reviews/{{project_id}}-{{title}}.md`
|
|
131
91
|
|
|
132
|
-
Include a **Consultation Log** section in the spec documenting all consultation feedback.
|
|
133
|
-
|
|
134
92
|
## Signals
|
|
135
93
|
|
|
136
94
|
Emit appropriate signals based on your progress:
|
|
@@ -152,15 +110,6 @@ Emit appropriate signals based on your progress:
|
|
|
152
110
|
<signal>SPEC_DRAFTED</signal>
|
|
153
111
|
```
|
|
154
112
|
|
|
155
|
-
- After incorporating consultation feedback:
|
|
156
|
-
```
|
|
157
|
-
<signal>CONSULTATION_INCORPORATED</signal>
|
|
158
|
-
```
|
|
159
|
-
|
|
160
|
-
- After final spec is ready for human approval:
|
|
161
|
-
```
|
|
162
|
-
<signal>SPEC_READY_FOR_APPROVAL</signal>
|
|
163
|
-
```
|
|
164
113
|
|
|
165
114
|
## Commit Cadence
|
|
166
115
|
|
|
@@ -177,15 +126,13 @@ git add codev/specs/{{project_id}}-{{title}}.md
|
|
|
177
126
|
|
|
178
127
|
## Important Notes
|
|
179
128
|
|
|
180
|
-
1. **
|
|
181
|
-
2. **Be thorough** - A good spec prevents implementation problems
|
|
129
|
+
1. **Be thorough** - A good spec prevents implementation problems
|
|
182
130
|
3. **Be specific** - Vague specs lead to wrong implementations
|
|
183
131
|
4. **Include examples** - Concrete examples clarify intent
|
|
184
|
-
5. **Document consultations** - Maintain the Consultation Log section
|
|
185
132
|
|
|
186
133
|
## What NOT to Do
|
|
187
134
|
|
|
188
|
-
- Don't
|
|
135
|
+
- Don't run `consult` commands yourself (porch handles consultations)
|
|
189
136
|
- Don't include implementation details (that's for the Plan phase)
|
|
190
137
|
- Don't estimate time (AI makes time estimates meaningless)
|
|
191
138
|
- Don't start coding (you're in Specify, not Implement)
|
|
@@ -1,7 +1,5 @@
|
|
|
1
|
-
# SPIR Protocol
|
|
1
|
+
# SPIR Protocol
|
|
2
2
|
|
|
3
|
-
> **Also known as**: SPIDER (legacy name)
|
|
4
|
-
>
|
|
5
3
|
> **SPIR** = **S**pecify → **P**lan → **I**mplement → **R**eview
|
|
6
4
|
>
|
|
7
5
|
> Each phase has one build-verify cycle with 3-way consultation.
|
|
@@ -20,17 +18,17 @@
|
|
|
20
18
|
### Multi-Agent Consultation (ENABLED BY DEFAULT)
|
|
21
19
|
|
|
22
20
|
**DEFAULT BEHAVIOR:**
|
|
23
|
-
Multi-agent consultation is **ENABLED BY DEFAULT** when using
|
|
21
|
+
Multi-agent consultation is **ENABLED BY DEFAULT** when using SPIR protocol.
|
|
24
22
|
|
|
25
23
|
**DEFAULT AGENTS:**
|
|
26
24
|
- **GPT-5 Codex**: Primary reviewer for architecture, feasibility, and code quality
|
|
27
25
|
- **Gemini Pro**: Secondary reviewer for completeness, edge cases, and alternative approaches
|
|
28
26
|
|
|
29
27
|
**DISABLING CONSULTATION:**
|
|
30
|
-
To run
|
|
28
|
+
To run SPIR without consultation, say "without consultation" when starting work.
|
|
31
29
|
|
|
32
30
|
**CUSTOM AGENTS:**
|
|
33
|
-
The user can specify different agents by saying: "use
|
|
31
|
+
The user can specify different agents by saying: "use SPIR with consultation from [agent1] and [agent2]"
|
|
34
32
|
|
|
35
33
|
**CONSULTATION BEHAVIOR:**
|
|
36
34
|
- DEFAULT: MANDATORY consultation with GPT-5 and Gemini Pro at EVERY checkpoint
|
|
@@ -596,12 +594,12 @@ Implements bcrypt-based password hashing with configurable rounds
|
|
|
596
594
|
|
|
597
595
|
### Branch Naming
|
|
598
596
|
```
|
|
599
|
-
|
|
597
|
+
spir/####-<spec-name>/<phase-name>
|
|
600
598
|
```
|
|
601
599
|
|
|
602
600
|
Example:
|
|
603
601
|
```
|
|
604
|
-
|
|
602
|
+
spir/0001-user-authentication/database-schema
|
|
605
603
|
```
|
|
606
604
|
|
|
607
605
|
|
|
@@ -106,7 +106,7 @@
|
|
|
106
106
|
|
|
107
107
|
## Methodology Feedback
|
|
108
108
|
|
|
109
|
-
###
|
|
109
|
+
### SPIR Protocol Effectiveness
|
|
110
110
|
- **Specification Phase**: [Was it thorough enough? Too detailed?]
|
|
111
111
|
- **Planning Phase**: [Were estimates accurate? Phases well-sized?]
|
|
112
112
|
- **Implementation Loop**: [Did IDE cycle work well?]
|
|
@@ -22,7 +22,7 @@ You are running in STRICT mode. This means:
|
|
|
22
22
|
## Protocol
|
|
23
23
|
Follow the TICK protocol: `codev/protocols/tick/protocol.md`
|
|
24
24
|
|
|
25
|
-
TICK is for amendments to existing
|
|
25
|
+
TICK is for amendments to existing SPIR specifications. You will:
|
|
26
26
|
1. Identify the target spec to amend
|
|
27
27
|
2. Update the spec with the amendment
|
|
28
28
|
3. Update the plan
|
|
@@ -3,16 +3,16 @@
|
|
|
3
3
|
|
|
4
4
|
## Overview
|
|
5
5
|
|
|
6
|
-
TICK is an **amendment workflow** for existing
|
|
6
|
+
TICK is an **amendment workflow** for existing SPIR specifications. Rather than creating new standalone specs, TICK modifies existing spec and plan documents in-place, tracking changes in an "Amendments" section.
|
|
7
7
|
|
|
8
|
-
**Core Principle**: TICK is for *refining* existing specs.
|
|
8
|
+
**Core Principle**: TICK is for *refining* existing specs. SPIR is for *creating* new specs.
|
|
9
9
|
|
|
10
|
-
**Key Insight**: TICKs are not small
|
|
10
|
+
**Key Insight**: TICKs are not small SPIRs - they're amendments to existing SPIRs. This eliminates the "TICK vs SPIR" decision problem and keeps related work together.
|
|
11
11
|
|
|
12
12
|
## When to Use TICK
|
|
13
13
|
|
|
14
14
|
### Use TICK when:
|
|
15
|
-
- Making **amendments to an existing
|
|
15
|
+
- Making **amendments to an existing SPIR spec** that is already `integrated`
|
|
16
16
|
- Small scope (< 300 lines of new/changed code)
|
|
17
17
|
- Requirements are clear and well-defined
|
|
18
18
|
- No fundamental architecture changes
|
|
@@ -23,7 +23,7 @@ TICK is an **amendment workflow** for existing SPIDER specifications. Rather tha
|
|
|
23
23
|
- Utility function additions to existing modules
|
|
24
24
|
- Refactoring within an existing feature
|
|
25
25
|
|
|
26
|
-
### Use
|
|
26
|
+
### Use SPIR instead when:
|
|
27
27
|
- Creating a **new feature from scratch** (no existing spec to amend)
|
|
28
28
|
- Major architecture changes (scope too large for amendment)
|
|
29
29
|
- Unclear requirements needing exploration
|
|
@@ -31,8 +31,8 @@ TICK is an **amendment workflow** for existing SPIDER specifications. Rather tha
|
|
|
31
31
|
- Multiple stakeholders need alignment
|
|
32
32
|
|
|
33
33
|
### Cannot Use TICK when:
|
|
34
|
-
- No relevant
|
|
35
|
-
- Target spec is not yet `integrated` (complete the
|
|
34
|
+
- No relevant SPIR spec exists (create a new SPIR spec instead)
|
|
35
|
+
- Target spec is not yet `integrated` (complete the SPIR cycle first)
|
|
36
36
|
|
|
37
37
|
## Amendment Workflow
|
|
38
38
|
|
|
@@ -162,9 +162,9 @@ The format `[TICK ####-NNN]` identifies:
|
|
|
162
162
|
- `####`: Parent spec number (e.g., 0002)
|
|
163
163
|
- `NNN`: TICK amendment number (e.g., 001, 002, 003)
|
|
164
164
|
|
|
165
|
-
## Key Differences from
|
|
165
|
+
## Key Differences from SPIR
|
|
166
166
|
|
|
167
|
-
| Aspect |
|
|
167
|
+
| Aspect | SPIR | TICK |
|
|
168
168
|
|--------|--------|------|
|
|
169
169
|
| Purpose | Create new features | Amend existing features |
|
|
170
170
|
| File creation | Creates new spec/plan/review | Modifies spec/plan, creates review |
|
|
@@ -178,16 +178,16 @@ The format `[TICK ####-NNN]` identifies:
|
|
|
178
178
|
|
|
179
179
|
```
|
|
180
180
|
Is there an existing spec to amend?
|
|
181
|
-
├── NO → Use
|
|
181
|
+
├── NO → Use SPIR (create new spec)
|
|
182
182
|
└── YES → Is it integrated?
|
|
183
|
-
├── NO → Complete
|
|
183
|
+
├── NO → Complete SPIR cycle first
|
|
184
184
|
└── YES → Is the change small (<300 LOC)?
|
|
185
185
|
├── YES → Use TICK (amend existing spec)
|
|
186
|
-
└── NO → Use
|
|
186
|
+
└── NO → Use SPIR (scope too large)
|
|
187
187
|
```
|
|
188
188
|
|
|
189
189
|
**Mental Model**:
|
|
190
|
-
-
|
|
190
|
+
- SPIR = Create new feature from scratch
|
|
191
191
|
- TICK = Refine/extend existing feature
|
|
192
192
|
|
|
193
193
|
## Example TICK Workflow
|
|
@@ -251,7 +251,7 @@ Existing standalone TICK projects (created before this protocol change) are gran
|
|
|
251
251
|
1. **Single source of truth**: Spec file shows complete feature evolution
|
|
252
252
|
2. **Clear history**: Amendments section documents all changes chronologically
|
|
253
253
|
3. **Reduced fragmentation**: Related work stays together
|
|
254
|
-
4. **Simpler mental model**: "New vs amendment" is clearer than "
|
|
254
|
+
4. **Simpler mental model**: "New vs amendment" is clearer than "SPIR vs TICK"
|
|
255
255
|
5. **Preserved context**: Looking at a spec shows all refinements
|
|
256
256
|
|
|
257
257
|
## Limitations
|
|
@@ -264,14 +264,14 @@ Existing standalone TICK projects (created before this protocol change) are gran
|
|
|
264
264
|
## Best Practices
|
|
265
265
|
|
|
266
266
|
1. **Verify spec is integrated**: Never TICK a spec that isn't complete
|
|
267
|
-
2. **Keep TICKs small**: If scope grows, consider new
|
|
267
|
+
2. **Keep TICKs small**: If scope grows, consider new SPIR spec
|
|
268
268
|
3. **Clear summaries**: Amendment entries should be self-explanatory
|
|
269
269
|
4. **Test before review**: Always test functionality before presenting
|
|
270
270
|
5. **Honest documentation**: Document all deviations in review
|
|
271
271
|
|
|
272
272
|
## Templates
|
|
273
273
|
|
|
274
|
-
TICK uses the standard
|
|
275
|
-
- Spec template: `codev/protocols/
|
|
276
|
-
- Plan template: `codev/protocols/
|
|
274
|
+
TICK uses the standard SPIR templates with amendments sections:
|
|
275
|
+
- Spec template: `codev/protocols/spir/templates/spec.md` (includes Amendments section)
|
|
276
|
+
- Plan template: `codev/protocols/spir/templates/plan.md` (includes Amendment History section)
|
|
277
277
|
- Review template: `codev/protocols/tick/templates/review.md` (TICK-specific)
|
|
@@ -77,7 +77,7 @@
|
|
|
77
77
|
|
|
78
78
|
## TICK Protocol Feedback
|
|
79
79
|
- **Autonomous execution**: [Worked well / Issues encountered]
|
|
80
|
-
- **Single-phase approach**: [Appropriate / Should have used
|
|
80
|
+
- **Single-phase approach**: [Appropriate / Should have used SPIR]
|
|
81
81
|
- **Speed vs quality trade-off**: [Balanced / Too fast / Too slow]
|
|
82
82
|
- **End-only consultation**: [Caught issues / Missed opportunities]
|
|
83
83
|
|
|
@@ -91,7 +91,7 @@ Agent Farm is configured via `af-config.json` at the project root. Created durin
|
|
|
91
91
|
|
|
92
92
|
## Related Documentation
|
|
93
93
|
|
|
94
|
-
- [
|
|
94
|
+
- [SPIR Protocol](../protocols/spir/protocol.md) - Multi-phase development workflow
|
|
95
95
|
- [TICK Protocol](../protocols/tick/protocol.md) - Fast amendment workflow
|
|
96
96
|
- [Architect Role](../roles/architect.md) - Architect responsibilities
|
|
97
97
|
- [Builder Role](../roles/builder.md) - Builder responsibilities
|