specrails-core 4.12.0 → 5.0.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 +49 -78
- package/bin/specrails-core.mjs +18 -98
- package/bin/tui-installer.mjs +22 -105
- package/commands/doctor.md +1 -1
- package/dist/installer/cli.js +12 -2
- package/dist/installer/cli.js.map +1 -1
- package/dist/installer/commands/doctor.js +3 -5
- package/dist/installer/commands/doctor.js.map +1 -1
- package/dist/installer/commands/init.js +23 -19
- package/dist/installer/commands/init.js.map +1 -1
- package/dist/installer/commands/update.js +17 -16
- package/dist/installer/commands/update.js.map +1 -1
- package/dist/installer/commands/v5-migration.js +119 -0
- package/dist/installer/commands/v5-migration.js.map +1 -0
- package/dist/installer/phases/install-config.js +3 -6
- package/dist/installer/phases/install-config.js.map +1 -1
- package/dist/installer/phases/manifest.js +2 -6
- package/dist/installer/phases/manifest.js.map +1 -1
- package/dist/installer/phases/prereqs.js +0 -1
- package/dist/installer/phases/prereqs.js.map +1 -1
- package/dist/installer/phases/scaffold.js +38 -148
- package/dist/installer/phases/scaffold.js.map +1 -1
- package/package.json +1 -1
- package/schemas/profile.v1.json +1 -1
- package/templates/agents/sr-architect.md +30 -0
- package/templates/agents/sr-developer.md +21 -8
- package/templates/agents/sr-reviewer.md +44 -31
- package/templates/codex-skills/batch-implement/SKILL.md +9 -32
- package/templates/codex-skills/implement/SKILL.md +61 -143
- package/templates/codex-skills/rails/sr-architect/SKILL.md +38 -20
- package/templates/codex-skills/rails/sr-developer/SKILL.md +29 -10
- package/templates/codex-skills/rails/sr-reviewer/SKILL.md +21 -10
- package/templates/commands/specrails/doctor.md +1 -1
- package/templates/commands/specrails/implement.md +117 -288
- package/templates/commands/specrails/memory-inspect.md +6 -4
- package/templates/commands/specrails/propose-spec.md +1 -1
- package/templates/commands/specrails/refactor-recommender.md +8 -51
- package/templates/commands/specrails/retry.md +12 -48
- package/templates/commands/specrails/telemetry.md +1 -1
- package/templates/gemini-commands/implement.toml +9 -0
- package/templates/profiles/default.json +5 -18
- package/commands/enrich.md +0 -1456
- package/templates/agents/sr-backend-developer.md +0 -91
- package/templates/agents/sr-backend-reviewer.md +0 -152
- package/templates/agents/sr-doc-sync.md +0 -247
- package/templates/agents/sr-frontend-developer.md +0 -85
- package/templates/agents/sr-frontend-reviewer.md +0 -145
- package/templates/agents/sr-merge-resolver.md +0 -195
- package/templates/agents/sr-performance-reviewer.md +0 -186
- package/templates/agents/sr-product-analyst.md +0 -36
- package/templates/agents/sr-product-manager.md +0 -148
- package/templates/agents/sr-security-reviewer.md +0 -191
- package/templates/agents/sr-test-writer.md +0 -176
- package/templates/codex-skills/enrich/SKILL.md +0 -191
- package/templates/codex-skills/merge-resolve/SKILL.md +0 -88
- package/templates/codex-skills/rails/sr-backend-developer/SKILL.md +0 -93
- package/templates/codex-skills/rails/sr-backend-reviewer/SKILL.md +0 -120
- package/templates/codex-skills/rails/sr-doc-sync/SKILL.md +0 -124
- package/templates/codex-skills/rails/sr-frontend-developer/SKILL.md +0 -106
- package/templates/codex-skills/rails/sr-frontend-reviewer/SKILL.md +0 -111
- package/templates/codex-skills/rails/sr-merge-resolver/SKILL.md +0 -156
- package/templates/codex-skills/rails/sr-performance-reviewer/SKILL.md +0 -109
- package/templates/codex-skills/rails/sr-product-analyst/SKILL.md +0 -85
- package/templates/codex-skills/rails/sr-product-manager/SKILL.md +0 -131
- package/templates/codex-skills/rails/sr-security-reviewer/SKILL.md +0 -121
- package/templates/codex-skills/rails/sr-test-writer/SKILL.md +0 -115
- package/templates/commands/specrails/auto-propose-backlog-specs.md +0 -312
- package/templates/commands/specrails/enrich.md +0 -1456
- package/templates/commands/specrails/get-backlog-specs.md +0 -226
- package/templates/commands/specrails/merge-resolve.md +0 -172
- package/templates/commands/specrails/reconfig.md +0 -80
- package/templates/commands/specrails/vpc-drift.md +0 -405
- package/templates/commands/test.md +0 -58
- package/templates/personas/persona.md +0 -43
- package/templates/personas/the-maintainer.md +0 -98
- package/templates/settings/perf-thresholds.yml +0 -25
|
@@ -86,60 +86,37 @@ the pipeline yourself):
|
|
|
86
86
|
> Read `jq '.tickets["<TICKET_ID>"]' .specrails/local-tickets.json`
|
|
87
87
|
> for the full ticket. Follow the `$sr-architect` skill
|
|
88
88
|
> instructions exactly.
|
|
89
|
-
>
|
|
90
|
-
> In `design.md`'s `## Context` section, include a
|
|
91
|
-
> `Scope: <labels>` line drawn from: `frontend`, `backend`,
|
|
92
|
-
> `both`, `security-sensitive`, `performance-sensitive`.
|
|
93
89
|
|
|
94
90
|
- `wait_agent`. Parse reply for the plan path. `close_agent`.
|
|
95
|
-
- Open the plan + design.md
|
|
91
|
+
- Open the plan + design.md.
|
|
96
92
|
- If the architect returned `BLOCKED: …`, mark this ticket
|
|
97
93
|
as failed for the batch report and **continue to the next
|
|
98
94
|
ticket** — do not stop the batch.
|
|
99
95
|
|
|
100
96
|
#### 1.b Developer phase (per ticket)
|
|
101
97
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
| scope contains | rails available | spawn |
|
|
105
|
-
|---|---|---|
|
|
106
|
-
| `frontend` only | `sr-frontend-developer` | $sr-frontend-developer |
|
|
107
|
-
| `backend` only | `sr-backend-developer` | $sr-backend-developer |
|
|
108
|
-
| `frontend` only | (no fe specialist) | $sr-developer |
|
|
109
|
-
| `backend` only | (no be specialist) | $sr-developer |
|
|
110
|
-
| `both` + both specialists + tagged tasks.md | — | TWO devs parallel |
|
|
111
|
-
| else | — | $sr-developer |
|
|
98
|
+
One developer rail. Unless a profile routes the ticket to a
|
|
99
|
+
listed `custom-*` developer, spawn `$sr-developer`.
|
|
112
100
|
|
|
113
101
|
- `spawn_agent`. `send_message`:
|
|
114
102
|
|
|
115
|
-
>
|
|
103
|
+
> `$sr-developer`
|
|
116
104
|
>
|
|
117
105
|
> Ticket id: `<TICKET_ID>`
|
|
118
106
|
> Plan: `<PLAN_PATH>`
|
|
119
|
-
> Scope: `<comma-separated labels>`
|
|
120
107
|
>
|
|
121
|
-
> Follow the
|
|
108
|
+
> Follow the `$sr-developer` skill instructions exactly.
|
|
122
109
|
|
|
123
110
|
- `wait_agent`. Capture file list. `close_agent`.
|
|
124
111
|
- If `BLOCKED: …` → mark ticket as failed in the batch report
|
|
125
112
|
and move to next ticket.
|
|
126
113
|
|
|
127
|
-
#### 1.c Reviewer phase (per ticket)
|
|
128
|
-
|
|
129
|
-
Always spawn `$sr-reviewer`. Additionally if installed AND
|
|
130
|
-
scope matches:
|
|
131
|
-
|
|
132
|
-
| scope flag | additional rail |
|
|
133
|
-
|---|---|
|
|
134
|
-
| `frontend` | `$sr-frontend-reviewer` |
|
|
135
|
-
| `backend` | `$sr-backend-reviewer` |
|
|
136
|
-
| `security-sensitive` | `$sr-security-reviewer` |
|
|
137
|
-
| `performance-sensitive` | `$sr-performance-reviewer` |
|
|
114
|
+
#### 1.c Reviewer phase (per ticket)
|
|
138
115
|
|
|
139
|
-
Spawn
|
|
140
|
-
`close_agent
|
|
116
|
+
Spawn the single `$sr-reviewer` — it covers correctness, tests,
|
|
117
|
+
security, and performance. `wait_agent`, then `close_agent`.
|
|
141
118
|
|
|
142
|
-
|
|
119
|
+
Verdict (same matrix as `$implement`):
|
|
143
120
|
|
|
144
121
|
- `clean` — every reviewer ≥70, no fix/blocked verdicts.
|
|
145
122
|
- `fix needed` — any "fix needed", OR score <70 with no
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: implement
|
|
3
|
-
description: "Implement a single backlog ticket through a multi-phase pipeline: architect plans (OpenSpec proposal+design+tasks+specs),
|
|
3
|
+
description: "Implement a single backlog ticket through a multi-phase pipeline: architect plans (OpenSpec proposal+design+tasks+specs), sr-developer codes in TDD order, sr-reviewer validates (correctness, tests, security, performance). A profile may add custom-* rails. Reads .specrails/local-tickets.json, closes the ticket in place, reports concisely. Use when the user invokes `$implement #N` or `$implement <free-form>`."
|
|
4
4
|
license: MIT
|
|
5
5
|
compatibility: "Codex-native. Uses spawn_agent / send_message / wait_agent (full-history forks, no agent_type / model / reasoning_effort). Per-role instructions live in the rail skills; this orchestrator only routes."
|
|
6
6
|
---
|
|
@@ -40,7 +40,7 @@ move on.
|
|
|
40
40
|
|
|
41
41
|
**A `clean` run is NOT finished until the change is archived.**
|
|
42
42
|
Archiving (`openspec archive`) is a hard obligation, not an
|
|
43
|
-
optional epilogue — see Phase
|
|
43
|
+
optional epilogue — see Phase 4. If you mark a ticket `done`
|
|
44
44
|
without an archived change under `openspec/changes/archive/`,
|
|
45
45
|
you violated this contract.
|
|
46
46
|
|
|
@@ -71,27 +71,14 @@ and gives you a single aggregated report.
|
|
|
71
71
|
│
|
|
72
72
|
├─► PHASE 1: $sr-architect
|
|
73
73
|
│ produces openspec/changes/<slug>/{proposal,design,tasks,specs}
|
|
74
|
-
│ + a "Scope" tag in design.md
|
|
75
74
|
│
|
|
76
|
-
├─► PHASE 2: developer
|
|
77
|
-
│
|
|
78
|
-
│ scope=backend → $sr-backend-developer (if installed)
|
|
79
|
-
│ scope=both → spawn BOTH in parallel (tasks.md must be
|
|
80
|
-
│ partitioned), OR fall back to $sr-developer
|
|
81
|
-
│ else → $sr-developer
|
|
75
|
+
├─► PHASE 2: $sr-developer
|
|
76
|
+
│ implements every task (tests + docs included per task)
|
|
82
77
|
│
|
|
83
|
-
├─► PHASE 3: reviewer
|
|
84
|
-
│
|
|
85
|
-
│ frontend changes: $sr-frontend-reviewer (if installed)
|
|
86
|
-
│ backend changes: $sr-backend-reviewer (if installed)
|
|
87
|
-
│ security-sensitive: $sr-security-reviewer (if installed)
|
|
88
|
-
│ perf-sensitive: $sr-performance-reviewer (if installed)
|
|
78
|
+
├─► PHASE 3: $sr-reviewer
|
|
79
|
+
│ single reviewer — correctness, TDD/spec, security, performance
|
|
89
80
|
│
|
|
90
|
-
|
|
91
|
-
│ coverage dropped + $sr-test-writer installed → spawn
|
|
92
|
-
│ public surface changed + $sr-doc-sync installed → spawn
|
|
93
|
-
│
|
|
94
|
-
└─► PHASE 5: close ticket + report
|
|
81
|
+
└─► PHASE 4: close ticket + report
|
|
95
82
|
```
|
|
96
83
|
|
|
97
84
|
All spawns are **full-history forks**. NEVER pass `agent_type`,
|
|
@@ -109,14 +96,12 @@ the combo and you'll burn a turn on the retry.
|
|
|
109
96
|
`jq '.tickets["<ID>"]' .specrails/local-tickets.json`
|
|
110
97
|
3. **List the installed rail skills**:
|
|
111
98
|
`ls .codex/skills/rails/`
|
|
112
|
-
The
|
|
113
|
-
|
|
114
|
-
rails
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
a quick `ls`/`find`, and the optional rails that are
|
|
119
|
-
available. Do NOT plan files-to-touch — that's the
|
|
99
|
+
The three core rails (`sr-architect`, `sr-developer`,
|
|
100
|
+
`sr-reviewer`) are always present and are the only first-party
|
|
101
|
+
rails. A profile may add user-owned `custom-*` rails; spawn a
|
|
102
|
+
`custom-*` rail only when it is listed.
|
|
103
|
+
4. State (≤4 lines) the ticket goal and the stack you detected from
|
|
104
|
+
a quick `ls`/`find`. Do NOT plan files-to-touch — that's the
|
|
120
105
|
architect's job.
|
|
121
106
|
|
|
122
107
|
### 1. Phase 1 — Architect
|
|
@@ -135,161 +120,94 @@ the combo and you'll burn a turn on the retry.
|
|
|
135
120
|
> for the full ticket. Follow the `$sr-architect` skill
|
|
136
121
|
> instructions exactly.
|
|
137
122
|
>
|
|
138
|
-
> In `design.md`'s `## Context` section, include a
|
|
139
|
-
> `Scope: <labels>` line. Labels are a comma-separated set
|
|
140
|
-
> drawn from: `frontend`, `backend`, `both`, `security-sensitive`,
|
|
141
|
-
> `performance-sensitive`. Pick the labels that honestly apply
|
|
142
|
-
> to this change. The orchestrator uses these to route
|
|
143
|
-
> subsequent phases.
|
|
144
|
-
>
|
|
145
123
|
> Reply with the one-line summary the skill specifies.
|
|
146
124
|
|
|
147
125
|
- `wait_agent`. Read the reply. Extract the plan path.
|
|
148
126
|
- `close_agent`. Open the plan file + design.md.
|
|
149
|
-
- **Parse the Scope line** from design.md's Context section.
|
|
150
|
-
Store the set of labels for use in phases 2-3. If the line is
|
|
151
|
-
missing, default to scope = `both`.
|
|
152
127
|
|
|
153
128
|
If the architect replied with `BLOCKED: …`, stop the pipeline,
|
|
154
129
|
write that reason into the final report, and exit without
|
|
155
130
|
updating the ticket.
|
|
156
131
|
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
| `frontend` only | `sr-frontend-developer` | $sr-frontend-developer |
|
|
165
|
-
| `backend` only | `sr-backend-developer` | $sr-backend-developer |
|
|
166
|
-
| `frontend` only | (no fe specialist) | $sr-developer (general) |
|
|
167
|
-
| `backend` only | (no be specialist) | $sr-developer (general) |
|
|
168
|
-
| `both` | both specialists installed | TWO devs in parallel (see below) |
|
|
169
|
-
| `both` | only one or neither specialist | $sr-developer (general) |
|
|
170
|
-
| neither/unknown | — | $sr-developer (general) |
|
|
132
|
+
**Design confidence gate.** Read
|
|
133
|
+
`${SPECRAILS_REPO_DIR:-.}/openspec/changes/<slug>/design-confidence.json`
|
|
134
|
+
(the architect writes it as part of its skill). File missing →
|
|
135
|
+
warn and proceed (backward compatible). `high`/`medium` →
|
|
136
|
+
proceed. `low` → **STOP before Phase 2** — implementation is the
|
|
137
|
+
expensive phase and must not run on an unconfident design.
|
|
138
|
+
Report:
|
|
171
139
|
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
140
|
+
> `BLOCKED: design confidence low — <blocking_question>`
|
|
141
|
+
>
|
|
142
|
+
> Answer the question (edit the ticket description), then re-run
|
|
143
|
+
> `$implement #N`. The OpenSpec artifacts are left in place as a
|
|
144
|
+
> resumable starting point.
|
|
175
145
|
|
|
176
|
-
|
|
177
|
-
`developer-fe-#<TICKET_ID>` and `developer-be-#<TICKET_ID>`.
|
|
178
|
-
- `send_message` to the frontend agent: `$sr-frontend-developer
|
|
179
|
-
... only run task blocks tagged [frontend] in tasks.md`.
|
|
180
|
-
Symmetric message to the backend agent.
|
|
181
|
-
- `wait_agent` on BOTH. Aggregate the changed-files list.
|
|
182
|
-
- `close_agent` on both.
|
|
146
|
+
Do NOT update the ticket, do NOT spawn the developer.
|
|
183
147
|
|
|
184
|
-
|
|
185
|
-
to a single `$sr-developer` invocation — the parallel split
|
|
186
|
-
needs ordered, non-overlapping cycles.
|
|
148
|
+
### 2. Phase 2 — Developer
|
|
187
149
|
|
|
188
|
-
|
|
150
|
+
There is one developer rail. Unless an active profile routes the
|
|
151
|
+
ticket to a `custom-*` developer that is listed in step 0.3, spawn
|
|
152
|
+
`$sr-developer`.
|
|
189
153
|
|
|
190
154
|
- `spawn_agent` (full-history).
|
|
191
155
|
- `send_message`:
|
|
192
156
|
|
|
193
|
-
>
|
|
157
|
+
> `$sr-developer`
|
|
194
158
|
>
|
|
195
159
|
> Ticket id: `<TICKET_ID>`
|
|
196
160
|
> Plan: `<PLAN_PATH>`
|
|
197
|
-
> Scope: `<comma-separated labels>`
|
|
198
161
|
>
|
|
199
|
-
> Follow the
|
|
162
|
+
> Follow the `$sr-developer` skill instructions exactly.
|
|
200
163
|
|
|
201
164
|
- `wait_agent`. Capture file list. `close_agent`.
|
|
202
165
|
|
|
203
166
|
If the developer returned `BLOCKED: …`, surface it to the user
|
|
204
167
|
in the final report (no review phase, no ticket update).
|
|
205
168
|
|
|
206
|
-
### 3. Phase 3 — Reviewer
|
|
169
|
+
### 3. Phase 3 — Reviewer
|
|
207
170
|
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
| scope flag | rail to add (if installed) |
|
|
212
|
-
|---|---|
|
|
213
|
-
| `frontend` | `$sr-frontend-reviewer` |
|
|
214
|
-
| `backend` | `$sr-backend-reviewer` |
|
|
215
|
-
| `security-sensitive` | `$sr-security-reviewer` |
|
|
216
|
-
| `performance-sensitive` | `$sr-performance-reviewer` |
|
|
217
|
-
|
|
218
|
-
For each reviewer:
|
|
171
|
+
Spawn the single `$sr-reviewer`. It owns every review dimension —
|
|
172
|
+
correctness, TDD/spec completeness, code quality, security, and
|
|
173
|
+
performance — scaled to what the change touches.
|
|
219
174
|
|
|
220
175
|
- `spawn_agent` (full-history).
|
|
221
176
|
- `send_message`:
|
|
222
177
|
|
|
223
|
-
>
|
|
178
|
+
> `$sr-reviewer`
|
|
224
179
|
>
|
|
225
180
|
> Ticket id: `<TICKET_ID>`
|
|
226
181
|
> Plan: `<PLAN_PATH>`
|
|
227
182
|
> Changed files:
|
|
228
183
|
> <one per line>
|
|
229
184
|
>
|
|
230
|
-
> Follow the
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
wrong — a single developer fix pass can usually clear it
|
|
252
|
-
(e.g. API surface mismatch, missing JSX component shape,
|
|
253
|
-
forgotten persistence hook).
|
|
254
|
-
- `blocked` — any reviewer said `blocked: …` AND overall
|
|
255
|
-
score is **< 30**, OR every reviewer said `blocked: …`.
|
|
256
|
-
This is the design-level case where another developer
|
|
257
|
-
pass won't help — the architect needs to re-engage.
|
|
258
|
-
|
|
259
|
-
### 4. Phase 4 — Optional augmentation
|
|
260
|
-
|
|
261
|
-
Run AFTER review is `clean` (or after the single fix-loop pass).
|
|
262
|
-
Skip when the overall verdict is `fix needed` or `blocked` — no
|
|
263
|
-
point sugar-coating an unsound change.
|
|
264
|
-
|
|
265
|
-
- If `sr-test-writer` is installed AND the reviewer's confidence
|
|
266
|
-
artefact reports a coverage gap (`tdd_evidence.all_tasks_have_tests`
|
|
267
|
-
is `false`, or `tdd_evidence.tests_are_non_trivial` is `false`),
|
|
268
|
-
spawn it with the changed files list. It writes more tests, runs
|
|
269
|
-
them, reports. (These are the fields the `$sr-reviewer` skill
|
|
270
|
-
actually writes — do not key on a non-existent "coverage" field.)
|
|
271
|
-
- If `sr-doc-sync` is installed AND the change touches a
|
|
272
|
-
publicly-documented surface (README mentions a renamed
|
|
273
|
-
function, AGENTS.md references a removed file, openspec specs
|
|
274
|
-
drifted), spawn it.
|
|
275
|
-
|
|
276
|
-
These augment, never block. If they return findings, surface in
|
|
277
|
-
the final report under "Follow-up" rather than reopening the
|
|
278
|
-
ticket.
|
|
279
|
-
|
|
280
|
-
### 5. Optional fix loop (single pass only)
|
|
281
|
-
|
|
282
|
-
If phase 3's overall verdict is `fix needed`:
|
|
283
|
-
|
|
284
|
-
- Spawn ONE follow-up developer (same routing rules as phase 2)
|
|
285
|
-
with a message that includes every reviewer's `issues[]`
|
|
286
|
-
array from their confidence artefacts.
|
|
185
|
+
> Follow the `$sr-reviewer` skill instructions exactly.
|
|
186
|
+
|
|
187
|
+
- `wait_agent`. `close_agent`.
|
|
188
|
+
|
|
189
|
+
**Verdict** — parse `Score: N/100` and `Verdict: …` from the reply:
|
|
190
|
+
|
|
191
|
+
- `clean` — score ≥ 70 AND not fix/blocked.
|
|
192
|
+
- `fix needed` — verdict `fix needed: …`, OR score < 70 with no
|
|
193
|
+
`blocked: …`, OR `blocked: …` with score **in the recoverable
|
|
194
|
+
range 30-69** (a single developer fix pass can usually clear it).
|
|
195
|
+
- `blocked` — `blocked: …` with score **< 30**. Design-level; a
|
|
196
|
+
developer pass won't help — the architect needs to re-engage.
|
|
197
|
+
|
|
198
|
+
### 4. Optional fix loop (single pass only)
|
|
199
|
+
|
|
200
|
+
If phase 3's verdict is `fix needed`:
|
|
201
|
+
|
|
202
|
+
- Spawn ONE follow-up developer (`$sr-developer`, or the same
|
|
203
|
+
`custom-*` developer used in phase 2) with a message that
|
|
204
|
+
includes the reviewer's `issues[]` array from its confidence
|
|
205
|
+
artefact.
|
|
287
206
|
- `wait_agent`. `close_agent`.
|
|
288
|
-
- Re-run phase 3
|
|
289
|
-
|
|
290
|
-
report.
|
|
207
|
+
- Re-run phase 3. If still `fix needed` or `blocked`, **do not loop
|
|
208
|
+
again** — surface in the final report.
|
|
291
209
|
|
|
292
|
-
###
|
|
210
|
+
### 5. Phase 4 — Archive FIRST, then close + report
|
|
293
211
|
|
|
294
212
|
> **INVARIANT.** A ticket may be marked `done` ONLY if its change is
|
|
295
213
|
> archived (`openspec/changes/archive/<slug>/` exists). A `clean`
|
|
@@ -5,6 +5,12 @@ license: MIT
|
|
|
5
5
|
compatibility: "Codex-native. Designed to run as a full-history sub-agent fork of the implement orchestrator."
|
|
6
6
|
---
|
|
7
7
|
|
|
8
|
+
**Deterministic repo map.** If `SPECRAILS_REPO_MAP_PATH` is set
|
|
9
|
+
and readable, read that file FIRST — a zero-AI map of the repo
|
|
10
|
+
(packages, ecosystems, sizes) generated by the spawner. Use it to
|
|
11
|
+
orient; do not spend turns on top-level discovery. Unset ⇒ explore
|
|
12
|
+
as normal.
|
|
13
|
+
|
|
8
14
|
You are the **architect** in the specrails implement pipeline. The
|
|
9
15
|
orchestrator already loaded the ticket and surveyed the repo before
|
|
10
16
|
spawning you. Your turn is short, focused, and ends with TWO
|
|
@@ -87,18 +93,6 @@ writing code.
|
|
|
87
93
|
<one paragraph: the system state today, the constraints the
|
|
88
94
|
change must respect, the assumptions you are making.>
|
|
89
95
|
|
|
90
|
-
Scope: <comma-separated labels — pick honestly from:
|
|
91
|
-
frontend, backend, both, security-sensitive,
|
|
92
|
-
performance-sensitive>
|
|
93
|
-
Examples:
|
|
94
|
-
- "Scope: frontend"
|
|
95
|
-
- "Scope: backend, security-sensitive"
|
|
96
|
-
- "Scope: both, performance-sensitive"
|
|
97
|
-
The implement orchestrator parses this line to route
|
|
98
|
-
the developer + reviewer phases. A missing or wrong
|
|
99
|
-
label means the wrong specialists get spawned (or
|
|
100
|
-
none at all).
|
|
101
|
-
|
|
102
96
|
## Goal
|
|
103
97
|
<one sentence: what observable behaviour you are adding /
|
|
104
98
|
changing.>
|
|
@@ -155,12 +149,13 @@ the table.
|
|
|
155
149
|
|
|
156
150
|
## 1. <First testable behaviour>
|
|
157
151
|
- [ ] 1.1 Write a failing test in `<test-path>` that asserts
|
|
158
|
-
<behaviour>. Run
|
|
152
|
+
<behaviour>. Run that test file (scoped); the new test
|
|
153
|
+
MUST fail.
|
|
159
154
|
- [ ] 1.2 Implement the minimum production code in `<src-path>`
|
|
160
|
-
to make the test pass.
|
|
161
|
-
MUST pass.
|
|
162
|
-
- [ ] 1.3 Refactor if needed without changing behaviour.
|
|
163
|
-
the test
|
|
155
|
+
to make the test pass. Re-run that test file (scoped);
|
|
156
|
+
it MUST pass.
|
|
157
|
+
- [ ] 1.3 Refactor if needed without changing behaviour. Re-run
|
|
158
|
+
the test files covering the touched files; still green.
|
|
164
159
|
|
|
165
160
|
## 2. <Next testable behaviour>
|
|
166
161
|
- [ ] 2.1 Write a failing test...
|
|
@@ -272,13 +267,36 @@ written:
|
|
|
272
267
|
If validation reports structural errors, fix the offending
|
|
273
268
|
artefact and re-run until it passes. Do not hand off a change
|
|
274
269
|
that fails `openspec validate`.
|
|
275
|
-
2.
|
|
270
|
+
2. **Emit design confidence** (mandatory). Write
|
|
271
|
+
`${SPECRAILS_REPO_DIR:-.}/openspec/changes/<slug>/design-confidence.json`:
|
|
272
|
+
```json
|
|
273
|
+
{
|
|
274
|
+
"schema_version": "1",
|
|
275
|
+
"change": "<slug>",
|
|
276
|
+
"agent": "architect",
|
|
277
|
+
"scored_at": "<ISO 8601>",
|
|
278
|
+
"confidence": "high | medium | low",
|
|
279
|
+
"reason": "<1-2 concrete sentences>",
|
|
280
|
+
"blocking_question": "<one focused question when low, else null>"
|
|
281
|
+
}
|
|
282
|
+
```
|
|
283
|
+
Rubric — **high**: evidence conclusive, exact files/identifiers
|
|
284
|
+
located, design unambiguous. **medium**: likely correct but one
|
|
285
|
+
non-obvious assumption remains (name it in `reason`). **low**:
|
|
286
|
+
multiple plausible designs and you cannot choose without
|
|
287
|
+
information you don't have — `blocking_question` is the SINGLE
|
|
288
|
+
most blocking unknown, phrased so a human can answer it. Never
|
|
289
|
+
inflate: a `low` with a sharp question is a successful output —
|
|
290
|
+
it saves the whole implementation cost of building the wrong
|
|
291
|
+
thing.
|
|
292
|
+
3. Reply with three lines:
|
|
276
293
|
```
|
|
277
294
|
OpenSpec change: openspec/changes/<slug>/
|
|
278
295
|
Plan written to <plan-path>; files to touch: <comma-separated list>
|
|
296
|
+
Design confidence: <high|medium|low>[ — blocking question: <question>]
|
|
279
297
|
```
|
|
280
|
-
|
|
281
|
-
tasks.md and spawn the developer next.
|
|
298
|
+
4. End your turn. The orchestrator will read your plan + the
|
|
299
|
+
tasks.md and spawn the developer next (or halt on `low`).
|
|
282
300
|
|
|
283
301
|
If you cannot produce a plan (ticket is too ambiguous, repo
|
|
284
302
|
state is corrupt, etc.), instead reply with:
|
|
@@ -72,9 +72,10 @@ note it in your reply — do not block on the architect.
|
|
|
72
72
|
a. **RED — write the failing test (step N.1).**
|
|
73
73
|
- Open the test file the task names. Create it if missing.
|
|
74
74
|
- Add the test asserting the behaviour the task names.
|
|
75
|
-
- Run
|
|
76
|
-
|
|
77
|
-
|
|
75
|
+
- Run **only that test file** (scoped run — e.g.
|
|
76
|
+
`npx vitest run <file>`, `pytest <file>`). The new test
|
|
77
|
+
MUST fail. If it unexpectedly passes, your test is wrong
|
|
78
|
+
(it isn't actually asserting the new behaviour) — rewrite it.
|
|
78
79
|
- Tick `- [x] N.1` in `tasks.md` only when you have
|
|
79
80
|
observed the test fail.
|
|
80
81
|
|
|
@@ -83,16 +84,27 @@ note it in your reply — do not block on the architect.
|
|
|
83
84
|
modify it.
|
|
84
85
|
- Write the minimum code to make the failing test pass.
|
|
85
86
|
Resist adding code unrelated to the test.
|
|
86
|
-
-
|
|
87
|
-
|
|
87
|
+
- Re-run **only that test file** (`npx vitest run
|
|
88
|
+
<file>`, `pytest <file>`, …). It must pass. The full
|
|
89
|
+
suite runs once, at the validation gate — not after
|
|
90
|
+
every task.
|
|
88
91
|
- Tick `- [x] N.2`.
|
|
89
92
|
|
|
90
93
|
c. **REFACTOR — clean up (step N.3, if present).**
|
|
91
94
|
- If the production code can be clearer without changing
|
|
92
95
|
behaviour, refactor it now.
|
|
93
|
-
- Re-run the test
|
|
96
|
+
- Re-run the test files covering the files you touched.
|
|
97
|
+
Still green.
|
|
94
98
|
- Tick `- [x] N.3`.
|
|
95
99
|
|
|
100
|
+
**Test-execution economy (MANDATORY):** the full project
|
|
101
|
+
suite runs exactly ONCE — at the validation gate below.
|
|
102
|
+
Never run it inside a task cycle. When a scoped run fails,
|
|
103
|
+
carry forward only the failing test names and the relevant
|
|
104
|
+
error excerpt (≤50 lines), never a full runner log. If you
|
|
105
|
+
run the same command 3 times with no intervening code
|
|
106
|
+
change, STOP re-running and change the code or the test.
|
|
107
|
+
|
|
96
108
|
3. **Honour the design's invariants and edge cases.** When the
|
|
97
109
|
design's `Public API / surface` says a function takes `(x, y)`
|
|
98
110
|
and returns `Result<Z>`, your code must match that signature
|
|
@@ -115,15 +127,22 @@ The final task block in `tasks.md` is always the validation gate
|
|
|
115
127
|
(`## N. Validation gate`). Run it:
|
|
116
128
|
|
|
117
129
|
- Full project test suite (e.g. `npm test`, `pytest`,
|
|
118
|
-
`cargo test`). MUST pass.
|
|
130
|
+
`cargo test`). MUST pass. This is the pipeline's SINGLE
|
|
131
|
+
full pass — the per-task loop stayed scoped so this one
|
|
132
|
+
can be exhaustive.
|
|
119
133
|
- Project build if present (e.g. `npm run build`,
|
|
120
134
|
`cargo build`). MUST succeed.
|
|
121
135
|
- A grep for debug breadcrumbs (`console.log`, `print(`, etc.)
|
|
122
136
|
in the files you touched — none should remain.
|
|
123
137
|
|
|
124
|
-
If the gate fails, the offending file is your responsibility
|
|
125
|
-
|
|
126
|
-
|
|
138
|
+
If the gate fails, the offending file is your responsibility.
|
|
139
|
+
Fix it, re-running **only the failing test files** between
|
|
140
|
+
fixes — you have a budget of 2 fix cycles, then ONE final
|
|
141
|
+
full-suite run to confirm. If failures persist after that,
|
|
142
|
+
reply `"BLOCKED: validation gate failing — <failing tests,
|
|
143
|
+
verbatim>"` and end your turn. Never keep looping, never
|
|
144
|
+
weaken or skip tests to force green, never hand a known
|
|
145
|
+
failure silently to the reviewer.
|
|
127
146
|
|
|
128
147
|
## What you must NOT do
|
|
129
148
|
|
|
@@ -109,16 +109,27 @@ a screenshot/manual-check note in the design's
|
|
|
109
109
|
"Open questions". A criterion with **no** mapping is a
|
|
110
110
|
blocker finding.
|
|
111
111
|
|
|
112
|
-
### 5.
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
112
|
+
### 5. Verify the gate — scoped-first
|
|
113
|
+
|
|
114
|
+
The developer's validation gate already ran the full suite
|
|
115
|
+
green; re-running the whole thing on an untouched tree
|
|
116
|
+
re-buys information the pipeline already has. So:
|
|
117
|
+
|
|
118
|
+
- Run the tests SCOPED to the diff — the test files covering
|
|
119
|
+
every changed source file, per-file (`npx vitest run
|
|
120
|
+
<file>`, `pytest <file>`, `cargo test <name>`, …). Confirm
|
|
121
|
+
green; capture the count.
|
|
122
|
+
- Run the full suite yourself ONLY when: you modified
|
|
123
|
+
production code in this review, the diff touches
|
|
124
|
+
build/config/test infrastructure, or a scoped failure has
|
|
125
|
+
an unclear blast radius. Then finish with ONE clean full
|
|
126
|
+
pass (plus the build if present) — never repeated full
|
|
127
|
+
passes between fixes.
|
|
128
|
+
- If you changed nothing and the scoped runs are green,
|
|
129
|
+
record the developer's gate as the pass of record — in the
|
|
130
|
+
confidence artefact set `tests.ran` to the scoped command
|
|
131
|
+
and say so in `tests.details`.
|
|
132
|
+
- If no test runner exists, run whatever fallback the design
|
|
122
133
|
named (`node --check`, etc.).
|
|
123
134
|
|
|
124
135
|
### 6. Write the confidence artefact
|
|
@@ -35,7 +35,7 @@ Each check is displayed as ✅ (pass) or ❌ (fail with fix instruction).
|
|
|
35
35
|
|
|
36
36
|
On all checks passed:
|
|
37
37
|
```
|
|
38
|
-
All 6 checks passed. Run /specrails:
|
|
38
|
+
All 6 checks passed. Run /specrails:implement to get started.
|
|
39
39
|
```
|
|
40
40
|
|
|
41
41
|
On failure:
|