@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,137 @@
1
+ #!/bin/bash
2
+ # /devos:status --compare: structural comparison of two specs' spec.md files.
3
+ # Deterministic, zero model calls.
4
+ #
5
+ # Usage: spec-diff.sh <spec-a> <spec-b> [project-root]
6
+ # Spec names are directory names under devos/specs/ or devos/specs/archive/.
7
+ # project-root defaults to pwd (the user's project directory).
8
+ #
9
+ # Compares, against the spec.md template in implement/SKILL.md: Implementation
10
+ # Plan task groups, each task group's inline Acceptance Criteria line, Code
11
+ # Map file list, and the Change Log (the amendment record after approval).
12
+ # spec.md has no separate "Behavior delta" heading of its own (that term
13
+ # names the merge step into devos/product/behaviors/, not a section in
14
+ # spec.md), so this tool doesn't claim to diff one. Structural comparison
15
+ # only, no semantic analysis, same shape as a `diff` command for markdown
16
+ # files with a known layout.
17
+ set -u
18
+
19
+ if [[ $# -lt 2 ]]; then
20
+ echo "Usage: $0 <spec-a> <spec-b> [project-root]" >&2
21
+ exit 2
22
+ fi
23
+
24
+ a_name="$1"
25
+ b_name="$2"
26
+ PROJECT_ROOT="${3:-$(pwd)}"
27
+
28
+ valid_name() {
29
+ [[ -n "$1" && "$1" != "." && "$1" != ".." && "$1" != */* ]]
30
+ }
31
+
32
+ if ! valid_name "$a_name" || ! valid_name "$b_name"; then
33
+ echo "ERROR spec names must be single directory names without path separators" >&2
34
+ exit 2
35
+ fi
36
+
37
+ resolve() { # $1 = spec name -> path to its spec.md, or empty + stderr message
38
+ local name="$1" active_dir archive_dir
39
+ active_dir="$PROJECT_ROOT/devos/specs/$name"
40
+ archive_dir="$PROJECT_ROOT/devos/specs/archive/$name"
41
+ if [[ -d "$active_dir" ]]; then
42
+ if [[ -f "$active_dir/spec.md" ]]; then
43
+ echo "$active_dir/spec.md"
44
+ return 0
45
+ fi
46
+ echo "ERROR active spec '$name' exists but its spec.md is missing; refusing to compare an archived fallback" >&2
47
+ return 1
48
+ fi
49
+ if [[ -f "$archive_dir/spec.md" ]]; then
50
+ echo "$archive_dir/spec.md"
51
+ return 0
52
+ fi
53
+ echo "ERROR no spec.md found for '$name' under devos/specs/ or devos/specs/archive/" >&2
54
+ return 1
55
+ }
56
+
57
+ a=$(resolve "$a_name") || exit 1
58
+ b=$(resolve "$b_name") || exit 1
59
+
60
+ echo "Structural diff: $a_name vs $b_name"
61
+ echo "=============================="
62
+ echo ""
63
+
64
+ # Lines strictly between a start pattern and the next level-2 header,
65
+ # excluding both boundary lines. Portable (no GNU-only head -n -1, which
66
+ # silently returns empty under BSD/macOS head).
67
+ section() { # $1=file $2=start-regex
68
+ awk -v start="$2" '
69
+ $0 ~ start { f = 1; next }
70
+ f && /^## / { f = 0 }
71
+ f { print }
72
+ ' "$1"
73
+ }
74
+
75
+ report_diff() { # $1=label $2=a-content $3=b-content
76
+ if [[ "$2" == "$3" ]]; then
77
+ echo "$1 are identical."
78
+ else
79
+ echo "$1 differ:"
80
+ diff <(printf '%s\n' "$2") <(printf '%s\n' "$3") | sed 's/^/ /' || true
81
+ fi
82
+ }
83
+
84
+ echo "## Implementation Plan task groups"
85
+ # Same shape every other plan reader in the plugin uses ('###' + any run of
86
+ # spaces + 'Task' + any run of spaces + 'Group', then whitespace or a colon).
87
+ # The literal '### Task Group' made a plan whose headers carry an extra space
88
+ # look like it had no groups at all, and two plans that disagree on group 2 were
89
+ # reported as identical. Requiring whitespace after 'Group' then hid the
90
+ # colon form that check-converge.sh reads, and two plans whose only group is
91
+ # written that way compared as identical because both sides were empty.
92
+ group_re='^###[[:space:]]+Task[[:space:]]+Group([[:space:]]+|:)'
93
+ a_tasks=$(grep -E "$group_re" "$a" 2>/dev/null || true)
94
+ b_tasks=$(grep -E "$group_re" "$b" 2>/dev/null || true)
95
+ report_diff "Task groups" "$a_tasks" "$b_tasks"
96
+ echo ""
97
+
98
+ echo "## Acceptance Criteria (per task group)"
99
+ a_ac=$(grep -E '^\*\*Acceptance Criteria:\*\*' "$a" 2>/dev/null || true)
100
+ b_ac=$(grep -E '^\*\*Acceptance Criteria:\*\*' "$b" 2>/dev/null || true)
101
+ report_diff "Acceptance criteria" "$a_ac" "$b_ac"
102
+ echo ""
103
+
104
+ echo "## Code Map overlap"
105
+ a_map=$(section "$a" '^## Code Map')
106
+ b_map=$(section "$b" '^## Code Map')
107
+ a_files=$(printf '%s\n' "$a_map" | grep -oE '`[^`]+`' | tr -d '`' | sort -u)
108
+ b_files=$(printf '%s\n' "$b_map" | grep -oE '`[^`]+`' | tr -d '`' | sort -u)
109
+
110
+ if [[ -z "$a_files" && -z "$b_files" ]]; then
111
+ echo "Neither spec has a Code Map."
112
+ else
113
+ shared=$(comm -12 <(printf '%s\n' "$a_files") <(printf '%s\n' "$b_files") | grep -c . || true)
114
+ a_only=$(comm -23 <(printf '%s\n' "$a_files") <(printf '%s\n' "$b_files") | grep -c . || true)
115
+ b_only=$(comm -13 <(printf '%s\n' "$a_files") <(printf '%s\n' "$b_files") | grep -c . || true)
116
+ echo "Shared files: $shared, Only in $a_name: $a_only, Only in $b_name: $b_only"
117
+ if ((shared > 0)); then
118
+ echo "Shared:"
119
+ comm -12 <(printf '%s\n' "$a_files") <(printf '%s\n' "$b_files") | sed 's/^/ /'
120
+ fi
121
+ if ((a_only > 0)); then
122
+ echo "Only in $a_name:"
123
+ comm -23 <(printf '%s\n' "$a_files") <(printf '%s\n' "$b_files") | sed 's/^/ /'
124
+ fi
125
+ if ((b_only > 0)); then
126
+ echo "Only in $b_name:"
127
+ comm -13 <(printf '%s\n' "$a_files") <(printf '%s\n' "$b_files") | sed 's/^/ /'
128
+ fi
129
+ fi
130
+ echo ""
131
+
132
+ echo "## Change Log"
133
+ a_log=$(section "$a" '^## Change Log')
134
+ b_log=$(section "$b" '^## Change Log')
135
+ report_diff "Change logs" "$a_log" "$b_log"
136
+
137
+ exit 0
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: surgical-diff
3
+ description: "Implementing from an approved plan or spec, or scope drifts: keep edits scoped."
4
+ user-invocable: false
5
+ ---
6
+
7
+ # Surgical diff
8
+
9
+ Every changed line traces to a task group in the approved plan.
10
+
11
+ - Before touching a file the plan doesn't list, name it and say why: one line is enough, silence is not.
12
+ - Match the surrounding code's style, naming, and comment density, even where you'd choose differently. If `devos/standards/rules/` has a file scoped to what you're touching, its bullets are the convention, not a suggestion: read it before the edit, not after a violation is flagged.
13
+ - Leave adjacent code as you found it: no drive-by refactors, comment rewrites, or reformatting. If you notice dead code or a latent bug outside scope, mention it in the report (or `decisions.md`): fixing it is a separate decision.
14
+ - Clean up your own orphans: imports, variables, and functions that **your** change made unused go; pre-existing dead code stays.
15
+ - When the codebase contradicts the plan, stop and say so (see the implement skill's HALT conditions): a surgical diff in the wrong place is a second bug, not a small fix.
16
+
17
+ | Rationalization | Rebuttal |
18
+ |---|---|
19
+ | "While I'm here, I'll clean this up" | Cleanup without a plan sentence is a new, unapproved change. Mention it, don't make it. |
20
+ | "This rename makes the code clearer" | It makes the diff bigger. The reviewer maps hunks to the plan, not to taste. |
21
+ | "It's just formatting, no logic change" | Then it's a separate commit under its own decision, not smuggled into this one. |
22
+
23
+ The test: could a reviewer map every hunk of the diff to a sentence in the plan? If a hunk has no sentence, either the plan grows (out loud) or the hunk goes.
@@ -0,0 +1,26 @@
1
+ ---
2
+ name: test-integrity
3
+ description: "Editing or debugging tests: keep assertions independent and fix code before weakening tests."
4
+ user-invocable: false
5
+ ---
6
+
7
+ # Test integrity
8
+
9
+ Tests are the spec's teeth. Implementation bends to tests, never the reverse.
10
+
11
+ - A failing test means the code is wrong until proven otherwise. Fix the code first.
12
+ - Keep assertions at full strength: the passing version of a test checks everything the failing version checked.
13
+ - A test that cannot disagree with the code is not a test. When the expected value is recomputed the way the implementation computes it (`expect(add(a, b)).toBe(a + b)`, a snapshot derived by hand the same way, a constant asserted equal to itself), it passes by construction, and the assertion count is unchanged so no counting gate sees it. Expected values come from an independent source: a known-good literal, a worked example, the spec.
14
+ - A test must fail when the code under test returns nothing. Stub it to return `undefined`, `[]`, `0`, or `""`. A test that still passes asserts nothing.
15
+ - Keep tests running: no `.skip`, no commented-out cases, no deleted tests to get to green.
16
+ - A test you believe is genuinely wrong gets said out loud: show why the asserted behavior contradicts the spec, and get agreement **before** changing it. Then the change is a spec correction, recorded in `decisions.md`, not a workaround.
17
+ - Failures you didn't cause get proven, not waved off: show the same test failing on the base branch, or fix it.
18
+
19
+ | Rationalization | Rebuttal |
20
+ |---|---|
21
+ | "The test was too strict" | The test is the spec's teeth: prove the spec disagrees, out loud, before touching it. |
22
+ | "I'll skip it now, re-enable after the merge" | A skipped test is a deleted test with better manners. Fix the code now. |
23
+ | "That failure is flaky / unrelated" | Show it failing on the base branch, or it's yours. |
24
+ | "I asserted the value the code computes, the count is unchanged" | Then the test can never fail. Get the expected value from the spec or a worked example, not from re-running the code's own arithmetic. |
25
+
26
+ The test: would the author of the failing test agree your change preserved its intent?
@@ -0,0 +1,17 @@
1
+ ---
2
+ name: verification-evidence
3
+ description: "For completion reports or verification verdicts, state commands, findings, and build or test status."
4
+ user-invocable: false
5
+ ---
6
+
7
+ # Verification evidence
8
+
9
+ A verdict without evidence is an opinion.
10
+
11
+ - Every PASS/CLEAN claim names the exact commands run and their exit status. "Tests pass" means you ran them **in this session**, never inferred from reading code.
12
+ - A run that executed nothing is not evidence. Report the count beside the status (`npm test` → exit 0, 42 passed), and treat zero tests collected as UNVERIFIED, never PASS: `go test` with no test files, a filter matching no test, and `--passWithNoTests` all exit 0 having proved nothing.
13
+ - Every finding carries `file:line`, the offending code, and why it's a gap. Every fix claim shows the check that now succeeds.
14
+ - A check you couldn't run is reported as SKIPPED with the reason, never silently folded into a PASS. An honest UNVERIFIED beats a false PASS.
15
+ - Partial coverage gets stated as partial: "checked these 6 files", not reported as full coverage.
16
+ - Re-measure every number at report time, or label it unverified. In measured agent runs, confident numbers stated from memory were the only false claims in otherwise-correct reports.
17
+ - Report failures faithfully: if 2 of 40 tests fail, the verdict is NOT DONE plus the failing output, not "mostly passing".
@@ -0,0 +1,44 @@
1
+ ### Backlog File Structure
2
+
3
+ ⚠️ **CRITICAL FORMAT RULES:**
4
+ - File extension: **`.md`** (NOT `.yml` or `.yaml`)
5
+ - Content: Pure Markdown (NO YAML frontmatter)
6
+ - This is an index file linking to category files
7
+
8
+ **Complete file example (`backlog.md`):**
9
+
10
+ ```md
11
+ # Product Backlog
12
+
13
+ Index of features not yet planned in a milestone.
14
+
15
+ ---
16
+
17
+ ## Category: Product Planning
18
+
19
+ [product-planning](backlog/product-planning.md)
20
+
21
+ - [ ] Feature X [M] - [product-planning](backlog/product-planning.md) - No spec yet
22
+ - [ ] Feature Y [L] - [product-planning](backlog/product-planning.md) - No spec yet
23
+
24
+ ---
25
+
26
+ ## Category: Verification System
27
+
28
+ [verification-system](backlog/verification-system.md)
29
+
30
+ (No features in this category)
31
+
32
+ ---
33
+
34
+ *Use `/devos:product` to plan these features into a milestone.*
35
+ ```
36
+
37
+ **Rules:**
38
+ - NO YAML frontmatter (pure Markdown file)
39
+ - One `## Category: [Name]` section per category
40
+ - Link to category file right after the header
41
+ - Features use universal format (see feature-line-format.md)
42
+ - Empty category: `(No features in this category)`
43
+ - `---` separator between each category section
44
+ - Footer noting how to promote features to the roadmap
@@ -0,0 +1,41 @@
1
+ ### Category File Structure
2
+
3
+ ⚠️ **CRITICAL FORMAT RULES:**
4
+ - File extension: **`.md`** (NOT `.yml` or `.yaml`)
5
+ - Content: YAML frontmatter ONLY (between `---` delimiters)
6
+ - NO markdown content after the closing `---`
7
+ - File ends immediately after the closing `---`
8
+
9
+ **Complete file example (`product-planning.md`):**
10
+
11
+ ```md
12
+ ---
13
+ category_id: product-planning
14
+ name: Product Planning
15
+
16
+ features:
17
+ - feature_id: backlog-grooming-cmd
18
+ name: Backlog Grooming Command
19
+ description: |
20
+ Command to manage backlog features.
21
+ size: L
22
+ milestone: null
23
+ spec: null
24
+ finalized: false
25
+ ---
26
+ ```
27
+
28
+ ↑ **File ends here. Nothing after the closing `---`.**
29
+
30
+ **Rules:**
31
+ - Empty array: `features: []`
32
+ - IDs: kebab-case, must match `^[a-z0-9-]+$`
33
+
34
+ **Feature fields:**
35
+ - `feature_id` : Unique kebab-case identifier
36
+ - `name` : Display name
37
+ - `description` : Multi-line description (use `|` for block scalar)
38
+ - `size` : XS, S, M, L, XL, XXL
39
+ - `milestone` : null (backlog) or milestone ID (e.g., "M1-Mercury")
40
+ - `spec` : null or path to spec folder
41
+ - `finalized` : false (pending) or true (completed)
@@ -0,0 +1,10 @@
1
+ ### Feature Line Format (Universal)
2
+
3
+ This format is **identical** in roadmap.md and backlog.md.
4
+
5
+ ```
6
+ - [x] Feature Name [SIZE] - [category-id](backlog/category-id.md) - [Spec](path)
7
+ - [ ] Feature Name [SIZE] - [category-id](backlog/category-id.md) - No spec yet
8
+ ```
9
+
10
+ **Rule:** `[x]` if `finalized: true`, `[ ]` otherwise.
@@ -0,0 +1,51 @@
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)
@@ -0,0 +1,76 @@
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
@@ -0,0 +1,92 @@
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
@@ -0,0 +1,137 @@
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