@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.
- package/CHANGELOG.md +23 -0
- package/README.md +26 -33
- package/package.json +1 -2
- package/plugins/devos/agents/verifier.md +4 -30
- package/plugins/devos/pi/extension/devos.ts +16 -26
- package/plugins/devos/scripts/check-evidence-router.sh +7 -1
- package/plugins/devos/scripts/evidence-router.py +5 -3
- package/plugins/devos/scripts/gates/check-dod-core.sh +5 -3
- package/plugins/devos/scripts/gates/check-port-source.sh +1 -1
- package/plugins/devos/scripts/gates/check-scenario-coverage.sh +10 -8
- package/plugins/devos/scripts/gates/phase-gate.sh +6 -6
- package/plugins/devos/scripts/gates/plan-template-check.py +6 -12
- package/plugins/devos/scripts/gates/spec-contract.sh +19 -0
- package/plugins/devos/scripts/gates/spec-template-check.py +8 -21
- package/plugins/devos/scripts/gates/suite/01-dod.sh +485 -0
- package/plugins/devos/scripts/gates/suite/02-integrity.sh +310 -0
- package/plugins/devos/scripts/gates/suite/03-archetype.sh +255 -0
- package/plugins/devos/scripts/gates/suite/04-spec-validator.sh +183 -0
- package/plugins/devos/scripts/gates/suite/05-requires.sh +360 -0
- package/plugins/devos/scripts/gates/suite/06-clarify-adapters.sh +435 -0
- package/plugins/devos/scripts/gates/suite/07-lint-evals.sh +350 -0
- package/plugins/devos/scripts/gates/suite/08-converge.sh +591 -0
- package/plugins/devos/scripts/gates/suite/09-quality.sh +516 -0
- package/plugins/devos/scripts/gates/suite/10-eval-harness.sh +679 -0
- package/plugins/devos/scripts/gates/test-gates.sh +23 -4253
- package/plugins/devos/scripts/gates/test-integrity-rubric.sh +1 -1
- package/plugins/devos/scripts/gates/test-phase-gate.sh +5 -5
- package/plugins/devos/skills/build/SKILL.md +3 -3
- package/plugins/devos/skills/build/references/refactor.md +1 -1
- package/plugins/devos/skills/build/references/routes.md +4 -4
- package/plugins/devos/skills/frame/SKILL.md +22 -39
- package/plugins/devos/skills/frame/references/template.md +115 -0
- package/plugins/devos/skills/implement/SKILL.md +4 -4
- package/plugins/devos/skills/implement/references/dod.md +6 -1
- package/plugins/devos/skills/implement/references/implement.md +3 -1
- package/plugins/devos/skills/implement/references/plan.md +9 -27
- package/plugins/devos/skills/implement/references/resume.md +1 -1
- package/plugins/devos/skills/implement/references/verify-close.md +4 -3
- package/plugins/devos/skills/implement/scripts/ops-log.sh +2 -2
- package/plugins/devos/skills/implement/scripts/validate-spec.sh +17 -65
- package/plugins/devos/skills/init/references/context.md +1 -1
- package/plugins/devos/skills/review/SKILL.md +24 -47
- package/plugins/devos/skills/review/references/comments.md +13 -0
- package/plugins/devos/skills/review/references/reviewer.md +124 -0
- package/plugins/devos/skills/review/references/routing.md +35 -0
- package/plugins/devos/skills/review/scripts/__pycache__/prepare.cpython-313.pyc +0 -0
- package/plugins/devos/skills/review/scripts/prepare.py +763 -0
- package/plugins/devos/skills/spec/SKILL.md +5 -6
- package/plugins/devos/skills/spec/references/write-spec.md +36 -51
- package/plugins/devos/skills/spec/scripts/clarify.sh +4 -4
- package/plugins/devos/skills/status/SKILL.md +4 -4
- package/plugins/devos/skills/status/scripts/check-requires.py +4 -4
- package/plugins/devos/skills/status/scripts/convention-usage.sh +1 -1
- package/plugins/devos/skills/status/scripts/quality-correlation.sh +2 -25
- package/plugins/devos/scripts/gates/check-handoff.sh +0 -215
- package/plugins/devos/skills/design-taste/SKILL.md +0 -55
- package/plugins/devos/skills/design-taste/references/tells.md +0 -85
- package/plugins/devos/skills/design-taste/scripts/slop-scan.py +0 -305
- package/plugins/devos/skills/docs/SKILL.md +0 -22
- package/plugins/devos/skills/docs/references/backfill.md +0 -54
- package/plugins/devos/skills/docs/references/init.md +0 -43
- package/plugins/devos/skills/docs/references/status.md +0 -71
- package/plugins/devos/skills/docs/references/update.md +0 -80
- package/plugins/devos/skills/explain/SKILL.md +0 -45
- package/plugins/devos/skills/explain/references/quiz.md +0 -21
- package/plugins/devos/skills/frame/references/boundaries.md +0 -53
- package/plugins/devos/skills/frame/references/decompose.md +0 -96
- package/plugins/devos/skills/frame/references/impact.md +0 -43
- package/plugins/devos/skills/frame/references/interrogate.md +0 -68
- package/plugins/devos/skills/product/SKILL.md +0 -40
- package/plugins/devos/skills/product/references/planner.md +0 -54
- package/plugins/devos/skills/surgical-diff/SKILL.md +0 -23
- package/plugins/devos/skills/test-integrity/SKILL.md +0 -26
- package/plugins/devos/skills/verification-evidence/SKILL.md +0 -17
- package/plugins/devos/workflows/common/backlog-file-structure.md +0 -44
- package/plugins/devos/workflows/common/category-file-structure.md +0 -41
- package/plugins/devos/workflows/common/feature-line-format.md +0 -10
- package/plugins/devos/workflows/common/roadmap-file-structure.md +0 -51
- package/plugins/devos/workflows/common/suggest-categories.md +0 -76
- package/plugins/devos/workflows/common/suggest-milestones.md +0 -92
- package/plugins/devos/workflows/doc/doc-health.md +0 -137
- package/plugins/devos/workflows/doc/doc-writer.md +0 -44
- package/plugins/devos/workflows/doc/init-documentation.md +0 -196
- package/plugins/devos/workflows/doc/retro-documentation.md +0 -304
- package/plugins/devos/workflows/doc/templates/library.md +0 -58
- package/plugins/devos/workflows/doc/templates/service.md +0 -61
- package/plugins/devos/workflows/doc/update-documentation.md +0 -194
- package/plugins/devos/workflows/doc/write-documentation.md +0 -137
- package/plugins/devos/workflows/product/create-product-mission.md +0 -45
- package/plugins/devos/workflows/product/create-product-roadmap.md +0 -106
- package/plugins/devos/workflows/product/create-product-tech-stack.md +0 -19
- package/plugins/devos/workflows/product/gather-product-info.md +0 -25
- package/plugins/devos/workflows/product/resume-detection.md +0 -70
- package/plugins/devos/workflows/product/reverse-backlog.md +0 -118
- package/plugins/devos/workflows/product/reverse-domain-model.md +0 -86
- package/plugins/devos/workflows/product/reverse-product-plan.md +0 -81
- package/plugins/devos/workflows/product/reverse-tech-stack.md +0 -73
- package/plugins/devos/workflows/product/scan-deep.md +0 -113
- package/plugins/devos/workflows/product/scan-git.md +0 -122
- 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
|
-
```
|