@tduyng/pi-devos 0.13.6 → 0.14.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +23 -0
- package/README.md +26 -33
- package/package.json +1 -2
- package/plugins/devos/agents/verifier.md +4 -30
- package/plugins/devos/pi/extension/devos.ts +16 -26
- package/plugins/devos/scripts/check-evidence-router.sh +7 -1
- package/plugins/devos/scripts/evidence-router.py +5 -3
- package/plugins/devos/scripts/gates/check-dod-core.sh +5 -3
- package/plugins/devos/scripts/gates/check-port-source.sh +1 -1
- package/plugins/devos/scripts/gates/check-scenario-coverage.sh +10 -8
- package/plugins/devos/scripts/gates/phase-gate.sh +6 -6
- package/plugins/devos/scripts/gates/plan-template-check.py +6 -12
- package/plugins/devos/scripts/gates/spec-contract.sh +19 -0
- package/plugins/devos/scripts/gates/spec-template-check.py +8 -21
- package/plugins/devos/scripts/gates/suite/01-dod.sh +485 -0
- package/plugins/devos/scripts/gates/suite/02-integrity.sh +310 -0
- package/plugins/devos/scripts/gates/suite/03-archetype.sh +255 -0
- package/plugins/devos/scripts/gates/suite/04-spec-validator.sh +183 -0
- package/plugins/devos/scripts/gates/suite/05-requires.sh +360 -0
- package/plugins/devos/scripts/gates/suite/06-clarify-adapters.sh +435 -0
- package/plugins/devos/scripts/gates/suite/07-lint-evals.sh +350 -0
- package/plugins/devos/scripts/gates/suite/08-converge.sh +591 -0
- package/plugins/devos/scripts/gates/suite/09-quality.sh +516 -0
- package/plugins/devos/scripts/gates/suite/10-eval-harness.sh +679 -0
- package/plugins/devos/scripts/gates/test-gates.sh +23 -4253
- package/plugins/devos/scripts/gates/test-integrity-rubric.sh +1 -1
- package/plugins/devos/scripts/gates/test-phase-gate.sh +5 -5
- package/plugins/devos/skills/build/SKILL.md +3 -3
- package/plugins/devos/skills/build/references/refactor.md +1 -1
- package/plugins/devos/skills/build/references/routes.md +4 -4
- package/plugins/devos/skills/frame/SKILL.md +22 -39
- package/plugins/devos/skills/frame/references/template.md +115 -0
- package/plugins/devos/skills/implement/SKILL.md +4 -4
- package/plugins/devos/skills/implement/references/dod.md +6 -1
- package/plugins/devos/skills/implement/references/implement.md +3 -1
- package/plugins/devos/skills/implement/references/plan.md +9 -27
- package/plugins/devos/skills/implement/references/resume.md +1 -1
- package/plugins/devos/skills/implement/references/verify-close.md +4 -3
- package/plugins/devos/skills/implement/scripts/ops-log.sh +2 -2
- package/plugins/devos/skills/implement/scripts/validate-spec.sh +17 -65
- package/plugins/devos/skills/init/references/context.md +1 -1
- package/plugins/devos/skills/review/SKILL.md +24 -47
- package/plugins/devos/skills/review/references/comments.md +13 -0
- package/plugins/devos/skills/review/references/reviewer.md +124 -0
- package/plugins/devos/skills/review/references/routing.md +35 -0
- package/plugins/devos/skills/review/scripts/__pycache__/prepare.cpython-313.pyc +0 -0
- package/plugins/devos/skills/review/scripts/prepare.py +763 -0
- package/plugins/devos/skills/spec/SKILL.md +5 -6
- package/plugins/devos/skills/spec/references/write-spec.md +36 -51
- package/plugins/devos/skills/spec/scripts/clarify.sh +4 -4
- package/plugins/devos/skills/status/SKILL.md +4 -4
- package/plugins/devos/skills/status/scripts/check-requires.py +4 -4
- package/plugins/devos/skills/status/scripts/convention-usage.sh +1 -1
- package/plugins/devos/skills/status/scripts/quality-correlation.sh +2 -25
- package/plugins/devos/scripts/gates/check-handoff.sh +0 -215
- package/plugins/devos/skills/design-taste/SKILL.md +0 -55
- package/plugins/devos/skills/design-taste/references/tells.md +0 -85
- package/plugins/devos/skills/design-taste/scripts/slop-scan.py +0 -305
- package/plugins/devos/skills/docs/SKILL.md +0 -22
- package/plugins/devos/skills/docs/references/backfill.md +0 -54
- package/plugins/devos/skills/docs/references/init.md +0 -43
- package/plugins/devos/skills/docs/references/status.md +0 -71
- package/plugins/devos/skills/docs/references/update.md +0 -80
- package/plugins/devos/skills/explain/SKILL.md +0 -45
- package/plugins/devos/skills/explain/references/quiz.md +0 -21
- package/plugins/devos/skills/frame/references/boundaries.md +0 -53
- package/plugins/devos/skills/frame/references/decompose.md +0 -96
- package/plugins/devos/skills/frame/references/impact.md +0 -43
- package/plugins/devos/skills/frame/references/interrogate.md +0 -68
- package/plugins/devos/skills/product/SKILL.md +0 -40
- package/plugins/devos/skills/product/references/planner.md +0 -54
- package/plugins/devos/skills/surgical-diff/SKILL.md +0 -23
- package/plugins/devos/skills/test-integrity/SKILL.md +0 -26
- package/plugins/devos/skills/verification-evidence/SKILL.md +0 -17
- package/plugins/devos/workflows/common/backlog-file-structure.md +0 -44
- package/plugins/devos/workflows/common/category-file-structure.md +0 -41
- package/plugins/devos/workflows/common/feature-line-format.md +0 -10
- package/plugins/devos/workflows/common/roadmap-file-structure.md +0 -51
- package/plugins/devos/workflows/common/suggest-categories.md +0 -76
- package/plugins/devos/workflows/common/suggest-milestones.md +0 -92
- package/plugins/devos/workflows/doc/doc-health.md +0 -137
- package/plugins/devos/workflows/doc/doc-writer.md +0 -44
- package/plugins/devos/workflows/doc/init-documentation.md +0 -196
- package/plugins/devos/workflows/doc/retro-documentation.md +0 -304
- package/plugins/devos/workflows/doc/templates/library.md +0 -58
- package/plugins/devos/workflows/doc/templates/service.md +0 -61
- package/plugins/devos/workflows/doc/update-documentation.md +0 -194
- package/plugins/devos/workflows/doc/write-documentation.md +0 -137
- package/plugins/devos/workflows/product/create-product-mission.md +0 -45
- package/plugins/devos/workflows/product/create-product-roadmap.md +0 -106
- package/plugins/devos/workflows/product/create-product-tech-stack.md +0 -19
- package/plugins/devos/workflows/product/gather-product-info.md +0 -25
- package/plugins/devos/workflows/product/resume-detection.md +0 -70
- package/plugins/devos/workflows/product/reverse-backlog.md +0 -118
- package/plugins/devos/workflows/product/reverse-domain-model.md +0 -86
- package/plugins/devos/workflows/product/reverse-product-plan.md +0 -81
- package/plugins/devos/workflows/product/reverse-tech-stack.md +0 -73
- package/plugins/devos/workflows/product/scan-deep.md +0 -113
- package/plugins/devos/workflows/product/scan-git.md +0 -122
- package/plugins/devos/workflows/product/scan-light.md +0 -154
|
@@ -1,51 +0,0 @@
|
|
|
1
|
-
### Roadmap File Structure
|
|
2
|
-
|
|
3
|
-
⚠️ **CRITICAL FORMAT RULES:**
|
|
4
|
-
- File extension: **`.md`** (NOT `.yml` or `.yaml`)
|
|
5
|
-
- Content: YAML Frontmatter + Markdown body (both in same file)
|
|
6
|
-
- Frontmatter defines milestones metadata
|
|
7
|
-
- Markdown body contains the actual roadmap content
|
|
8
|
-
|
|
9
|
-
**Complete file example (`roadmap.md`):**
|
|
10
|
-
|
|
11
|
-
```md
|
|
12
|
-
---
|
|
13
|
-
milestones:
|
|
14
|
-
- id: M1-Mercury
|
|
15
|
-
name: "Milestone 1: Mercury"
|
|
16
|
-
timeframe: "Q1 2025"
|
|
17
|
-
- id: M2-Venus
|
|
18
|
-
name: "Milestone 2: Venus"
|
|
19
|
-
timeframe: "Q2 2025"
|
|
20
|
-
---
|
|
21
|
-
|
|
22
|
-
# Product Roadmap
|
|
23
|
-
|
|
24
|
-
## Milestone 1: Mercury (Q1 2025)
|
|
25
|
-
|
|
26
|
-
**Goal**: Foundation phase with core features.
|
|
27
|
-
|
|
28
|
-
### Category 1
|
|
29
|
-
|
|
30
|
-
- [x] Feature A [M] - [category](backlog/category.md) - [Spec](specs/...)
|
|
31
|
-
- [ ] Feature B [L] - [category](backlog/category.md) - No spec yet
|
|
32
|
-
|
|
33
|
-
### Category 2
|
|
34
|
-
|
|
35
|
-
- [ ] Feature C [S] - [category](backlog/category.md) - No spec yet
|
|
36
|
-
|
|
37
|
-
**Success Metrics**:
|
|
38
|
-
|
|
39
|
-
- Metric 1 : Details
|
|
40
|
-
- Metric 2 : Details
|
|
41
|
-
- Metric 3 : Details
|
|
42
|
-
|
|
43
|
-
## Milestone 2: Venus (Q2 2025)
|
|
44
|
-
|
|
45
|
-
(No features planned)
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
**Rules:**
|
|
49
|
-
- Section title `## [name] ([timeframe])` MUST match the frontmatter values
|
|
50
|
-
- Empty milestone section: `(No features planned)`
|
|
51
|
-
- Milestone fields: `id`, `name`, `timeframe` (all required)
|
|
@@ -1,76 +0,0 @@
|
|
|
1
|
-
### Suggest Categories for Features
|
|
2
|
-
|
|
3
|
-
**Objective:** Ask user how to organize features into categories.
|
|
4
|
-
|
|
5
|
-
**Input:** List of features (names)
|
|
6
|
-
|
|
7
|
-
**Output:** Category assignments for each feature
|
|
8
|
-
|
|
9
|
-
---
|
|
10
|
-
|
|
11
|
-
## Step 1: Present Options
|
|
12
|
-
|
|
13
|
-
**DISPLAY:**
|
|
14
|
-
|
|
15
|
-
```
|
|
16
|
-
📦 CATEGORIZATION STRATEGY
|
|
17
|
-
|
|
18
|
-
How would you like to organize your features into categories?
|
|
19
|
-
|
|
20
|
-
1. Single "legacy" category for all features
|
|
21
|
-
2. Let me suggest categories based on feature names
|
|
22
|
-
3. Define my own categories now
|
|
23
|
-
|
|
24
|
-
Your choice?
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
**WAIT** for user response.
|
|
28
|
-
|
|
29
|
-
---
|
|
30
|
-
|
|
31
|
-
## Option 1: Single "legacy" Category
|
|
32
|
-
|
|
33
|
-
- Assign all features to category `legacy` (name: "Legacy Features")
|
|
34
|
-
- **CONTINUE** to calling workflow
|
|
35
|
-
|
|
36
|
-
---
|
|
37
|
-
|
|
38
|
-
## Option 2: Automatic Suggestions
|
|
39
|
-
|
|
40
|
-
1. **Analyze** feature names for common patterns (Auth, Dashboard, API, User, etc.)
|
|
41
|
-
2. **Group** features by identified patterns
|
|
42
|
-
3. **DISPLAY:**
|
|
43
|
-
```
|
|
44
|
-
📦 Suggested categories based on your features:
|
|
45
|
-
|
|
46
|
-
1. authentication (3 features): Login, Logout, Password Reset
|
|
47
|
-
2. dashboard (2 features): Main Dashboard, Analytics
|
|
48
|
-
3. api (4 features): REST API, GraphQL, Webhooks
|
|
49
|
-
|
|
50
|
-
Accept? (ok / modify / option 3)
|
|
51
|
-
```
|
|
52
|
-
4. **IF** modify: allow reassigning individual features
|
|
53
|
-
5. **IF** ok: **CONTINUE** to calling workflow
|
|
54
|
-
|
|
55
|
-
---
|
|
56
|
-
|
|
57
|
-
## Option 3: Manual Categories
|
|
58
|
-
|
|
59
|
-
1. **ASK:**
|
|
60
|
-
```
|
|
61
|
-
Define your categories (one per line, format: id - Name)
|
|
62
|
-
|
|
63
|
-
Example:
|
|
64
|
-
core - Core Features
|
|
65
|
-
ui - User Interface
|
|
66
|
-
|
|
67
|
-
Your categories:
|
|
68
|
-
```
|
|
69
|
-
|
|
70
|
-
2. **FOR EACH** feature, **ASK:**
|
|
71
|
-
```
|
|
72
|
-
Feature: "[name]"
|
|
73
|
-
Category? [list categories]
|
|
74
|
-
```
|
|
75
|
-
|
|
76
|
-
3. **CONTINUE** to calling workflow
|
|
@@ -1,92 +0,0 @@
|
|
|
1
|
-
### Suggest Milestones for Features
|
|
2
|
-
|
|
3
|
-
**Objective:** Ask user how to organize features into milestones.
|
|
4
|
-
|
|
5
|
-
**Input:**
|
|
6
|
-
- List of features (with sizes if available)
|
|
7
|
-
- Theme from previous step (select-milestone-theme)
|
|
8
|
-
|
|
9
|
-
**Output:** Milestone assignments for each feature (or backlog)
|
|
10
|
-
|
|
11
|
-
---
|
|
12
|
-
|
|
13
|
-
## Step 1: Present Options
|
|
14
|
-
|
|
15
|
-
**DISPLAY:**
|
|
16
|
-
|
|
17
|
-
```
|
|
18
|
-
📋 MILESTONE STRATEGY
|
|
19
|
-
|
|
20
|
-
Theme: [theme] (e.g., planets → Mercury, Venus, Mars...)
|
|
21
|
-
|
|
22
|
-
How would you like to organize milestones?
|
|
23
|
-
|
|
24
|
-
1. Single milestone for all features
|
|
25
|
-
2. Two milestones: Completed (M1) + In Progress (M2)
|
|
26
|
-
3. Let me suggest milestones based on priority/size
|
|
27
|
-
4. Define my own milestones now
|
|
28
|
-
|
|
29
|
-
Your choice?
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
**WAIT** for user response.
|
|
33
|
-
|
|
34
|
-
---
|
|
35
|
-
|
|
36
|
-
## Option 1: Single Milestone
|
|
37
|
-
|
|
38
|
-
1. **Generate** first milestone name from theme (e.g., M1-Mercury)
|
|
39
|
-
2. **ASK** for timeframe: `Target period (e.g., "Q1 2025"): ___`
|
|
40
|
-
3. Assign all features to this milestone
|
|
41
|
-
4. **CONTINUE** to calling workflow
|
|
42
|
-
|
|
43
|
-
---
|
|
44
|
-
|
|
45
|
-
## Option 2: By Completion State
|
|
46
|
-
|
|
47
|
-
1. **Generate** milestone names from theme:
|
|
48
|
-
- M1 → First name (Mercury) for completed features
|
|
49
|
-
- M2 → Second name (Venus) for in-progress features
|
|
50
|
-
2. **ASK** timeframes for each
|
|
51
|
-
3. **IF** no completed features: only create M1 for pending
|
|
52
|
-
4. **CONTINUE** to calling workflow
|
|
53
|
-
|
|
54
|
-
---
|
|
55
|
-
|
|
56
|
-
## Option 3: Automatic Suggestions
|
|
57
|
-
|
|
58
|
-
1. **Analyze** feature sizes (XS/S → quick wins, L/XL → major efforts)
|
|
59
|
-
2. **DISPLAY:**
|
|
60
|
-
```
|
|
61
|
-
📋 Suggested milestones:
|
|
62
|
-
|
|
63
|
-
M1-Mercury (Q1 2025): 5 features (quick wins)
|
|
64
|
-
M2-Venus (Q2 2025): 4 features (standard work)
|
|
65
|
-
Backlog: 3 features (not yet planned)
|
|
66
|
-
|
|
67
|
-
Accept? (ok / modify / option 4)
|
|
68
|
-
```
|
|
69
|
-
3. **IF** modify: allow reassigning individual features
|
|
70
|
-
4. **IF** ok: **CONTINUE** to calling workflow
|
|
71
|
-
|
|
72
|
-
---
|
|
73
|
-
|
|
74
|
-
## Option 4: Manual Milestones
|
|
75
|
-
|
|
76
|
-
1. **ASK:**
|
|
77
|
-
```
|
|
78
|
-
Define your milestones (one per line)
|
|
79
|
-
|
|
80
|
-
Format: ID - Name - Timeframe
|
|
81
|
-
Example: M1-Mercury - Phase 1: Foundation - Q1 2025
|
|
82
|
-
|
|
83
|
-
Your milestones:
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
2. **FOR EACH** feature, **ASK:**
|
|
87
|
-
```
|
|
88
|
-
Feature: "[name]" [SIZE]
|
|
89
|
-
Milestone? [list milestones] or "backlog"
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
3. **CONTINUE** to calling workflow
|
|
@@ -1,137 +0,0 @@
|
|
|
1
|
-
# Workflow: Documentation Health
|
|
2
|
-
|
|
3
|
-
**Goal:** Compute and display health metrics for the consolidated documentation: coverage, freshness, structural completeness.
|
|
4
|
-
|
|
5
|
-
**Input:** `documentation-mapping.md`, documentation files, specs
|
|
6
|
-
|
|
7
|
-
**Output:** `documentation-health.md` (persisted metrics), console display
|
|
8
|
-
|
|
9
|
-
---
|
|
10
|
-
|
|
11
|
-
## Step 1: Read sources
|
|
12
|
-
|
|
13
|
-
### Batch 1 (parallel)
|
|
14
|
-
|
|
15
|
-
1. `Read devos/product/documentation-mapping.md`
|
|
16
|
-
2. `Read devos/product/documentation-plan.md`
|
|
17
|
-
3. `Glob devos/specs/*/verifications/verification.md`: implemented specs
|
|
18
|
-
|
|
19
|
-
If the mapping doesn't exist:
|
|
20
|
-
```
|
|
21
|
-
❌ No documentation mapping found.
|
|
22
|
-
|
|
23
|
-
Run first: /devos:docs init
|
|
24
|
-
```
|
|
25
|
-
**STOP**
|
|
26
|
-
|
|
27
|
-
---
|
|
28
|
-
|
|
29
|
-
## Step 2: Read configuration
|
|
30
|
-
|
|
31
|
-
```bash
|
|
32
|
-
```
|
|
33
|
-
|
|
34
|
-
**Variable:** `DOC_DIR` = `documentation` (fixed default; change it by editing this workflow)
|
|
35
|
-
|
|
36
|
-
---
|
|
37
|
-
|
|
38
|
-
## Step 3: Compute metrics
|
|
39
|
-
|
|
40
|
-
### 3.1 Coverage
|
|
41
|
-
|
|
42
|
-
```
|
|
43
|
-
specs_total = number of specs with verifications/verification.md (implemented)
|
|
44
|
-
specs_documented = number of those specs appearing in the mapping's "Source Specs" column
|
|
45
|
-
coverage = specs_documented / specs_total * 100
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
### 3.2 Freshness
|
|
49
|
-
|
|
50
|
-
For each documented spec, use the `Last Sync` dates in the mapping:
|
|
51
|
-
|
|
52
|
-
```
|
|
53
|
-
avg_freshness = average(now - last_sync) in days
|
|
54
|
-
max_freshness = max(now - last_sync) in days
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
### 3.3 Structural completeness
|
|
58
|
-
|
|
59
|
-
For each documentation file in the mapping:
|
|
60
|
-
|
|
61
|
-
1. `Read` the file
|
|
62
|
-
2. Count:
|
|
63
|
-
- `sections_total` = number of H2 and H3 headings
|
|
64
|
-
- `sections_filled` = headings followed by substantial content (not a placeholder)
|
|
65
|
-
- `placeholders` = headings followed by `<!-- TODO` or content < 20 characters
|
|
66
|
-
|
|
67
|
-
```
|
|
68
|
-
completeness = sections_filled / sections_total * 100
|
|
69
|
-
placeholders_count = total number of placeholders
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
---
|
|
73
|
-
|
|
74
|
-
## Step 4: Persistence
|
|
75
|
-
|
|
76
|
-
Write `devos/product/documentation-health.md`:
|
|
77
|
-
|
|
78
|
-
```markdown
|
|
79
|
-
# Documentation Health
|
|
80
|
-
|
|
81
|
-
> Last evaluated: [ISO timestamp]
|
|
82
|
-
|
|
83
|
-
## Metrics
|
|
84
|
-
|
|
85
|
-
| Metric | Value | Detail |
|
|
86
|
-
|--------|-------|--------|
|
|
87
|
-
| **Coverage** | [N]% | [documented]/[total] specs documented |
|
|
88
|
-
| **Freshness** | [N] days | Average age since last sync |
|
|
89
|
-
| **Completeness** | [N]% | [filled]/[total] sections filled |
|
|
90
|
-
|
|
91
|
-
## Detail by domain
|
|
92
|
-
|
|
93
|
-
| Domain | Files | Completeness | Last update |
|
|
94
|
-
|--------|-------|--------------|-------------|
|
|
95
|
-
| [Domain 1] | [N] | [N]% | [date] |
|
|
96
|
-
|
|
97
|
-
## Undocumented specs
|
|
98
|
-
|
|
99
|
-
| Spec | Implemented | Reason |
|
|
100
|
-
|------|-------------|--------|
|
|
101
|
-
| [spec-1] | yes | Not yet documented |
|
|
102
|
-
|
|
103
|
-
## Remaining placeholders
|
|
104
|
-
|
|
105
|
-
| File | Section | Type |
|
|
106
|
-
|------|---------|------|
|
|
107
|
-
| [file] | [heading] | TODO |
|
|
108
|
-
```
|
|
109
|
-
|
|
110
|
-
---
|
|
111
|
-
|
|
112
|
-
## Step 5: Console display
|
|
113
|
-
|
|
114
|
-
```
|
|
115
|
-
📊 DOCUMENTATION HEALTH
|
|
116
|
-
══════════════════════════════════════════════
|
|
117
|
-
|
|
118
|
-
Coverage [████████░░] 80% (12/15 specs)
|
|
119
|
-
Freshness [██████████] 2d (average age)
|
|
120
|
-
Completeness [███████░░░] 72% (89/123 sections)
|
|
121
|
-
|
|
122
|
-
──────────────────────────────────────────────
|
|
123
|
-
Domains:
|
|
124
|
-
✅ Authentication 100% (last update: 2026-03-25)
|
|
125
|
-
⚠️ Notifications 60% (last update: 2026-02-15)
|
|
126
|
-
🔴 Administration 25% (last update: 2026-01-10)
|
|
127
|
-
|
|
128
|
-
──────────────────────────────────────────────
|
|
129
|
-
⚠️ 3 undocumented specs
|
|
130
|
-
🔧 12 remaining placeholders
|
|
131
|
-
|
|
132
|
-
📄 Report: devos/product/documentation-health.md
|
|
133
|
-
```
|
|
134
|
-
|
|
135
|
-
**Completeness indicators:** ✅ >= 90% | ⚠️ 50-89% | 🔴 < 50%
|
|
136
|
-
|
|
137
|
-
**Progress bar (10 chars):** `█` filled, `░` empty
|
|
@@ -1,44 +0,0 @@
|
|
|
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`.
|
|
@@ -1,196 +0,0 @@
|
|
|
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
|
-
```
|