@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.
Files changed (138) hide show
  1. package/CHANGELOG.md +1398 -0
  2. package/LICENSE +201 -0
  3. package/README.md +213 -2
  4. package/package.json +45 -4
  5. package/plugins/devos/agents/reader.md +27 -0
  6. package/plugins/devos/agents/verifier.md +181 -0
  7. package/plugins/devos/pi/extension/devos.ts +615 -0
  8. package/plugins/devos/scripts/check-evidence-router.sh +134 -0
  9. package/plugins/devos/scripts/evidence-router.py +252 -0
  10. package/plugins/devos/scripts/gates/check-dod-core.sh +283 -0
  11. package/plugins/devos/scripts/gates/check-dod.sh +38 -0
  12. package/plugins/devos/scripts/gates/check-handoff.sh +215 -0
  13. package/plugins/devos/scripts/gates/check-implementation-boundary.sh +99 -0
  14. package/plugins/devos/scripts/gates/check-port-source.sh +134 -0
  15. package/plugins/devos/scripts/gates/check-report-locations.sh +148 -0
  16. package/plugins/devos/scripts/gates/check-scenario-coverage.sh +102 -0
  17. package/plugins/devos/scripts/gates/gate-check.mjs +204 -0
  18. package/plugins/devos/scripts/gates/phase-gate.sh +208 -0
  19. package/plugins/devos/scripts/gates/plan-template-check.py +147 -0
  20. package/plugins/devos/scripts/gates/run-gate.sh +148 -0
  21. package/plugins/devos/scripts/gates/spec-template-check.py +165 -0
  22. package/plugins/devos/scripts/gates/test-gates.sh +4306 -0
  23. package/plugins/devos/scripts/gates/test-integrity-rubric.sh +152 -0
  24. package/plugins/devos/scripts/gates/test-phase-gate.sh +116 -0
  25. package/plugins/devos/skills/absorb/SKILL.md +75 -0
  26. package/plugins/devos/skills/absorb/references/distill.md +67 -0
  27. package/plugins/devos/skills/absorb/scripts/check-refs.sh +108 -0
  28. package/plugins/devos/skills/absorb/scripts/knowledge.py +258 -0
  29. package/plugins/devos/skills/build/SKILL.md +71 -0
  30. package/plugins/devos/skills/build/references/advanced-routing.md +19 -0
  31. package/plugins/devos/skills/build/references/defect.md +17 -0
  32. package/plugins/devos/skills/build/references/exposure.md +28 -0
  33. package/plugins/devos/skills/build/references/hard.md +39 -0
  34. package/plugins/devos/skills/build/references/refactor.md +66 -0
  35. package/plugins/devos/skills/build/references/routes.md +56 -0
  36. package/plugins/devos/skills/build/references/scale.md +84 -0
  37. package/plugins/devos/skills/build/references/spike.md +19 -0
  38. package/plugins/devos/skills/build/scripts/construct-census.py +204 -0
  39. package/plugins/devos/skills/build/scripts/dep-order.py +297 -0
  40. package/plugins/devos/skills/build/scripts/ledger.sh +228 -0
  41. package/plugins/devos/skills/build/scripts/route.sh +5 -0
  42. package/plugins/devos/skills/build/scripts/secret-scan.sh +121 -0
  43. package/plugins/devos/skills/build/scripts/toolchain-preflight.py +302 -0
  44. package/plugins/devos/skills/design-taste/SKILL.md +55 -0
  45. package/plugins/devos/skills/design-taste/references/tells.md +85 -0
  46. package/plugins/devos/skills/design-taste/scripts/slop-scan.py +305 -0
  47. package/plugins/devos/skills/docs/SKILL.md +22 -0
  48. package/plugins/devos/skills/docs/references/backfill.md +54 -0
  49. package/plugins/devos/skills/docs/references/init.md +43 -0
  50. package/plugins/devos/skills/docs/references/status.md +71 -0
  51. package/plugins/devos/skills/docs/references/update.md +80 -0
  52. package/plugins/devos/skills/explain/SKILL.md +45 -0
  53. package/plugins/devos/skills/explain/references/quiz.md +21 -0
  54. package/plugins/devos/skills/frame/SKILL.md +71 -0
  55. package/plugins/devos/skills/frame/references/boundaries.md +53 -0
  56. package/plugins/devos/skills/frame/references/decompose.md +96 -0
  57. package/plugins/devos/skills/frame/references/impact.md +43 -0
  58. package/plugins/devos/skills/frame/references/interrogate.md +68 -0
  59. package/plugins/devos/skills/frame/scripts/survey.sh +44 -0
  60. package/plugins/devos/skills/implement/SKILL.md +36 -0
  61. package/plugins/devos/skills/implement/references/conditional-plan.md +17 -0
  62. package/plugins/devos/skills/implement/references/debug-loop.md +7 -0
  63. package/plugins/devos/skills/implement/references/dod.md +32 -0
  64. package/plugins/devos/skills/implement/references/implement.md +52 -0
  65. package/plugins/devos/skills/implement/references/manual-gates.md +16 -0
  66. package/plugins/devos/skills/implement/references/plan.md +160 -0
  67. package/plugins/devos/skills/implement/references/resume.md +9 -0
  68. package/plugins/devos/skills/implement/references/scale.md +86 -0
  69. package/plugins/devos/skills/implement/references/verify-close.md +61 -0
  70. package/plugins/devos/skills/implement/references/visual-verification.md +7 -0
  71. package/plugins/devos/skills/implement/scripts/check-converge.sh +147 -0
  72. package/plugins/devos/skills/implement/scripts/equivalence-check.sh +140 -0
  73. package/plugins/devos/skills/implement/scripts/manifest-queue.sh +185 -0
  74. package/plugins/devos/skills/implement/scripts/ops-log.sh +58 -0
  75. package/plugins/devos/skills/implement/scripts/pilot-consistency.py +173 -0
  76. package/plugins/devos/skills/implement/scripts/validate-spec.sh +268 -0
  77. package/plugins/devos/skills/init/SKILL.md +100 -0
  78. package/plugins/devos/skills/init/references/archetype-sections.md +15 -0
  79. package/plugins/devos/skills/init/references/context.md +42 -0
  80. package/plugins/devos/skills/init/references/conventions-template.md +153 -0
  81. package/plugins/devos/skills/init/references/reverse-engineer.md +3 -0
  82. package/plugins/devos/skills/init/references/rule-format.md +58 -0
  83. package/plugins/devos/skills/init/references/shape-model.md +29 -0
  84. package/plugins/devos/skills/init/scripts/detect-archetype.py +461 -0
  85. package/plugins/devos/skills/init/scripts/render-rule.py +114 -0
  86. package/plugins/devos/skills/init/scripts/reverse-engineer.sh +162 -0
  87. package/plugins/devos/skills/learn/SKILL.md +29 -0
  88. package/plugins/devos/skills/learn/references/destinations.md +43 -0
  89. package/plugins/devos/skills/learn/references/scoring.md +26 -0
  90. package/plugins/devos/skills/product/SKILL.md +40 -0
  91. package/plugins/devos/skills/product/references/planner.md +54 -0
  92. package/plugins/devos/skills/review/SKILL.md +77 -0
  93. package/plugins/devos/skills/review/references/gaps.md +26 -0
  94. package/plugins/devos/skills/spec/SKILL.md +58 -0
  95. package/plugins/devos/skills/spec/references/prototype.md +21 -0
  96. package/plugins/devos/skills/spec/references/question-craft.md +47 -0
  97. package/plugins/devos/skills/spec/references/roadmap-link.md +5 -0
  98. package/plugins/devos/skills/spec/references/write-spec.md +143 -0
  99. package/plugins/devos/skills/spec/scripts/clarify.sh +173 -0
  100. package/plugins/devos/skills/status/SKILL.md +67 -0
  101. package/plugins/devos/skills/status/references/cost.md +38 -0
  102. package/plugins/devos/skills/status/scripts/artifact-budgets.sh +88 -0
  103. package/plugins/devos/skills/status/scripts/check-requires.py +556 -0
  104. package/plugins/devos/skills/status/scripts/context-cost.sh +89 -0
  105. package/plugins/devos/skills/status/scripts/convention-usage.sh +184 -0
  106. package/plugins/devos/skills/status/scripts/findings-summary.sh +112 -0
  107. package/plugins/devos/skills/status/scripts/quality-correlation.sh +282 -0
  108. package/plugins/devos/skills/status/scripts/sizing-calibration.sh +71 -0
  109. package/plugins/devos/skills/status/scripts/spec-diff.sh +137 -0
  110. package/plugins/devos/skills/surgical-diff/SKILL.md +23 -0
  111. package/plugins/devos/skills/test-integrity/SKILL.md +26 -0
  112. package/plugins/devos/skills/verification-evidence/SKILL.md +17 -0
  113. package/plugins/devos/workflows/common/backlog-file-structure.md +44 -0
  114. package/plugins/devos/workflows/common/category-file-structure.md +41 -0
  115. package/plugins/devos/workflows/common/feature-line-format.md +10 -0
  116. package/plugins/devos/workflows/common/roadmap-file-structure.md +51 -0
  117. package/plugins/devos/workflows/common/suggest-categories.md +76 -0
  118. package/plugins/devos/workflows/common/suggest-milestones.md +92 -0
  119. package/plugins/devos/workflows/doc/doc-health.md +137 -0
  120. package/plugins/devos/workflows/doc/doc-writer.md +44 -0
  121. package/plugins/devos/workflows/doc/init-documentation.md +196 -0
  122. package/plugins/devos/workflows/doc/retro-documentation.md +304 -0
  123. package/plugins/devos/workflows/doc/templates/library.md +58 -0
  124. package/plugins/devos/workflows/doc/templates/service.md +61 -0
  125. package/plugins/devos/workflows/doc/update-documentation.md +194 -0
  126. package/plugins/devos/workflows/doc/write-documentation.md +137 -0
  127. package/plugins/devos/workflows/product/create-product-mission.md +45 -0
  128. package/plugins/devos/workflows/product/create-product-roadmap.md +106 -0
  129. package/plugins/devos/workflows/product/create-product-tech-stack.md +19 -0
  130. package/plugins/devos/workflows/product/gather-product-info.md +25 -0
  131. package/plugins/devos/workflows/product/resume-detection.md +70 -0
  132. package/plugins/devos/workflows/product/reverse-backlog.md +118 -0
  133. package/plugins/devos/workflows/product/reverse-domain-model.md +86 -0
  134. package/plugins/devos/workflows/product/reverse-product-plan.md +81 -0
  135. package/plugins/devos/workflows/product/reverse-tech-stack.md +73 -0
  136. package/plugins/devos/workflows/product/scan-deep.md +113 -0
  137. package/plugins/devos/workflows/product/scan-git.md +122 -0
  138. 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 -->