@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,194 @@
|
|
|
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
|
+
```
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
# Workflow: Write Documentation (Agent)
|
|
2
|
+
|
|
3
|
+
**Goal:** Write or update functional documentation files within a strict scope. This workflow is paired with `doc-writer.md`.
|
|
4
|
+
|
|
5
|
+
**Input:** Scope (list of files), sources (specs, code), plan, mapping
|
|
6
|
+
|
|
7
|
+
**Output:** Written/modified documentation files, summary of changes
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Step 1: Read context
|
|
12
|
+
|
|
13
|
+
### 1.1 Read the sources
|
|
14
|
+
|
|
15
|
+
For each source provided by the orchestrator:
|
|
16
|
+
|
|
17
|
+
1. `Read` the source functional spec
|
|
18
|
+
2. `Read` the referenced source code files (if provided)
|
|
19
|
+
3. `Read` the documentation plan (`documentation-plan.md`)
|
|
20
|
+
4. `Read` the mapping (`documentation-mapping.md`)
|
|
21
|
+
|
|
22
|
+
### 1.2 Load templates
|
|
23
|
+
|
|
24
|
+
If `TEMPLATES_DIR` is provided:
|
|
25
|
+
1. Identify the type of file to write
|
|
26
|
+
2. `Read` the matching template
|
|
27
|
+
3. If `PROJECT_TEMPLATES_DIR` exists and contains an override → use the override
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## Step 2: Process files (within scope)
|
|
32
|
+
|
|
33
|
+
For each file in SCOPE:
|
|
34
|
+
|
|
35
|
+
### Case A: Creation (`create`)
|
|
36
|
+
|
|
37
|
+
1. Read the matching template
|
|
38
|
+
2. Extract relevant information from the sources (specs, code)
|
|
39
|
+
3. Write the content:
|
|
40
|
+
- Follow the template structure
|
|
41
|
+
- Use domain model vocabulary if available
|
|
42
|
+
- Include Mermaid diagrams where relevant (flows, sequences, relations)
|
|
43
|
+
- **No DevOS metadata**: 100% clean markdown file
|
|
44
|
+
4. `Write` the file
|
|
45
|
+
|
|
46
|
+
### Case B: Update (`update`)
|
|
47
|
+
|
|
48
|
+
1. `Read` the existing file
|
|
49
|
+
2. Identify sections to modify
|
|
50
|
+
3. **Smart merge:**
|
|
51
|
+
- Detect manual changes (content that doesn't match the last known state)
|
|
52
|
+
- Preserve manual changes when they don't conflict
|
|
53
|
+
- On conflict: **don't write**, flag it to the orchestrator
|
|
54
|
+
4. Generate the diff of planned changes
|
|
55
|
+
5. Apply changes via `Edit`
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## Step 3: Detecting out-of-scope changes
|
|
60
|
+
|
|
61
|
+
If, while writing, a change is needed on a file **outside the scope**:
|
|
62
|
+
|
|
63
|
+
1. **Don't modify the file**
|
|
64
|
+
2. Generate a proposed diff:
|
|
65
|
+
|
|
66
|
+
```
|
|
67
|
+
OUT_OF_SCOPE_DIFF:
|
|
68
|
+
file: path/to/out-of-scope-file.md
|
|
69
|
+
reason: [why this file needs changes]
|
|
70
|
+
diff: |
|
|
71
|
+
--- a/path/to/file.md
|
|
72
|
+
+++ b/path/to/file.md
|
|
73
|
+
@@ section @@
|
|
74
|
+
- old content
|
|
75
|
+
+ new content
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
The orchestrator will decide whether to apply it.
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
## Step 4: Writing rules
|
|
83
|
+
|
|
84
|
+
### Style
|
|
85
|
+
- **Language**: English (technical terms in English)
|
|
86
|
+
- **Tone**: professional, concise, factual
|
|
87
|
+
- **Structure**: prefer lists and tables over prose
|
|
88
|
+
- **Diagrams**: Mermaid for flows and relations (versionable text format)
|
|
89
|
+
|
|
90
|
+
### Content
|
|
91
|
+
- Describe the product's **current behavior** (not the spec history)
|
|
92
|
+
- Consolidate information from multiple specs into a coherent whole
|
|
93
|
+
- Resolve contradictions between specs (the most recent prevails)
|
|
94
|
+
- Include business rules, functional constraints, edge cases
|
|
95
|
+
|
|
96
|
+
### Prohibited
|
|
97
|
+
- No references to the DevOS framework
|
|
98
|
+
- No frontmatter or metadata
|
|
99
|
+
- No references to source specs (traceability lives in the mapping)
|
|
100
|
+
- No spec dates or spec versions
|
|
101
|
+
- No `TODO` or `FIXME` in the final content
|
|
102
|
+
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
## Step 5: Report
|
|
106
|
+
|
|
107
|
+
### Success (all files processed)
|
|
108
|
+
|
|
109
|
+
```
|
|
110
|
+
DOC_WRITER_REPORT: SUCCESS
|
|
111
|
+
files_created: [N]
|
|
112
|
+
files_updated: [N]
|
|
113
|
+
conflicts: 0
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
### With conflicts
|
|
117
|
+
|
|
118
|
+
```
|
|
119
|
+
DOC_WRITER_REPORT: CONFLICTS
|
|
120
|
+
files_created: [N]
|
|
121
|
+
files_updated: [N]
|
|
122
|
+
conflicts: [N]
|
|
123
|
+
conflict_details:
|
|
124
|
+
- file: path/to/file.md
|
|
125
|
+
section: [section name]
|
|
126
|
+
reason: Manual edits detected, cannot auto-merge
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
### With out-of-scope changes
|
|
130
|
+
|
|
131
|
+
```
|
|
132
|
+
DOC_WRITER_REPORT: OUT_OF_SCOPE
|
|
133
|
+
files_created: [N]
|
|
134
|
+
files_updated: [N]
|
|
135
|
+
out_of_scope_diffs: [N]
|
|
136
|
+
[include diffs from Step 3]
|
|
137
|
+
```
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
Create `devos/product/mission.md` with comprehensive product definition following this structure for its' content:
|
|
2
|
+
|
|
3
|
+
#### Mission Structure:
|
|
4
|
+
```markdown
|
|
5
|
+
# Product Mission
|
|
6
|
+
|
|
7
|
+
## Pitch
|
|
8
|
+
[PRODUCT_NAME] is a [PRODUCT_TYPE] that helps [TARGET_USERS] [SOLVE_PROBLEM]
|
|
9
|
+
by providing [KEY_VALUE_PROPOSITION].
|
|
10
|
+
|
|
11
|
+
## Users
|
|
12
|
+
|
|
13
|
+
### Primary Customers
|
|
14
|
+
- [CUSTOMER_SEGMENT_1]: [DESCRIPTION]
|
|
15
|
+
- [CUSTOMER_SEGMENT_2]: [DESCRIPTION]
|
|
16
|
+
|
|
17
|
+
## The Problem
|
|
18
|
+
|
|
19
|
+
### [PROBLEM_TITLE]
|
|
20
|
+
[PROBLEM_DESCRIPTION]. [QUANTIFIABLE_IMPACT].
|
|
21
|
+
|
|
22
|
+
**Our Solution:** [SOLUTION_APPROACH]
|
|
23
|
+
|
|
24
|
+
## Differentiators
|
|
25
|
+
|
|
26
|
+
### [DIFFERENTIATOR_TITLE]
|
|
27
|
+
Unlike [COMPETITOR/ALTERNATIVE], we provide [SPECIFIC_ADVANTAGE].
|
|
28
|
+
This results in [MEASURABLE_BENEFIT].
|
|
29
|
+
|
|
30
|
+
## Key Features
|
|
31
|
+
|
|
32
|
+
### Core Features
|
|
33
|
+
- **[FEATURE_NAME]:** [USER_BENEFIT_DESCRIPTION]
|
|
34
|
+
|
|
35
|
+
### Collaboration Features
|
|
36
|
+
- **[FEATURE_NAME]:** [USER_BENEFIT_DESCRIPTION]
|
|
37
|
+
|
|
38
|
+
### Advanced Features
|
|
39
|
+
- **[FEATURE_NAME]:** [USER_BENEFIT_DESCRIPTION]
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
#### Important Constraints
|
|
43
|
+
|
|
44
|
+
- **Focus on user benefits** in feature descriptions, not technical details
|
|
45
|
+
- **Keep it concise** and easy for users to scan and get the more important concepts quickly
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
Generate the product roadmap structure (v0.4 format) with milestones, categories, and backlog.
|
|
2
|
+
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
## Step 1: Read Prerequisites
|
|
6
|
+
|
|
7
|
+
1. **Read** `devos/product/mission.md` to understand goals and features
|
|
8
|
+
2. **Extract** the list of features from the "Key Features" section
|
|
9
|
+
3. **IF** mission.md doesn't exist:
|
|
10
|
+
```
|
|
11
|
+
ERROR: mission.md not found
|
|
12
|
+
|
|
13
|
+
Run /devos:product first to create the product mission.
|
|
14
|
+
```
|
|
15
|
+
**STOP** workflow.
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## Step 2: Read Project Configuration
|
|
20
|
+
|
|
21
|
+
Generated content follows the language rules in AGENTS.md, like everything else, no per-command language logic.
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## Step 3: Milestone names
|
|
26
|
+
|
|
27
|
+
Ask the user what to call each milestone (or propose short functional names from the milestone's content). No naming themes.
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## Step 4: Categorization Strategy
|
|
32
|
+
|
|
33
|
+
**MANDATORY: You MUST display the question and WAIT for the user's response before proceeding.**
|
|
34
|
+
**DO NOT skip this step. DO NOT auto-generate categories without asking.**
|
|
35
|
+
|
|
36
|
+
Read and follow `${CLAUDE_PLUGIN_ROOT}/workflows/common/suggest-categories.md`.
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## Step 5: Milestone Strategy
|
|
41
|
+
|
|
42
|
+
**MANDATORY: You MUST display the question and WAIT for the user's response before proceeding.**
|
|
43
|
+
**DO NOT skip this step. DO NOT auto-generate milestones without asking.**
|
|
44
|
+
|
|
45
|
+
Read and follow `${CLAUDE_PLUGIN_ROOT}/workflows/common/suggest-milestones.md`.
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
## Step 6: Create File Structure
|
|
50
|
+
|
|
51
|
+
### 6.1 Create backlog/ folder
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
mkdir -p devos/product/backlog
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
### 6.2 Create category files
|
|
58
|
+
|
|
59
|
+
**FOR EACH** category determined in Step 4:
|
|
60
|
+
|
|
61
|
+
Create `devos/product/backlog/[category-id].md`:
|
|
62
|
+
|
|
63
|
+
Read and follow `${CLAUDE_PLUGIN_ROOT}/workflows/common/category-file-structure.md`.
|
|
64
|
+
|
|
65
|
+
### 6.3 Create roadmap.md (v0.4 format)
|
|
66
|
+
|
|
67
|
+
Read and follow `${CLAUDE_PLUGIN_ROOT}/workflows/common/roadmap-file-structure.md`.
|
|
68
|
+
|
|
69
|
+
Read and follow `${CLAUDE_PLUGIN_ROOT}/workflows/common/feature-line-format.md`.
|
|
70
|
+
|
|
71
|
+
### 6.4 Create backlog.md (index)
|
|
72
|
+
|
|
73
|
+
Read and follow `${CLAUDE_PLUGIN_ROOT}/workflows/common/backlog-file-structure.md`.
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
## Step 7: Confirmation
|
|
78
|
+
|
|
79
|
+
```
|
|
80
|
+
Product roadmap created (v0.4 format)
|
|
81
|
+
|
|
82
|
+
Files created:
|
|
83
|
+
├── devos/product/roadmap.md
|
|
84
|
+
│ └── [N] milestones, [X] features planned
|
|
85
|
+
├── devos/product/backlog.md
|
|
86
|
+
│ └── Index of [Y] unplanned features
|
|
87
|
+
└── devos/product/backlog/
|
|
88
|
+
├── [category-1].md ([A] features)
|
|
89
|
+
├── [category-2].md ([B] features)
|
|
90
|
+
└── ...
|
|
91
|
+
|
|
92
|
+
Next steps:
|
|
93
|
+
- Edit roadmap.md directly to reorganize features between milestones
|
|
94
|
+
- Edit backlog.md directly to add new features
|
|
95
|
+
- Use /devos:spec to start specifying a feature
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
---
|
|
99
|
+
|
|
100
|
+
## Important Constraints
|
|
101
|
+
|
|
102
|
+
- **v0.4 format** - Always create YAML frontmatter + milestones structure
|
|
103
|
+
- **Category files** - YAML frontmatter only, no markdown body
|
|
104
|
+
- **Backlog.md** - Markdown only, no YAML frontmatter
|
|
105
|
+
- **Feature traceability** - Each feature appears in both category file AND roadmap/backlog
|
|
106
|
+
- **No bootstrap tasks** - Assume project codebase already exists
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
Create `devos/product/tech-stack.md` with a list of all tech stack choices that cover all aspects of this product's codebase.
|
|
2
|
+
|
|
3
|
+
### Creating the Tech Stack document
|
|
4
|
+
|
|
5
|
+
#### Step 1: Note User's Input Regarding Tech Stack
|
|
6
|
+
|
|
7
|
+
IF the user has provided specific information in the current conversation in regards to tech stack choices, these notes ALWAYS take precidence. These must be reflected in your final `tech-stack.md` document that you will create.
|
|
8
|
+
|
|
9
|
+
#### Step 2: Gather User's Default Tech Stack Information
|
|
10
|
+
|
|
11
|
+
Reconcile and fill in the remaining gaps in the tech stack list by finding, reading and analyzing information regarding the tech stack. Find this information in the following sources, in this order:
|
|
12
|
+
|
|
13
|
+
1. If user has provided their default tech stack under "User Standards & Preferences Compliance", READ and analyze this document.
|
|
14
|
+
2. If the current project has any of these files, read them to find information regarding tech stack choices for this codebase:
|
|
15
|
+
- `AGENTS.md`
|
|
16
|
+
|
|
17
|
+
#### Step 3: Create the Tech Stack Document
|
|
18
|
+
|
|
19
|
+
Create `devos/product/tech-stack.md` and populate it with the final list of all technical stack choices, reconciled between the information the user has provided to you and the information found in provided sources.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
Collect comprehensive product information from the user:
|
|
2
|
+
|
|
3
|
+
```bash
|
|
4
|
+
# Check if product folder already exists
|
|
5
|
+
if [ -d "devos/product" ]; then
|
|
6
|
+
echo "Product documentation already exists. Review existing files or start fresh?"
|
|
7
|
+
# List existing product files
|
|
8
|
+
ls -la devos/product/
|
|
9
|
+
fi
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
Gather from user the following required information:
|
|
13
|
+
- **Product Idea**: Core concept and purpose (required)
|
|
14
|
+
- **Key Features**: Minimum 3 features with descriptions
|
|
15
|
+
- **Target Users**: At least 1 user segment with use cases
|
|
16
|
+
- **Tech stack**: Confirmation or info regarding the product's tech stack choices
|
|
17
|
+
|
|
18
|
+
If any required information is missing, prompt user:
|
|
19
|
+
```
|
|
20
|
+
Please provide the following to create your product plan:
|
|
21
|
+
1. Main idea for the product
|
|
22
|
+
2. List of key features (minimum 3)
|
|
23
|
+
3. Target users and use cases (minimum 1)
|
|
24
|
+
4. Will this product use your usual tech stack choices or deviate in any way?
|
|
25
|
+
```
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# Workflow: Resume Detection
|
|
2
|
+
|
|
3
|
+
**Goal:** Detect onboarding progress from the presence of artifacts. No `.state.json`: detection is purely file-based.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Detection
|
|
8
|
+
|
|
9
|
+
Check for artifacts in reverse order (most advanced to least advanced):
|
|
10
|
+
|
|
11
|
+
### Check Phase 4 (Documentation)
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
# Check whether documentation has real content (not just skeletons)
|
|
15
|
+
find documentation/ -name "*.md" -not -name "index.html" 2>/dev/null | head -5
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
If documentation files with substantial content exist:
|
|
19
|
+
|
|
20
|
+
```
|
|
21
|
+
Onboarding detected at Phase 5 (documentation complete).
|
|
22
|
+
Onboarding appears to already be complete.
|
|
23
|
+
|
|
24
|
+
Do you want to:
|
|
25
|
+
A) Restart from the beginning (warning: overwrites existing artifacts)
|
|
26
|
+
B) Jump straight to post-onboarding suggestions
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
**WAIT** for the response. If A → resume Phase 1. If B → go to Phase 5.
|
|
30
|
+
|
|
31
|
+
### Check Phase 3 (Reconstruction)
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
ls devos/product/mission.md devos/product/domain-model.md devos/product/tech-stack.md 2>/dev/null
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
If all three files exist:
|
|
38
|
+
|
|
39
|
+
```
|
|
40
|
+
Onboarding detected at Phase 3 (foundations reconstructed).
|
|
41
|
+
Resume at Phase 4 (documentation)?
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
If yes → go to Phase 4.
|
|
45
|
+
|
|
46
|
+
### Check Phase 2 (Deep Scan)
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
ls devos/onboarding/findings/*.md 2>/dev/null
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
If findings exist:
|
|
53
|
+
|
|
54
|
+
```
|
|
55
|
+
Onboarding detected at Phase 2 (deep scan complete).
|
|
56
|
+
[N] findings files found.
|
|
57
|
+
Resume at Phase 3 (reconstruction)?
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
If yes → go to Phase 3.
|
|
61
|
+
|
|
62
|
+
### No artifacts
|
|
63
|
+
|
|
64
|
+
If no onboarding artifacts are detected:
|
|
65
|
+
|
|
66
|
+
```
|
|
67
|
+
No previous onboarding detected. Starting from Phase 1.
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
→ go to Phase 1.
|