@tduyng/pi-devos 0.0.0-stage → 0.13.6
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 +1398 -0
- package/LICENSE +201 -0
- package/README.md +213 -2
- package/package.json +45 -4
- package/plugins/devos/agents/reader.md +27 -0
- package/plugins/devos/agents/verifier.md +181 -0
- package/plugins/devos/pi/extension/devos.ts +615 -0
- package/plugins/devos/scripts/check-evidence-router.sh +134 -0
- package/plugins/devos/scripts/evidence-router.py +252 -0
- package/plugins/devos/scripts/gates/check-dod-core.sh +283 -0
- package/plugins/devos/scripts/gates/check-dod.sh +38 -0
- package/plugins/devos/scripts/gates/check-handoff.sh +215 -0
- package/plugins/devos/scripts/gates/check-implementation-boundary.sh +99 -0
- package/plugins/devos/scripts/gates/check-port-source.sh +134 -0
- package/plugins/devos/scripts/gates/check-report-locations.sh +148 -0
- package/plugins/devos/scripts/gates/check-scenario-coverage.sh +102 -0
- package/plugins/devos/scripts/gates/gate-check.mjs +204 -0
- package/plugins/devos/scripts/gates/phase-gate.sh +208 -0
- package/plugins/devos/scripts/gates/plan-template-check.py +147 -0
- package/plugins/devos/scripts/gates/run-gate.sh +148 -0
- package/plugins/devos/scripts/gates/spec-template-check.py +165 -0
- package/plugins/devos/scripts/gates/test-gates.sh +4306 -0
- package/plugins/devos/scripts/gates/test-integrity-rubric.sh +152 -0
- package/plugins/devos/scripts/gates/test-phase-gate.sh +116 -0
- package/plugins/devos/skills/absorb/SKILL.md +75 -0
- package/plugins/devos/skills/absorb/references/distill.md +67 -0
- package/plugins/devos/skills/absorb/scripts/check-refs.sh +108 -0
- package/plugins/devos/skills/absorb/scripts/knowledge.py +258 -0
- package/plugins/devos/skills/build/SKILL.md +71 -0
- package/plugins/devos/skills/build/references/advanced-routing.md +19 -0
- package/plugins/devos/skills/build/references/defect.md +17 -0
- package/plugins/devos/skills/build/references/exposure.md +28 -0
- package/plugins/devos/skills/build/references/hard.md +39 -0
- package/plugins/devos/skills/build/references/refactor.md +66 -0
- package/plugins/devos/skills/build/references/routes.md +56 -0
- package/plugins/devos/skills/build/references/scale.md +84 -0
- package/plugins/devos/skills/build/references/spike.md +19 -0
- package/plugins/devos/skills/build/scripts/construct-census.py +204 -0
- package/plugins/devos/skills/build/scripts/dep-order.py +297 -0
- package/plugins/devos/skills/build/scripts/ledger.sh +228 -0
- package/plugins/devos/skills/build/scripts/route.sh +5 -0
- package/plugins/devos/skills/build/scripts/secret-scan.sh +121 -0
- package/plugins/devos/skills/build/scripts/toolchain-preflight.py +302 -0
- package/plugins/devos/skills/design-taste/SKILL.md +55 -0
- package/plugins/devos/skills/design-taste/references/tells.md +85 -0
- package/plugins/devos/skills/design-taste/scripts/slop-scan.py +305 -0
- package/plugins/devos/skills/docs/SKILL.md +22 -0
- package/plugins/devos/skills/docs/references/backfill.md +54 -0
- package/plugins/devos/skills/docs/references/init.md +43 -0
- package/plugins/devos/skills/docs/references/status.md +71 -0
- package/plugins/devos/skills/docs/references/update.md +80 -0
- package/plugins/devos/skills/explain/SKILL.md +45 -0
- package/plugins/devos/skills/explain/references/quiz.md +21 -0
- package/plugins/devos/skills/frame/SKILL.md +71 -0
- package/plugins/devos/skills/frame/references/boundaries.md +53 -0
- package/plugins/devos/skills/frame/references/decompose.md +96 -0
- package/plugins/devos/skills/frame/references/impact.md +43 -0
- package/plugins/devos/skills/frame/references/interrogate.md +68 -0
- package/plugins/devos/skills/frame/scripts/survey.sh +44 -0
- package/plugins/devos/skills/implement/SKILL.md +36 -0
- package/plugins/devos/skills/implement/references/conditional-plan.md +17 -0
- package/plugins/devos/skills/implement/references/debug-loop.md +7 -0
- package/plugins/devos/skills/implement/references/dod.md +32 -0
- package/plugins/devos/skills/implement/references/implement.md +52 -0
- package/plugins/devos/skills/implement/references/manual-gates.md +16 -0
- package/plugins/devos/skills/implement/references/plan.md +160 -0
- package/plugins/devos/skills/implement/references/resume.md +9 -0
- package/plugins/devos/skills/implement/references/scale.md +86 -0
- package/plugins/devos/skills/implement/references/verify-close.md +61 -0
- package/plugins/devos/skills/implement/references/visual-verification.md +7 -0
- package/plugins/devos/skills/implement/scripts/check-converge.sh +147 -0
- package/plugins/devos/skills/implement/scripts/equivalence-check.sh +140 -0
- package/plugins/devos/skills/implement/scripts/manifest-queue.sh +185 -0
- package/plugins/devos/skills/implement/scripts/ops-log.sh +58 -0
- package/plugins/devos/skills/implement/scripts/pilot-consistency.py +173 -0
- package/plugins/devos/skills/implement/scripts/validate-spec.sh +268 -0
- package/plugins/devos/skills/init/SKILL.md +100 -0
- package/plugins/devos/skills/init/references/archetype-sections.md +15 -0
- package/plugins/devos/skills/init/references/context.md +42 -0
- package/plugins/devos/skills/init/references/conventions-template.md +153 -0
- package/plugins/devos/skills/init/references/reverse-engineer.md +3 -0
- package/plugins/devos/skills/init/references/rule-format.md +58 -0
- package/plugins/devos/skills/init/references/shape-model.md +29 -0
- package/plugins/devos/skills/init/scripts/detect-archetype.py +461 -0
- package/plugins/devos/skills/init/scripts/render-rule.py +114 -0
- package/plugins/devos/skills/init/scripts/reverse-engineer.sh +162 -0
- package/plugins/devos/skills/learn/SKILL.md +29 -0
- package/plugins/devos/skills/learn/references/destinations.md +43 -0
- package/plugins/devos/skills/learn/references/scoring.md +26 -0
- package/plugins/devos/skills/product/SKILL.md +40 -0
- package/plugins/devos/skills/product/references/planner.md +54 -0
- package/plugins/devos/skills/review/SKILL.md +77 -0
- package/plugins/devos/skills/review/references/gaps.md +26 -0
- package/plugins/devos/skills/spec/SKILL.md +58 -0
- package/plugins/devos/skills/spec/references/prototype.md +21 -0
- package/plugins/devos/skills/spec/references/question-craft.md +47 -0
- package/plugins/devos/skills/spec/references/roadmap-link.md +5 -0
- package/plugins/devos/skills/spec/references/write-spec.md +143 -0
- package/plugins/devos/skills/spec/scripts/clarify.sh +173 -0
- package/plugins/devos/skills/status/SKILL.md +67 -0
- package/plugins/devos/skills/status/references/cost.md +38 -0
- package/plugins/devos/skills/status/scripts/artifact-budgets.sh +88 -0
- package/plugins/devos/skills/status/scripts/check-requires.py +556 -0
- package/plugins/devos/skills/status/scripts/context-cost.sh +89 -0
- package/plugins/devos/skills/status/scripts/convention-usage.sh +184 -0
- package/plugins/devos/skills/status/scripts/findings-summary.sh +112 -0
- package/plugins/devos/skills/status/scripts/quality-correlation.sh +282 -0
- package/plugins/devos/skills/status/scripts/sizing-calibration.sh +71 -0
- package/plugins/devos/skills/status/scripts/spec-diff.sh +137 -0
- package/plugins/devos/skills/surgical-diff/SKILL.md +23 -0
- package/plugins/devos/skills/test-integrity/SKILL.md +26 -0
- package/plugins/devos/skills/verification-evidence/SKILL.md +17 -0
- package/plugins/devos/workflows/common/backlog-file-structure.md +44 -0
- package/plugins/devos/workflows/common/category-file-structure.md +41 -0
- package/plugins/devos/workflows/common/feature-line-format.md +10 -0
- package/plugins/devos/workflows/common/roadmap-file-structure.md +51 -0
- package/plugins/devos/workflows/common/suggest-categories.md +76 -0
- package/plugins/devos/workflows/common/suggest-milestones.md +92 -0
- package/plugins/devos/workflows/doc/doc-health.md +137 -0
- package/plugins/devos/workflows/doc/doc-writer.md +44 -0
- package/plugins/devos/workflows/doc/init-documentation.md +196 -0
- package/plugins/devos/workflows/doc/retro-documentation.md +304 -0
- package/plugins/devos/workflows/doc/templates/library.md +58 -0
- package/plugins/devos/workflows/doc/templates/service.md +61 -0
- package/plugins/devos/workflows/doc/update-documentation.md +194 -0
- package/plugins/devos/workflows/doc/write-documentation.md +137 -0
- package/plugins/devos/workflows/product/create-product-mission.md +45 -0
- package/plugins/devos/workflows/product/create-product-roadmap.md +106 -0
- package/plugins/devos/workflows/product/create-product-tech-stack.md +19 -0
- package/plugins/devos/workflows/product/gather-product-info.md +25 -0
- package/plugins/devos/workflows/product/resume-detection.md +70 -0
- package/plugins/devos/workflows/product/reverse-backlog.md +118 -0
- package/plugins/devos/workflows/product/reverse-domain-model.md +86 -0
- package/plugins/devos/workflows/product/reverse-product-plan.md +81 -0
- package/plugins/devos/workflows/product/reverse-tech-stack.md +73 -0
- package/plugins/devos/workflows/product/scan-deep.md +113 -0
- package/plugins/devos/workflows/product/scan-git.md +122 -0
- package/plugins/devos/workflows/product/scan-light.md +154 -0
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
You are the **Documentation Writer** role for DevOS.
|
|
2
|
+
|
|
3
|
+
## Mission
|
|
4
|
+
|
|
5
|
+
Write and update functional documentation files within a **strict scope** defined by the orchestrator. You produce clean, framework-agnostic markdown documentation organized by functional domain.
|
|
6
|
+
|
|
7
|
+
## CRITICAL: Scope Enforcement
|
|
8
|
+
|
|
9
|
+
| Rule | Detail |
|
|
10
|
+
|------|--------|
|
|
11
|
+
| **Scope** | Only modify files explicitly listed in your assignment |
|
|
12
|
+
| **Cap** | Never process more files than the configured cap (default: 5) |
|
|
13
|
+
| **Out-of-scope changes** | Propose as diff to the orchestrator, never apply directly |
|
|
14
|
+
| **No metadata** | Documentation files are 100% clean, no DevOS markers, no frontmatter, no framework references |
|
|
15
|
+
|
|
16
|
+
## Input Format
|
|
17
|
+
|
|
18
|
+
The orchestrator provides:
|
|
19
|
+
|
|
20
|
+
```
|
|
21
|
+
SCOPE:
|
|
22
|
+
- path/to/file1.md (create|update)
|
|
23
|
+
- path/to/file2.md (create|update)
|
|
24
|
+
|
|
25
|
+
SOURCES:
|
|
26
|
+
- spec: devos/specs/[spec-name]/spec-functional.md
|
|
27
|
+
- code: [relevant source files]
|
|
28
|
+
|
|
29
|
+
PLAN: devos/product/documentation-plan.md
|
|
30
|
+
MAPPING: devos/product/documentation-mapping.md
|
|
31
|
+
TEMPLATES_DIR: [framework templates path]
|
|
32
|
+
PROJECT_TEMPLATES_DIR: [project override path, if exists]
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Token Efficiency
|
|
36
|
+
|
|
37
|
+
| Scenario | Report length |
|
|
38
|
+
|----------|---------------|
|
|
39
|
+
| CLEAN (all files written) | 5 lines |
|
|
40
|
+
| ISSUES (conflicts/questions) | 30 lines max |
|
|
41
|
+
|
|
42
|
+
## Workflow
|
|
43
|
+
|
|
44
|
+
Read and follow `${CLAUDE_PLUGIN_ROOT}/workflows/doc/write-documentation.md`.
|
|
@@ -0,0 +1,196 @@
|
|
|
1
|
+
# Workflow: Init Documentation
|
|
2
|
+
|
|
3
|
+
**Goal:** Initialize consolidated functional documentation for a project. Generate the documentation plan, the initial mapping, and markdown skeletons.
|
|
4
|
+
|
|
5
|
+
**Input:** Product files (`mission.md`, `roadmap.md`, backlog), finalized specs, source code
|
|
6
|
+
|
|
7
|
+
**Output:** `documentation-plan.md`, `documentation-mapping.md`, skeletons in `/${doc_dir}/`
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Step 1: Analyze the existing state
|
|
12
|
+
|
|
13
|
+
### Batch 1: Product files (parallel)
|
|
14
|
+
|
|
15
|
+
Read in parallel:
|
|
16
|
+
|
|
17
|
+
1. `Read devos/product/mission.md`
|
|
18
|
+
2. `Read devos/product/roadmap.md`
|
|
19
|
+
3. `Read devos/product/tech-stack.md`
|
|
20
|
+
4. `Glob devos/product/backlog/*.md` then `Read` each file
|
|
21
|
+
|
|
22
|
+
### Batch 2: Finalized specs (parallel)
|
|
23
|
+
|
|
24
|
+
1. `Glob devos/specs/*/spec-functional.md`
|
|
25
|
+
2. For each spec found, `Read` the file
|
|
26
|
+
3. For each spec, check `verifications/verification.md` exists to identify implemented specs
|
|
27
|
+
|
|
28
|
+
**Extract:**
|
|
29
|
+
- List of implemented features
|
|
30
|
+
- Identified functional domains (groups of related specs)
|
|
31
|
+
- Unimplemented specs (exclude from documentation)
|
|
32
|
+
|
|
33
|
+
### Batch 3: Source code (sampling)
|
|
34
|
+
|
|
35
|
+
1. `Glob src/**/*.{ts,tsx,js,jsx,py,go,java,swift,kt}` (adapt per tech-stack)
|
|
36
|
+
2. Read a representative sample (max 10 files) to check consistency with the specs
|
|
37
|
+
3. Identify the project structure (main folders, patterns)
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## Step 2: Read configuration
|
|
42
|
+
|
|
43
|
+
Read the configured documentation directory:
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
**Variable:** `DOC_DIR` = `documentation` (fixed default; change it by editing this workflow)
|
|
49
|
+
|
|
50
|
+
Check if project templates exist:
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
ls ${DOC_DIR}/.templates/ 2>/dev/null
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## Step 3: Hybrid Q&A (mode C)
|
|
59
|
+
|
|
60
|
+
### 3.1 Propose a documentation plan
|
|
61
|
+
|
|
62
|
+
Based on the analysis, propose a plan organized by **functional domain**:
|
|
63
|
+
|
|
64
|
+
```
|
|
65
|
+
Proposed documentation plan:
|
|
66
|
+
|
|
67
|
+
Identified domains:
|
|
68
|
+
1. [Domain 1]: [description, related specs]
|
|
69
|
+
- [subsection 1]
|
|
70
|
+
- [subsection 2]
|
|
71
|
+
2. [Domain 2]: [description, related specs]
|
|
72
|
+
...
|
|
73
|
+
|
|
74
|
+
Architecture/ADR section: [Proposed, include? yes/no]
|
|
75
|
+
|
|
76
|
+
Proposed structure:
|
|
77
|
+
/${DOC_DIR}/
|
|
78
|
+
[domain-1]/
|
|
79
|
+
[file-1].md
|
|
80
|
+
[file-2].md
|
|
81
|
+
[domain-2]/
|
|
82
|
+
[file-1].md
|
|
83
|
+
...
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
### 3.2 Targeted questions
|
|
87
|
+
|
|
88
|
+
Use `AskUserQuestion` to ask only about areas of ambiguity:
|
|
89
|
+
|
|
90
|
+
- Functional domains to add or remove
|
|
91
|
+
- Grouping of specs into domains
|
|
92
|
+
- Whether to include the architecture/ADR section
|
|
93
|
+
- Desired level of granularity
|
|
94
|
+
|
|
95
|
+
**Max 4 questions per call. 0 questions if the plan is clear.**
|
|
96
|
+
|
|
97
|
+
### 3.3 Plan revision
|
|
98
|
+
|
|
99
|
+
If you ask to rethink the plan: regenerate from step 3.1.
|
|
100
|
+
|
|
101
|
+
**WAIT** for explicit plan approval before continuing.
|
|
102
|
+
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
## Step 4: Template selection
|
|
106
|
+
|
|
107
|
+
1. Check project templates: `Glob ${DOC_DIR}/.templates/*.md`: if found, use those (project takes priority).
|
|
108
|
+
2. Otherwise pick the closer of the two framework templates and adapt its sections to the project type (drop what doesn't apply, add what's missing):
|
|
109
|
+
- `${CLAUDE_PLUGIN_ROOT}/workflows/doc/templates/library.md`: packages consumed as code (npm/pip/gem)
|
|
110
|
+
- `${CLAUDE_PLUGIN_ROOT}/workflows/doc/templates/service.md`: everything that runs (API, frontend, worker, CLI, mobile)
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## Step 5: Generate artifacts
|
|
115
|
+
|
|
116
|
+
### 5.1 Documentation plan
|
|
117
|
+
|
|
118
|
+
Write `devos/product/documentation-plan.md`:
|
|
119
|
+
|
|
120
|
+
```markdown
|
|
121
|
+
# Documentation Plan
|
|
122
|
+
|
|
123
|
+
> Generated by DevOS on [date]
|
|
124
|
+
> Type: [type]
|
|
125
|
+
|
|
126
|
+
## Overview
|
|
127
|
+
[Description of the chosen organization]
|
|
128
|
+
|
|
129
|
+
## Functional domains
|
|
130
|
+
|
|
131
|
+
### [Domain 1]
|
|
132
|
+
- **Description:** [description]
|
|
133
|
+
- **Files:**
|
|
134
|
+
- `/${DOC_DIR}/[domain-1]/[file].md`: [description]
|
|
135
|
+
|
|
136
|
+
### [Domain N]
|
|
137
|
+
...
|
|
138
|
+
|
|
139
|
+
## Architecture section
|
|
140
|
+
[If approved by the user]
|
|
141
|
+
- `/${DOC_DIR}/architecture/overview.md`: Architecture overview
|
|
142
|
+
- `/${DOC_DIR}/architecture/adr/`: Architecture Decision Records
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
### 5.2 Initial mapping
|
|
146
|
+
|
|
147
|
+
Write `devos/product/documentation-mapping.md`:
|
|
148
|
+
|
|
149
|
+
```markdown
|
|
150
|
+
# Documentation Mapping
|
|
151
|
+
|
|
152
|
+
> Auto-generated by DevOS. Do not edit manually.
|
|
153
|
+
|
|
154
|
+
## Metadata
|
|
155
|
+
- **Last updated:** [ISO timestamp]
|
|
156
|
+
- **Coverage:** 0/[N] specs documented (0%)
|
|
157
|
+
- **Generator:** devos v[version]
|
|
158
|
+
|
|
159
|
+
## Mapping
|
|
160
|
+
|
|
161
|
+
| Documentation File | Domain | Source Specs | Last Sync | Status |
|
|
162
|
+
|---|---|---|---|---|
|
|
163
|
+
| `/${DOC_DIR}/[domain]/[file].md` | [Domain] | n/a | n/a | Skeleton |
|
|
164
|
+
|
|
165
|
+
## Unmapped Specs
|
|
166
|
+
[List of existing specs not yet attached]
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
### 5.3 Markdown skeletons
|
|
170
|
+
|
|
171
|
+
For each file in the plan:
|
|
172
|
+
|
|
173
|
+
1. Create the directory if needed: `mkdir -p ${DOC_DIR}/[domain]/`
|
|
174
|
+
2. Generate the skeleton with the matching template:
|
|
175
|
+
- Headings matching the project type's template
|
|
176
|
+
- Descriptive placeholders (`<!-- TODO: Describe the authentication flows -->`)
|
|
177
|
+
- **No DevOS metadata**: 100% clean file
|
|
178
|
+
|
|
179
|
+
---
|
|
180
|
+
|
|
181
|
+
## Step 6: Summary
|
|
182
|
+
|
|
183
|
+
```
|
|
184
|
+
Documentation initialized!
|
|
185
|
+
|
|
186
|
+
Plan: devos/product/documentation-plan.md
|
|
187
|
+
Mapping: devos/product/documentation-mapping.md
|
|
188
|
+
Skeletons: ${DOC_DIR}/ ([N] files generated)
|
|
189
|
+
|
|
190
|
+
Domains:
|
|
191
|
+
- [Domain 1] ([N] files)
|
|
192
|
+
- [Domain 2] ([N] files)
|
|
193
|
+
[- Architecture/ADR (if included)]
|
|
194
|
+
|
|
195
|
+
Next step: /devos:docs update <spec> to populate the documentation
|
|
196
|
+
```
|
|
@@ -0,0 +1,304 @@
|
|
|
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
|
+
```
|
|
@@ -0,0 +1,58 @@
|
|
|
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 -->
|
|
@@ -0,0 +1,61 @@
|
|
|
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 -->
|