You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 362631d
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: docs/reference/agentic-sdd.md
+15-4Lines changed: 15 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -109,7 +109,18 @@ Assesses the codebase against the feature's spec, plan, and tasks to confirm not
109
109
/speckit.converge
110
110
```
111
111
112
-
It first prints a severity-graded findings summary, then resolves to one of two outcomes:
113
-
114
-
-**Converged** — no gaps found. `tasks.md` is left byte-for-byte unchanged and you'll see a clean result like `✅ Converged — the implementation satisfies the spec, plan, and tasks.` You're done; proceed to review or open a PR.
115
-
-**Tasks appended** — gaps found. Converge appends them as new tasks under a Convergence section in `tasks.md` and tells you how many. Run `/speckit.implement` again to complete them, then `/speckit.converge` once more. Each pass finds fewer items; repeat until it reports converged.
112
+
It first prints a severity-graded findings summary, including per-category `checked/total`
113
+
coverage and a compact stable-key inventory ledger. Counts are derived from the feature artifacts,
114
+
not model memory. It then resolves to one of three outcomes:
115
+
116
+
-**Incomplete assessment** — one or more inventory keys could not be assessed. The report names
117
+
those keys and their incomplete coverage category, does not modify `tasks.md`, and is **not** a
118
+
clean result. Resolve the missing evidence and run `/speckit.converge` again.
119
+
-**Converged** — every applicable inventory category is fully assessed and no gaps were found.
120
+
`tasks.md` is left byte-for-byte unchanged and you'll see a clean result like
121
+
`✅ Converged — the implementation satisfies the spec, plan, and tasks.` You're done; proceed
122
+
to review or open a PR.
123
+
-**Tasks appended** — every applicable inventory category is fully assessed and gaps were found.
124
+
Converge appends them as new tasks under a Convergence section in `tasks.md` and tells you how
125
+
many. Run `/speckit.implement` again to complete them, then `/speckit.converge` once more.
126
+
Each pass finds fewer items; repeat until it reports converged.
Copy file name to clipboardExpand all lines: templates/commands/converge.md
+63-17Lines changed: 63 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -50,6 +50,7 @@ You **MUST** consider the user input before proceeding (if not empty).
50
50
51
51
Wait for the result of the hook command before proceeding to the Goal.
52
52
```
53
+
53
54
After emitting the block above you MUST actually invoke the hook and wait for it to finish before continuing. Run it the same way you would run the command yourself in this agent/session (the invocation may differ from the literal `{command}` id shown above, e.g. a skills-mode agent runs it as `/skill:speckit-...` or `$speckit-...`). Emitting the block alone does not run the hook.
54
55
55
56
- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
@@ -132,15 +133,30 @@ Load only the minimal necessary context from each artifact:
132
133
133
134
### 3. Build the Intent Inventory
134
135
135
-
Create an internal model (do not echo raw artifacts):
136
-
137
-
- **Requirements inventory**: one stable key per FR-### / SC-### / user-story acceptance
138
-
scenario (e.g. `US1/AC2`), plus the plan decisions and constitution principles that
139
-
impose buildable obligations.
136
+
Create an internal model (do not echo raw artifact prose). The report **MUST** emit the
137
+
stable keys and statuses from this model in the compact inventory ledger required by Step 6:
138
+
139
+
- **Requirements inventory**: one stable key per buildable `FR-###`, buildable `SC-###`, and
140
+
user-story acceptance scenario (e.g. `US1/AC2`), plus the plan decisions and constitution
141
+
principles that impose buildable obligations.
142
+
- **Per-key status**: initialize every applicable key as `unassessed`. End the assessment with
143
+
exactly one status per key: `checked:no-gap`, `checked:gap(F#)`, or `unassessed` when the
144
+
evidence could not be evaluated. A user story is **not** assessed on behalf of its individual
145
+
acceptance scenarios; each `USn/ACn` key is counted independently. When a user story or
146
+
scenario has no explicit ID, derive `US<story-position>/AC<scenario-position>` from its order
147
+
under the User Stories section; do not collapse it into a prose-only row.
148
+
- **Plan and constitution keys**: use an explicit label from the artifact when present (for
149
+
example `plan: D1` or `Constitution II`). Otherwise, derive a stable ordinal key from its
150
+
artifact order (`plan: decision-01`, `Constitution principle-01`).
151
+
- **Coverage denominators**: count applicable keys from the loaded artifacts before assessing
152
+
code. Keep separate totals for buildable FRs, buildable SCs, acceptance scenarios, plan
153
+
decisions, and applicable Constitution MUST principles. A category with no applicable keys is
154
+
reported as `0/0 (not applicable)` and does not block convergence. Do not derive, estimate, or
155
+
recall a denominator from model memory.
140
156
- **Code-scope map**: from the file paths named in `plan.md` and `tasks.md`, plus a keyword
141
157
search for the concepts each requirement describes, derive the set of source files and
142
-
components in scope for assessment. Bound the assessment to these — do **not** infer
143
-
scope beyond what the artifacts define.
158
+
components in scope for assessment. Bound the assessment to these — do **not** infer scope
159
+
beyond what the artifacts define.
144
160
145
161
### 4. Assess the Codebase and Classify Findings
146
162
@@ -185,17 +201,42 @@ Before appending anything, output a compact, severity-graded summary (no file wr
**If any applicable key is `unassessed`, or any coverage numerator is below its denominator**
231
+
(`incomplete_assessment` outcome):
197
232
198
-
**If there are one or more actionable findings** (`tasks_appended` outcome):
233
+
- Do **not** modify `tasks.md` at all — no Convergence phase, even if findings were already
234
+
discovered for other keys.
235
+
- Report the incomplete category counts and each `unassessed` key in the inventory ledger.
236
+
- State that the result is not converged and recommend resolving the missing evidence, then
237
+
rerunning `__SPECKIT_COMMAND_CONVERGE__`.
238
+
239
+
**Otherwise, if there are one or more actionable findings** (`tasks_appended` outcome):
199
240
200
241
Append to the **end** of `tasks.md`, per the append contract:
201
242
@@ -219,14 +260,18 @@ Append to the **end** of `tasks.md`, per the append contract:
219
260
4. Never reuse or renumber existing IDs. If a prior Convergence phase exists, add a new,
220
261
separately-numbered one below it — do not touch the old one.
221
262
222
-
**If there are no actionable findings** (`converged` outcome):
263
+
**Otherwise** (`converged` outcome):
223
264
265
+
- All applicable coverage metrics are `total/total` and there are zero actionable findings.
224
266
- Do **not** modify `tasks.md` at all — no empty phase header.
225
267
- Report: **"✅ Converged — the implementation satisfies the spec, plan, and tasks."**
226
-
- Include the summary counts of what was checked.
268
+
- Include the coverage metrics and inventory ledger.
227
269
228
270
### 8. Provide Next Actions (Handoff)
229
271
272
+
- On `incomplete_assessment`: state which keys need assessment and recommend resolving the
273
+
missing evidence, then rerunning `__SPECKIT_COMMAND_CONVERGE__`. Do not recommend
274
+
`__SPECKIT_COMMAND_IMPLEMENT__` from a partial assessment.
230
275
- On `tasks_appended`: state how many tasks were appended under which phase, and recommend
231
276
running `__SPECKIT_COMMAND_IMPLEMENT__` to complete them; note that a follow-up converge
232
277
run will find fewer or no remaining items.
@@ -243,8 +288,8 @@ After producing the result, check if `.specify/extensions.yml` exists in the pro
243
288
- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
244
289
- If the hook has no `condition` field, or it is null/empty, treat the hook as executable
245
290
- If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
246
-
- Report the convergence outcome (`converged` or `tasks_appended`) in-session before listing
247
-
any hooks, so users can decide whether to run optional follow-up commands.
291
+
- Report the convergence outcome (`incomplete_assessment`, `converged`, or `tasks_appended`) in-session
292
+
before listing any hooks, so users can decide whether to run optional follow-up commands.
248
293
- For each executable hook, output the following based on its `optional` flag:
249
294
-**Optional hook** (`optional: true`):
250
295
@@ -268,6 +313,7 @@ After producing the result, check if `.specify/extensions.yml` exists in the pro
268
313
Executing: `/{command}`
269
314
EXECUTE_COMMAND: {command}
270
315
```
316
+
271
317
After emitting the block above you MUST actually invoke the hook and wait for it to finish before continuing. Run it the same way you would run the command yourself in this agent/session (the invocation may differ from the literal `{command}` id shown above, e.g. a skills-mode agent runs it as `/skill:speckit-...` or `$speckit-...`). Emitting the block alone does not run the hook.
272
318
273
319
- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
0 commit comments