@tduyng/pi-devos 0.13.6 → 0.14.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.
Files changed (100) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/README.md +26 -33
  3. package/package.json +1 -2
  4. package/plugins/devos/agents/verifier.md +4 -30
  5. package/plugins/devos/pi/extension/devos.ts +16 -26
  6. package/plugins/devos/scripts/check-evidence-router.sh +7 -1
  7. package/plugins/devos/scripts/evidence-router.py +5 -3
  8. package/plugins/devos/scripts/gates/check-dod-core.sh +5 -3
  9. package/plugins/devos/scripts/gates/check-port-source.sh +1 -1
  10. package/plugins/devos/scripts/gates/check-scenario-coverage.sh +10 -8
  11. package/plugins/devos/scripts/gates/phase-gate.sh +6 -6
  12. package/plugins/devos/scripts/gates/plan-template-check.py +6 -12
  13. package/plugins/devos/scripts/gates/spec-contract.sh +19 -0
  14. package/plugins/devos/scripts/gates/spec-template-check.py +8 -21
  15. package/plugins/devos/scripts/gates/suite/01-dod.sh +485 -0
  16. package/plugins/devos/scripts/gates/suite/02-integrity.sh +310 -0
  17. package/plugins/devos/scripts/gates/suite/03-archetype.sh +255 -0
  18. package/plugins/devos/scripts/gates/suite/04-spec-validator.sh +183 -0
  19. package/plugins/devos/scripts/gates/suite/05-requires.sh +360 -0
  20. package/plugins/devos/scripts/gates/suite/06-clarify-adapters.sh +435 -0
  21. package/plugins/devos/scripts/gates/suite/07-lint-evals.sh +350 -0
  22. package/plugins/devos/scripts/gates/suite/08-converge.sh +591 -0
  23. package/plugins/devos/scripts/gates/suite/09-quality.sh +516 -0
  24. package/plugins/devos/scripts/gates/suite/10-eval-harness.sh +679 -0
  25. package/plugins/devos/scripts/gates/test-gates.sh +23 -4253
  26. package/plugins/devos/scripts/gates/test-integrity-rubric.sh +1 -1
  27. package/plugins/devos/scripts/gates/test-phase-gate.sh +5 -5
  28. package/plugins/devos/skills/build/SKILL.md +3 -3
  29. package/plugins/devos/skills/build/references/refactor.md +1 -1
  30. package/plugins/devos/skills/build/references/routes.md +4 -4
  31. package/plugins/devos/skills/frame/SKILL.md +22 -39
  32. package/plugins/devos/skills/frame/references/template.md +115 -0
  33. package/plugins/devos/skills/implement/SKILL.md +4 -4
  34. package/plugins/devos/skills/implement/references/dod.md +6 -1
  35. package/plugins/devos/skills/implement/references/implement.md +3 -1
  36. package/plugins/devos/skills/implement/references/plan.md +9 -27
  37. package/plugins/devos/skills/implement/references/resume.md +1 -1
  38. package/plugins/devos/skills/implement/references/verify-close.md +4 -3
  39. package/plugins/devos/skills/implement/scripts/ops-log.sh +2 -2
  40. package/plugins/devos/skills/implement/scripts/validate-spec.sh +17 -65
  41. package/plugins/devos/skills/init/references/context.md +1 -1
  42. package/plugins/devos/skills/review/SKILL.md +24 -47
  43. package/plugins/devos/skills/review/references/comments.md +13 -0
  44. package/plugins/devos/skills/review/references/reviewer.md +124 -0
  45. package/plugins/devos/skills/review/references/routing.md +35 -0
  46. package/plugins/devos/skills/review/scripts/__pycache__/prepare.cpython-313.pyc +0 -0
  47. package/plugins/devos/skills/review/scripts/prepare.py +763 -0
  48. package/plugins/devos/skills/spec/SKILL.md +5 -6
  49. package/plugins/devos/skills/spec/references/write-spec.md +36 -51
  50. package/plugins/devos/skills/spec/scripts/clarify.sh +4 -4
  51. package/plugins/devos/skills/status/SKILL.md +4 -4
  52. package/plugins/devos/skills/status/scripts/check-requires.py +4 -4
  53. package/plugins/devos/skills/status/scripts/convention-usage.sh +1 -1
  54. package/plugins/devos/skills/status/scripts/quality-correlation.sh +2 -25
  55. package/plugins/devos/scripts/gates/check-handoff.sh +0 -215
  56. package/plugins/devos/skills/design-taste/SKILL.md +0 -55
  57. package/plugins/devos/skills/design-taste/references/tells.md +0 -85
  58. package/plugins/devos/skills/design-taste/scripts/slop-scan.py +0 -305
  59. package/plugins/devos/skills/docs/SKILL.md +0 -22
  60. package/plugins/devos/skills/docs/references/backfill.md +0 -54
  61. package/plugins/devos/skills/docs/references/init.md +0 -43
  62. package/plugins/devos/skills/docs/references/status.md +0 -71
  63. package/plugins/devos/skills/docs/references/update.md +0 -80
  64. package/plugins/devos/skills/explain/SKILL.md +0 -45
  65. package/plugins/devos/skills/explain/references/quiz.md +0 -21
  66. package/plugins/devos/skills/frame/references/boundaries.md +0 -53
  67. package/plugins/devos/skills/frame/references/decompose.md +0 -96
  68. package/plugins/devos/skills/frame/references/impact.md +0 -43
  69. package/plugins/devos/skills/frame/references/interrogate.md +0 -68
  70. package/plugins/devos/skills/product/SKILL.md +0 -40
  71. package/plugins/devos/skills/product/references/planner.md +0 -54
  72. package/plugins/devos/skills/surgical-diff/SKILL.md +0 -23
  73. package/plugins/devos/skills/test-integrity/SKILL.md +0 -26
  74. package/plugins/devos/skills/verification-evidence/SKILL.md +0 -17
  75. package/plugins/devos/workflows/common/backlog-file-structure.md +0 -44
  76. package/plugins/devos/workflows/common/category-file-structure.md +0 -41
  77. package/plugins/devos/workflows/common/feature-line-format.md +0 -10
  78. package/plugins/devos/workflows/common/roadmap-file-structure.md +0 -51
  79. package/plugins/devos/workflows/common/suggest-categories.md +0 -76
  80. package/plugins/devos/workflows/common/suggest-milestones.md +0 -92
  81. package/plugins/devos/workflows/doc/doc-health.md +0 -137
  82. package/plugins/devos/workflows/doc/doc-writer.md +0 -44
  83. package/plugins/devos/workflows/doc/init-documentation.md +0 -196
  84. package/plugins/devos/workflows/doc/retro-documentation.md +0 -304
  85. package/plugins/devos/workflows/doc/templates/library.md +0 -58
  86. package/plugins/devos/workflows/doc/templates/service.md +0 -61
  87. package/plugins/devos/workflows/doc/update-documentation.md +0 -194
  88. package/plugins/devos/workflows/doc/write-documentation.md +0 -137
  89. package/plugins/devos/workflows/product/create-product-mission.md +0 -45
  90. package/plugins/devos/workflows/product/create-product-roadmap.md +0 -106
  91. package/plugins/devos/workflows/product/create-product-tech-stack.md +0 -19
  92. package/plugins/devos/workflows/product/gather-product-info.md +0 -25
  93. package/plugins/devos/workflows/product/resume-detection.md +0 -70
  94. package/plugins/devos/workflows/product/reverse-backlog.md +0 -118
  95. package/plugins/devos/workflows/product/reverse-domain-model.md +0 -86
  96. package/plugins/devos/workflows/product/reverse-product-plan.md +0 -81
  97. package/plugins/devos/workflows/product/reverse-tech-stack.md +0 -73
  98. package/plugins/devos/workflows/product/scan-deep.md +0 -113
  99. package/plugins/devos/workflows/product/scan-git.md +0 -122
  100. package/plugins/devos/workflows/product/scan-light.md +0 -154
@@ -1,304 +0,0 @@
1
- # Workflow: Retro Documentation
2
-
3
- **Goal:** Generate consolidated documentation retroactively from all existing specs AND the source code. Specs are the base, code fills in for unspecified features. The documentation reflects the real code.
4
-
5
- **Input:** Specs in `devos/specs/` (optional) + source code (always)
6
-
7
- **Output:** Complete documentation in `/${DOC_DIR}/`, updated mapping
8
-
9
- ---
10
-
11
- ## Step 1: Read and inventory
12
-
13
- ### 1.1 Check prerequisites
14
-
15
- The documentation plan must exist:
16
-
17
- ```bash
18
- ls devos/product/documentation-plan.md 2>/dev/null
19
- ```
20
-
21
- If missing:
22
- ```
23
- ❌ No documentation plan found.
24
-
25
- Run first: /devos:docs init
26
- ```
27
- **STOP**
28
-
29
- ### 1.2 Inventory the sources
30
-
31
- #### 1.2a Existing specs (if available)
32
-
33
- `Glob devos/specs/*/spec-functional.md`
34
-
35
- For each spec found:
36
- 1. `Read` the `spec-functional.md`
37
- 2. Identify the implementation status (check `verifications/verification.md` exists)
38
- 3. Sort by date (YYYY-MM-DD prefix of the folder)
39
-
40
- If no spec found: note "0 specs", work from the code alone.
41
-
42
- #### 1.2b Source code (always)
43
-
44
- Scan the project structure to identify code sources:
45
- 1. `Glob` for source files: `src/**/*.{ts,tsx,js,jsx,py,go,java,kt,swift,rb,rs,php}`
46
- 2. Identify the main folders and tech stack
47
- 3. This scan will be deepened in step 3bis
48
-
49
- ### 1.3 Read existing plan and mapping
50
-
51
- 1. `Read devos/product/documentation-plan.md`
52
- 2. `Read devos/product/documentation-mapping.md` (may not exist)
53
-
54
- ### 1.4 Configuration
55
-
56
- ```bash
57
- ```
58
-
59
- **Variable:** `DOC_DIR` = `documentation` (fixed default; change it by editing this workflow)
60
-
61
- ---
62
-
63
- ## Step 2: Group by domain
64
-
65
- ### 2.1 Attach to the existing plan
66
-
67
- If a `documentation-plan.md` exists:
68
- 1. For each spec, determine which domain(s) of the plan it feeds
69
- 2. Attach specs to existing domains
70
-
71
- ### 2.2 Semantic analysis for orphan specs
72
-
73
- For specs not attached to the plan:
74
- 1. Analyze the functional content of each spec
75
- 2. Group by semantic proximity (similar features, shared entities)
76
- 3. Propose new domains if needed
77
-
78
- ### 2.3 Present the grouping
79
-
80
- ```
81
- Grouping specs by domain:
82
-
83
- Existing domains (from the plan):
84
- | Domain | Attached specs | Coverage |
85
- |---------|-----------------|------------|
86
- | [Domain 1] | spec-a, spec-b | [N] specs |
87
-
88
- New domains proposed:
89
- | Domain | Specs | Justification |
90
- |---------|-------|---------------|
91
- | [New 1] | spec-c, spec-d | [reason for grouping] |
92
-
93
- Orphan specs (not attached):
94
- - [spec-e]: [reason for exclusion]
95
-
96
- Validate this grouping? (yes/no/modify)
97
- ```
98
-
99
- **WAIT** for explicit validation.
100
-
101
- ---
102
-
103
- ## Step 3: Implementation check (specs vs code)
104
-
105
- **If specs exist:**
106
-
107
- ### 3.1 Chronological consolidation
108
-
109
- For each domain, order specs chronologically:
110
- 1. Identify specs that overlap (same feature, different dates)
111
- 2. Resolve contradictions: the most recent spec prevails
112
- 3. Produce a consolidated view per domain
113
-
114
- ### 3.2 Spec vs code confrontation
115
-
116
- For each consolidated feature:
117
- 1. `Grep` and `Read` the source code to verify the implementation
118
- 2. Classify each business rule:
119
-
120
- | Status | Meaning | Documentation action |
121
- |--------|---------------|---------------------|
122
- | **Confirmed** | Spec and code match | Document as-is |
123
- | **Divergent** | Code does it differently | Document the code (flag the gap) |
124
- | **Not implemented** | Spec but no code | Don't document (flag it) |
125
- | **Not specified** | Code but no spec | Handled in step 3bis |
126
-
127
- ### 3.3 Present the results
128
-
129
- ```
130
- Spec vs code verification:
131
-
132
- | Domain | Confirmed rules | Divergent | Not implemented | Not specified |
133
- |---------|------------------|-------------|-----------------|----------------|
134
- | [Domain 1] | [N] | [N] | [N] | [N] |
135
-
136
- The documentation will reflect the **real code**, not the spec.
137
- Gaps are flagged for information.
138
-
139
- Continue? (yes/no)
140
- ```
141
-
142
- **WAIT** for confirmation.
143
-
144
- **If no spec exists:** skip directly to step 3bis.
145
-
146
- ---
147
-
148
- ## Step 3bis: Scan the code for unspecified features
149
-
150
- **MANDATORY**: This step fills in the specs by analyzing the code for uncovered features.
151
-
152
- ### 3bis.1 Identify features in the code
153
-
154
- Launch scan agents in parallel by domain/layer (same pattern as `/devos:init` Phase 2):
155
-
156
- For each domain identified in step 2:
157
-
158
- Run one documentation pass per domain, each with this brief:
159
-
160
- ```
161
- Analyze the source code of domain [domain-name] to extract implemented features.
162
-
163
- SCOPE: [domain paths]
164
-
165
- Extract:
166
- - Business entities, attributes, relations
167
- - Services and their responsibilities
168
- - Business rules (validations, conditions, constraints)
169
- - API endpoints / events
170
- - Behaviors extracted from tests
171
-
172
- Ignore features already covered by specs: [list of confirmed features]
173
-
174
- Produce a structured report of UNSPECIFIED features found in the code.
175
- ```
176
-
177
- ### 3bis.2 Consolidate code-only features
178
-
179
- Group features found in the code but absent from the specs:
180
-
181
- ```
182
- Features found in the code (no spec):
183
-
184
- | # | Feature | Domain | Source (files) | Description |
185
- |---|---------------|---------|-------------------|-------------|
186
- | 1 | [name] | [domain] | [path] | [description extracted from code] |
187
- | 2 | [name] | [domain] | [path] | [description] |
188
-
189
- These features will be added to the documentation.
190
- Adjust the domain grouping? (yes/no/modify)
191
- ```
192
-
193
- **WAIT** for validation of the classification.
194
-
195
- ---
196
-
197
- ## Step 4: Retro-documentation plan
198
-
199
- ### 4.1 Generate the writing plan
200
-
201
- For each domain, list the files to create with their sources (specs AND/OR code):
202
-
203
- ```
204
- Retro-documentation plan:
205
-
206
- Total: [N] files to create across [M] domains
207
-
208
- Sources:
209
- - [X] features from specs (confirmed in code)
210
- - [Y] features from code only (no spec)
211
-
212
- | # | File | Domain | Sources | Agent |
213
- |---|---------|---------|---------|-------|
214
- | 1 | /${DOC_DIR}/[dom]/[f].md | [Domain 1] | spec-a + code | Agent 1 |
215
- | 2 | /${DOC_DIR}/[dom]/[f].md | [Domain 1] | code only | Agent 1 |
216
- | 3 | /${DOC_DIR}/[dom]/[f].md | [Domain 2] | spec-d, spec-e + code | Agent 2 |
217
- ...
218
-
219
- Agents: [N] documentation agents in parallel
220
- Partition: strict (no file overlap between agents)
221
-
222
- Validate this plan before launching? (yes/no/modify)
223
- ```
224
-
225
- **Validation MANDATORY** before continuing. Don't launch the agents without explicit agreement.
226
-
227
- ---
228
-
229
- ## Step 5: Parallel writing
230
-
231
- ### Per-domain mode
232
-
233
- For each partition, run a pass with `${CLAUDE_PLUGIN_ROOT}/workflows/doc/doc-writer.md` as its brief:
234
-
235
- **Agent N:**
236
- ```
237
- SCOPE:
238
- - /${DOC_DIR}/[domain]/[file1].md (create)
239
- - /${DOC_DIR}/[domain]/[file2].md (create)
240
-
241
- SOURCES:
242
- - spec: devos/specs/[spec-a]/spec-functional.md (if available)
243
- - spec: devos/specs/[spec-b]/spec-functional.md (if available)
244
- - code: [domain source files]
245
- - verification: [spec vs code confrontation results from step 3]
246
- - code_features: [code-only features from step 3bis]
247
-
248
- RULE: The documentation reflects the REAL CODE. Specs provide context but the code prevails on gaps.
249
-
250
- PLAN: devos/product/documentation-plan.md
251
- MAPPING: devos/product/documentation-mapping.md
252
- ```
253
-
254
- Launch all agents in **parallel** (`run_in_background: true`).
255
-
256
- **WAIT** for all agents to complete.
257
-
258
- ### Post-writing check
259
-
260
- 1. For each agent, check the report (SUCCESS/CONFLICTS/OUT_OF_SCOPE)
261
- 2. If out-of-scope diffs are proposed: apply them manually or route them to a follow-up pass
262
- 3. If conflicts are detected: present to the user for resolution
263
-
264
- ---
265
-
266
- ## Step 6: Update plan and mapping
267
-
268
- ### 6.1 Update the plan
269
-
270
- If new domains were created:
271
- 1. `Read devos/product/documentation-plan.md`
272
- 2. Add the new domains
273
- 3. `Write` the updated plan
274
-
275
- ### 6.2 Update the mapping
276
-
277
- 1. `Read devos/product/documentation-mapping.md`
278
- 2. Add all new mapping rows
279
- 3. Update `Coverage` and `Last updated` in Metadata
280
- 4. Clear the `Unmapped Specs` section for processed specs
281
- 5. `Write` the updated mapping
282
-
283
- ---
284
-
285
- ## Step 7: Summary
286
-
287
- ```
288
- Retro-documentation complete!
289
-
290
- Sources:
291
- - Specs processed: [N] (or "none, documentation entirely based on code")
292
- - Code-only features: [M]
293
- - Spec/code gaps: [K] (divergences documented per the code)
294
-
295
- Files created: [total]
296
- Domains documented: [N]
297
- Agents used: [N]
298
-
299
- Plan: devos/product/documentation-plan.md (updated)
300
- Mapping: devos/product/documentation-mapping.md (updated)
301
- Documentation: /${DOC_DIR}/ ([total] files)
302
-
303
- Next step: /devos:docs status to check coverage
304
- ```
@@ -1,58 +0,0 @@
1
- # Template: Library / Package
2
-
3
- > Documentation template for libraries and packages (npm, pip, gem, etc.).
4
- > The sections below are tailored to this project type.
5
-
6
- ---
7
-
8
- ## [Functional domain name]
9
-
10
- ### Overview
11
- <!-- Domain description and its role in the library -->
12
-
13
- ### Public API
14
-
15
- #### `[functionName(params)]`
16
- - **Description:** <!-- Function purpose -->
17
- - **Parameters:**
18
-
19
- | Name | Type | Required | Description |
20
- |------|------|----------|-------------|
21
-
22
- - **Returns:** <!-- Return type and description -->
23
- - **Throws:** <!-- Possible errors -->
24
-
25
- **Example:**
26
- ```typescript
27
- // Usage example
28
- ```
29
-
30
- ### Types and interfaces
31
- <!-- Exported types, public interfaces -->
32
-
33
- ```typescript
34
- interface ExampleType {
35
- // ...
36
- }
37
- ```
38
-
39
- ### Configuration
40
- <!-- Configuration options, defaults -->
41
-
42
- | Option | Type | Default | Description |
43
- |--------|------|---------|-------------|
44
-
45
- ### Compatibility
46
- <!-- Supported versions, environments, browsers -->
47
-
48
- | Environment | Minimum version |
49
- |-------------|-----------------|
50
-
51
- ### Business rules
52
- <!-- Business rules applicable to this domain -->
53
-
54
- ### Integration examples
55
- <!-- Common use cases with code -->
56
-
57
- ### Migration
58
- <!-- Migration guide between major versions -->
@@ -1,61 +0,0 @@
1
- # Template: Service (API, worker, app)
2
-
3
- > Documentation template for anything that runs: REST/GraphQL APIs, workers, frontends, CLIs, mobile apps. Drop the sections that do not apply and add project-specific ones.
4
- > The sections below are adapted to the specifics of this project type.
5
-
6
- ---
7
-
8
- ## [Functional domain name]
9
-
10
- ### Overview
11
- <!-- Description of the domain and its role in the product -->
12
-
13
- ### Endpoints
14
-
15
- #### [Method] [Route]
16
- - **Description:** <!-- Purpose of the endpoint -->
17
- - **Authentication:** <!-- Type of auth required -->
18
- - **Parameters:**
19
-
20
- | Name | Type | Required | Description |
21
- |-----|------|--------|-------------|
22
-
23
- - **Request body:**
24
-
25
- ```json
26
- {}
27
- ```
28
-
29
- - **Response (success):**
30
-
31
- ```json
32
- {}
33
- ```
34
-
35
- - **Error codes:**
36
-
37
- | Code | Meaning | Detail |
38
- |------|--------------|--------|
39
-
40
- ### Data schemas
41
-
42
- #### [Entity name]
43
- <!-- Description of the entity and its attributes -->
44
-
45
- | Field | Type | Description | Constraints |
46
- |-------|------|-------------|-------------|
47
-
48
- ### Business rules
49
- <!-- Business rules applicable to this domain -->
50
-
51
- ### Authentication and authorization
52
- <!-- Roles, permissions, access restrictions -->
53
-
54
- ### Error handling
55
- <!-- Error handling strategy, codes, messages -->
56
-
57
- ### Pagination and filters
58
- <!-- Pagination parameters, available filters -->
59
-
60
- ### Webhooks / Events
61
- <!-- Emitted events, payload format -->
@@ -1,194 +0,0 @@
1
- # Workflow: Update Documentation
2
-
3
- **Goal:** Update the consolidated documentation after a spec has been implemented and tested. The documentation reflects the **real code** (not just the spec): business rules are verified in the implementation.
4
-
5
- **Input:** Implemented spec (targeted mode) or scan of all specs (global mode) + source code
6
-
7
- **Output:** Updated documentation (based on the real code), updated mapping
8
-
9
- ---
10
-
11
- ## Step 1: Determine the mode
12
-
13
- ### Targeted mode (spec given)
14
-
15
- Variable `SPEC_NAME` = name of the given spec.
16
-
17
- 1. Check that `devos/specs/${SPEC_NAME}/verifications/verification.md` exists (spec implemented)
18
- 2. If not: error, the spec must be implemented before updating the documentation
19
-
20
- ### Global mode (no spec)
21
-
22
- 1. `Glob devos/specs/*/verifications/verification.md`: implemented specs
23
- 2. Cross-reference with the `Source Specs` column of `documentation-mapping.md`: specs already documented
24
- 3. Specs to document = implemented but not yet in the mapping
25
-
26
- **If more than 2 specs are behind:**
27
-
28
- ```
29
- ⚠️ [N] specs are behind on documentation.
30
-
31
- Specs to document:
32
- 1. [spec-1]
33
- 2. [spec-2]
34
-
35
- Recommendation: use /devos:docs backfill for a global catch-up.
36
- Continue with /devos:docs update? (yes/no)
37
- ```
38
-
39
- **WAIT** for your response.
40
-
41
- ---
42
-
43
- ## Step 2: Read context
44
-
45
- ### 2.1 Plan and mapping
46
-
47
- 1. `Read devos/product/documentation-plan.md`
48
- 2. `Read devos/product/documentation-mapping.md`
49
-
50
- If the plan doesn't exist:
51
- ```
52
- ❌ No documentation plan found.
53
-
54
- Run first: /devos:docs init
55
- ```
56
- **STOP**
57
-
58
- ### 2.2 Source spec(s)
59
-
60
- For each spec to document:
61
- 1. `Read devos/specs/${SPEC_NAME}/spec-functional.md`
62
- 2. `Read devos/specs/${SPEC_NAME}/spec.md` (technical spec if it exists)
63
-
64
- ### 2.3 Source code
65
-
66
- For each spec, identify the relevant code files:
67
- 1. If `spec.md` exists: extract the files referenced in the implementation plan
68
- 2. Otherwise: `Grep` for the spec's entity/service names in the source code
69
-
70
- ### 2.4 Configuration
71
-
72
- ```bash
73
- ```
74
-
75
- **Variable:** `DOC_DIR` = `documentation` (fixed default; change it by editing this workflow)
76
-
77
- ---
78
-
79
- ## Step 3: Code verification (mandatory)
80
-
81
- ### 3.1 Spec vs code confrontation
82
-
83
- For each business rule / feature of the spec, look for the matching implementation (`Grep`, `Read`) and classify:
84
-
85
- | Status | Meaning |
86
- |--------|---------|
87
- | **Confirmed** | Spec and code match |
88
- | **Divergent** | Code implements it differently from the spec |
89
- | **Not implemented** | Spec feature absent from the code |
90
- | **Not specified** | Code feature absent from the spec |
91
-
92
- ### 3.2 Present the gaps
93
-
94
- ```
95
- Spec vs code verification for: [spec-name]
96
-
97
- | Business rule | Spec | Code | Status |
98
- |---------------|------|------|--------|
99
- | [convention 1] | [spec description] | [code description] | Confirmed |
100
- | [convention 2] | [spec description] | [different behavior] | Divergent |
101
-
102
- The documentation will reflect the **real code**.
103
- Gaps are flagged for information.
104
-
105
- Validate? (yes/no)
106
- ```
107
-
108
- **WAIT** for validation.
109
-
110
- **Principle:** the documentation describes what the product **actually does**, not what it should do.
111
-
112
- ---
113
-
114
- ## Step 4: Update plan estimation
115
-
116
- 1. Analyze **confirmed and divergent** features (not the unimplemented ones), plus **unspecified** features found in the code
117
- 2. Cross-reference with `documentation-plan.md` (domains) and `documentation-mapping.md` (existing files)
118
- 3. Determine per file: `create` or `update`
119
-
120
- ```
121
- Update plan for: [spec-name]
122
-
123
- Impacted files:
124
- | # | File | Action | Nature of changes |
125
- |---|------|--------|-------------------|
126
- | 1 | /${DOC_DIR}/[domain]/[file].md | update | Added section [X] |
127
-
128
- Validate this plan? (yes/no/modify)
129
- ```
130
-
131
- **WAIT** for validation.
132
-
133
- ---
134
-
135
- ## Step 5: Documentation pass
136
-
137
- Run one documentation pass with `${CLAUDE_PLUGIN_ROOT}/workflows/doc/doc-writer.md` as its brief:
138
-
139
- ```
140
- SCOPE:
141
- - /${DOC_DIR}/[domain]/[file1].md (update)
142
- - /${DOC_DIR}/[domain]/[file2].md (create)
143
-
144
- SOURCES:
145
- - spec: devos/specs/${SPEC_NAME}/spec-functional.md
146
- - code: [relevant code files from step 2.3]
147
- - verification: [spec vs code results from step 3]
148
-
149
- PLAN: devos/product/documentation-plan.md
150
- MAPPING: devos/product/documentation-mapping.md
151
- ```
152
-
153
- **WAIT** for that pass to complete.
154
-
155
- ---
156
-
157
- ## Step 6: Diff validation
158
-
159
- For each modified/created file, present a summary of the changes and ask:
160
-
161
- ```
162
- Changes for: [file]
163
-
164
- [Summary]
165
-
166
- Apply? (yes/no/modify)
167
- ```
168
-
169
- **WAIT** for validation per file. If declined: revert that file.
170
-
171
- ---
172
-
173
- ## Step 7: Mapping update
174
-
175
- 1. `Read devos/product/documentation-mapping.md`
176
- 2. Update the mapping table: new rows for created files, `Last Sync`/`Status` for modified files, source spec in `Source Specs`, `Coverage` in Metadata
177
- 3. `Write` the updated mapping
178
- 4. Remove the spec from `Unmapped Specs` if present
179
-
180
- ---
181
-
182
- ## Step 8: Summary
183
-
184
- ```
185
- Documentation updated!
186
-
187
- Spec: [spec-name]
188
- Files modified: [N]
189
- Files created: [M]
190
- Mapping: devos/product/documentation-mapping.md (updated)
191
-
192
- [If conflicts detected:]
193
- ⚠️ [N] conflicts detected, see details above
194
- ```