@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,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
|