@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,268 @@
1
+ #!/bin/bash
2
+ # validate-spec.sh <spec-dir>: deterministic format check of a spec folder.
3
+ # Zero model calls. Run by implement before planning and by the
4
+ # verifier as its first completeness check.
5
+ #
6
+ # Diagnostic envelope (shared by DevOS check scripts):
7
+ # FAIL <check>: <message>
8
+ # fix: <one actionable line>
9
+ # Exit 0 = valid, 1 = findings, 2 = usage/missing folder.
10
+ set -u
11
+ dir="${1:-}"
12
+ if [[ -z "$dir" || ! -d "$dir" ]]; then
13
+ echo "FAIL validate-spec: spec directory not found: '${dir}'" >&2
14
+ echo " fix: pass a devos/specs/<name> folder" >&2
15
+ exit 2
16
+ fi
17
+ # Archived capsules are historical records. New plan gates apply to active
18
+ # work, not to specs that were completed before those gates existed. Detect
19
+ # the canonical layout rather than trusting a caller-provided exemption.
20
+ historical=0
21
+ if [[ "$(basename "$(dirname "$dir")")" == "archive" \
22
+ && "$(basename "$(dirname "$(dirname "$dir")")")" == "specs" ]]; then
23
+ historical=1
24
+ fi
25
+ fail=0
26
+ finding() { echo "FAIL validate-spec: $1"; echo " fix: $2"; fail=1; }
27
+
28
+ sf="$dir/spec-functional.md"
29
+ if [[ ! -f "$sf" ]]; then
30
+ finding "spec-functional.md missing in $dir" "write it (M route inline, or run /devos:spec)"
31
+ else
32
+ grep -qiE '^#+ .*goal' "$sf" || \
33
+ finding "spec-functional.md has no Goal section" "add a Goal section: 1-2 sentences of business purpose"
34
+ grep -qiE '^#+ .*out of scope|^\*\*out of scope' "$sf" || \
35
+ finding "spec-functional.md has no Out of Scope section" "state explicitly what this spec does not do"
36
+ notes="$dir/planning/notes.md"
37
+ if [[ -f "$notes" ]] && grep -q '^## Explicit contract anchors' "$notes"; then
38
+ grep -q '^\*\*Explicit contract anchors:\*\*' "$sf" || \
39
+ finding "spec-functional.md drops explicit contract anchors from planning/notes.md" "copy the supplied anchors verbatim into the Appendix, or record None supplied"
40
+ notes_anchor_lines=$(awk '
41
+ /^##[[:space:]]+Explicit contract anchors/ { in_anchors = 1; next }
42
+ in_anchors && /^##[[:space:]]/ { exit }
43
+ in_anchors && NF { print }
44
+ ' "$notes")
45
+ anchor_summary=$(awk '
46
+ /^\*\*Explicit contract anchors:\*\*/ { in_summary = 1 }
47
+ in_summary && /^##[[:space:]]/ { exit }
48
+ in_summary { print }
49
+ ' "$sf")
50
+ if [[ -n "$notes_anchor_lines" ]] && ! grep -qiE '(^|[[:space:]])(none supplied|unspecified|none|n/a)([[:punct:]]|$)' <<<"$notes_anchor_lines" \
51
+ && grep -qi 'none supplied' <<<"$anchor_summary"; then
52
+ finding "spec-functional.md records None supplied despite explicit contract anchors in planning/notes.md" \
53
+ "copy the supplied anchors verbatim into the Appendix, or correct planning/notes.md to record None supplied"
54
+ fi
55
+ anchor_tokens=$(grep -oE '`[^`]+`' <<<"$notes_anchor_lines" | sort -u || true)
56
+ while IFS= read -r token; do
57
+ [[ -n "$token" ]] || continue
58
+ grep -Fq "$token" <<<"$anchor_summary" || \
59
+ finding "spec-functional.md drops explicit contract anchor: $token" \
60
+ "copy every supplied contract anchor verbatim into the Appendix"
61
+ done <<<"$anchor_tokens"
62
+ fi
63
+ # C route (behavior-preserving change): an `## Invariant` section stands in
64
+ # for user stories, scenarios and the Behavior delta. The contract is what
65
+ # must NOT change, so there is no scenario to write and no SC-n to trace, and
66
+ # requiring them produces a fabricated spec the verifier then checks against
67
+ # two empty sets. Section body extracted once, reused by both checks below.
68
+ # Heading matched exactly, never as a substring: a feature spec is free to
69
+ # have a "Business invariants" section, and reading that as the C route would
70
+ # silently switch off every scenario check it still needs.
71
+ inv_body=$(awk '/^#+ /{
72
+ h = tolower($0); sub(/^#+[ \t]*/, "", h); sub(/^[0-9]+[.)]?[ \t]*/, "", h)
73
+ sub(/[ \t]+$/, "", h); inv = (h == "invariant"); next
74
+ } inv' "$sf")
75
+ delta_body=$(awk '/^#+ /{ d = (tolower($0) ~ /behavior delta/); next } d' "$sf")
76
+
77
+ if [[ -n "$inv_body" ]]; then
78
+ # The whole route is a before/after comparison, so a named command is the
79
+ # one thing the section cannot omit. Backticks are how the template writes
80
+ # one, and how every other DevOS check recognizes a command.
81
+ grep -q '`' <<<"$inv_body" || \
82
+ finding "Invariant section names no command" "list at least one command that must still pass: \`command\` -> baseline: exit N, M passed"
83
+ grep -qiE 'surface|none, internal' <<<"$inv_body" || \
84
+ finding "Invariant section does not state the public surface" "add the exported names/routes/flags that must not move, or state 'none, internal only'"
85
+ # Both sections present means the spec is claiming to change behavior and
86
+ # preserve it. One of the two is wrong, and guessing which is not this
87
+ # script's job.
88
+ real_delta=$(grep -E '^[[:space:]]*[-*][[:space:]]+' <<<"$delta_body" | grep -ivE '\(none\)|^[[:space:]]*[-*][[:space:]]*none' || true)
89
+ if [[ -n "$real_delta" ]]; then
90
+ finding "spec has both an Invariant and a Behavior delta with entries" \
91
+ "a spec that changes behavior is not a C route: drop the Invariant and write scenarios, or move the delta entries to their own spec"
92
+ fi
93
+ elif ! grep -qE 'Scenario( SC-[0-9]+)?:' "$sf"; then
94
+ finding "spec-functional.md has no WHEN/THEN scenarios" "each behavior and business rule needs at least one 'Scenario SC-n: name / WHEN condition / THEN outcome' line, or an ## Invariant section if this is a behavior-preserving change"
95
+ else
96
+ while IFS=: read -r n line; do
97
+ if ! grep -qE 'WHEN .+ THEN' <<<"$line"; then
98
+ finding "malformed scenario at spec-functional.md:$n (needs WHEN ... THEN ... on the line)" "rewrite as: Scenario SC-n: name / WHEN condition / THEN observable outcome"
99
+ fi
100
+ # The SC-n ID is the stable index shared by the functional spec, plan,
101
+ # and verification report. It stays in devos/ artifacts. Implementation
102
+ # tests use behavior-facing names, and the output-boundary gate keeps the
103
+ # ID out of source.
104
+ if ! grep -qE 'Scenario SC-[0-9]+:' <<<"$line"; then
105
+ finding "scenario at spec-functional.md:$n has no SC-n ID" "number it: 'Scenario SC-1: name / WHEN ... THEN ...', sequential across the spec"
106
+ fi
107
+ done < <(grep -nE 'Scenario( SC-[0-9]+)?:' "$sf")
108
+ dupes=$(grep -oE 'Scenario SC-[0-9]+:' "$sf" | sort | uniq -d)
109
+ if [[ -n "$dupes" ]]; then
110
+ finding "duplicate scenario IDs in spec-functional.md: $(tr '\n' ' ' <<<"$dupes")" "IDs are unique within a spec; renumber the later duplicate to the next free number"
111
+ fi
112
+ fi
113
+ # Normative wording, made mechanical: a requirement nobody can falsify is not
114
+ # yet a requirement, and asking the writer to police its own hedges is prose
115
+ # a gate can replace. Section-aware, because Out of Scope and Behavior delta
116
+ # hedge legitimately (a deferred item, a quoted current behavior).
117
+ # Boundaries are POSIX bracket classes, never gawk's \y: that extension
118
+ # matches nothing on darwin's awk, so the check would pass silently forever.
119
+ while IFS= read -r h; do
120
+ finding "hedge word in a requirement at spec-functional.md:${h%%:*}:${h#*:}" \
121
+ "promote the hedge to MUST/SHALL, or move the item to Out of Scope"
122
+ done < <(awk '
123
+ /^#+ / { sect = tolower($0); next }
124
+ sect ~ /out of scope|behavior delta|appendix|known volatility/ { next }
125
+ /^[[:space:]]*[-*][[:space:]]/ || /Scenario( SC-[0-9]+)?:/ {
126
+ if (tolower($0) ~ /(^|[^[:alnum:]])(should|may|probably|ideally|might|possibly)([^[:alnum:]]|$)/)
127
+ printf "%d:%s\n", FNR, $0
128
+ }' "$sf")
129
+
130
+ # A functional spec describes behavior, not implementation. Tested on
131
+ # emptiness rather than grep's status: piping through head would report the
132
+ # pipeline's last exit code, which is head's, which is always 0.
133
+ fence=$(grep -nE '^[[:space:]]*```' "$sf" | head -1)
134
+ if [[ -n "$fence" ]]; then
135
+ finding "spec-functional.md has a code block at line ${fence%%:*}" \
136
+ "describe the behavior instead; a sample belongs in a table, and implementation belongs in spec.md"
137
+ fi
138
+
139
+ # Behavior delta (present from v0.4.0 specs onward; validated only if present)
140
+ if grep -qiE '^#+ .*behavior delta' "$sf"; then
141
+ removed=$(grep -iE '^#+ *Removed|^\*\*Removed' "$sf" | grep -ivE '\(none\)|: *$' || true)
142
+ if [[ -n "$removed" ]]; then
143
+ grep -qiE 'Reason' "$sf" || \
144
+ finding "Behavior delta removes behavior without a Reason" "each Removed entry states Reason and what replaces it"
145
+ fi
146
+ fi
147
+ fi
148
+
149
+ plan="$dir/spec.md"
150
+ if [[ -f "$plan" && "$historical" -eq 0 ]]; then
151
+ if [[ -n "${anchor_tokens:-}" ]]; then
152
+ tech_requirements=$(awk '
153
+ tolower($0) ~ /^##[[:space:]].*technical requirements/ { in_requirements = 1; next }
154
+ in_requirements && /^##[[:space:]]/ { exit }
155
+ in_requirements { print }
156
+ ' "$plan")
157
+ code_map=$(awk '
158
+ tolower($0) ~ /^##[[:space:]].*code map/ { in_code_map = 1; next }
159
+ in_code_map && /^##[[:space:]]/ { exit }
160
+ in_code_map { print }
161
+ ' "$plan")
162
+ while IFS= read -r token; do
163
+ [[ -n "$token" ]] || continue
164
+ if [[ "$token" == */* || "$token" =~ \.[A-Za-z0-9]+$ ]]; then
165
+ grep -Fq "$token" <<<"$code_map" || \
166
+ finding "spec.md drops explicit contract anchor from Code Map: $token" \
167
+ "copy file-path anchors into Code Map verbatim"
168
+ else
169
+ grep -Fq "$token" <<<"$tech_requirements" || \
170
+ finding "spec.md drops explicit contract anchor from Technical Requirements: $token" \
171
+ "copy behavior anchors into Technical Requirements verbatim"
172
+ fi
173
+ done <<<"$anchor_tokens"
174
+ fi
175
+
176
+ lines=$(awk 'END { print NR }' "$plan")
177
+ if (( lines > 300 )); then
178
+ finding "spec.md capsule is $lines lines (budget 300)" "split the spec: two small specs implement more reliably than one huge one"
179
+ fi
180
+
181
+ # A task group with no Files list is invisible to check-converge.sh, which
182
+ # skips any group it cannot resolve a file list for. The group then closes
183
+ # without ever proving its work landed, so the omission disables an existing
184
+ # gate rather than merely under-documenting the plan. The heading accepts the
185
+ # colon separator as well as the numbered one, the two forms check-converge
186
+ # reads: with the numbered form alone, `### Task Group: Lexer` was not a group
187
+ # here and its missing file list was never reported.
188
+ while IFS= read -r g; do
189
+ finding "task group at spec.md:${g%%:*} has no **Files:** line" \
190
+ "list the files this group touches; check-converge skips a group with none, so it closes unverified"
191
+ done < <(awk '
192
+ /^###[[:space:]]+Task[[:space:]]+Group([[:space:]]+|:)/ {
193
+ if (open) printf "%d:%s\n", start, head
194
+ open = 1; start = FNR; head = $0; next
195
+ }
196
+ open && /^\*\*Files:\*\*/ { open = 0 }
197
+ /^##[[:space:]]/ && !/^###/ { if (open) { printf "%d:%s\n", start, head; open = 0 } }
198
+ END { if (open) printf "%d:%s\n", start, head }' "$plan")
199
+
200
+ # Local Craft is the plan's project-specific evidence. Without this gate, a
201
+ # plan can omit the section that distinguishes local reuse and syntax from
202
+ # generic advice, while still passing every other structural check.
203
+ if ! grep -qiE '^#+[[:space:]]*Local Craft' "$plan"; then
204
+ finding "spec.md has no Local Craft section" \
205
+ "record project-specific syntax, reuse, package, or algorithm evidence, or state None"
206
+ else
207
+ local_craft=$(awk '
208
+ /^#+[[:space:]]*Local Craft/ { in_craft = 1; next }
209
+ in_craft && /^#+[[:space:]]/ { exit }
210
+ in_craft { print }
211
+ ' "$plan")
212
+ if ! grep -qiE '^[[:space:]]*(-[[:space:]]*)?(none|n/a)([[:space:]]*:.*)?$' <<<"$local_craft" \
213
+ && ! grep -qE '`[^`]+:[0-9]+(-[0-9]+)?`|https?://' <<<"$local_craft"; then
214
+ finding "spec.md Local Craft has no file:line or URL evidence" \
215
+ "name the project evidence, or state None when the task is conventional"
216
+ fi
217
+ fi
218
+
219
+ # Design Convergence (step 4b) is the plan's own anti-over-engineering pass:
220
+ # the smallest design that delivers the Goal, what it fails, and what was
221
+ # added only because something failed. Unenforced, it is the section a plan
222
+ # skips exactly when it is adding the most.
223
+ if ! grep -qiE '^#+[[:space:]]*Design Convergence' "$plan"; then
224
+ finding "spec.md has no Design Convergence section" \
225
+ "add it with Direct MVP, Failed Items, Adopted Additions, Rejected Additions; 'None' is a valid answer for the last three"
226
+ else
227
+ # Presence alone proves nothing: the section passes with four labels and no
228
+ # thought behind them. This is the one line of it a script can falsify.
229
+ # Every Adopted Addition answers a Failed Item, so additions listed against
230
+ # `Failed Items: None` is the section contradicting itself, and it is the
231
+ # exact shape an unjustified abstraction takes on the way into a plan.
232
+ dcval() { awk -v k="$1" '
233
+ tolower($0) ~ "^[-*][[:space:]]*\\*\\*" k "\\*\\*" {
234
+ sub(/^[^:]*:[[:space:]]*/, ""); print; exit }' "$plan"; }
235
+ empty() { [[ -z "$1" ]] || grep -qiE '^(none|n/?a)[[:punct:]]*$' <<<"$1"; }
236
+ if ! empty "$(dcval 'adopted additions')" && empty "$(dcval 'failed items')"; then
237
+ finding "Design Convergence adopts additions while Failed Items is None" \
238
+ "every addition answers a Failed Item: name what the Direct MVP fails and the evidence it fails, or drop the addition"
239
+ fi
240
+ fi
241
+
242
+ # Scenario traceability across artifacts (spec-kit's analyze pass, made a
243
+ # gate): every SC-n the functional spec declares must surface somewhere in
244
+ # the capsule, and every SC-n the capsule cites must exist. C routes are
245
+ # exempt (an Invariant declares no scenarios by design). Both directions are
246
+ # set differences over IDs, so prose cannot blur them and the check stays mechanical.
247
+ if [[ -f "$sf" && -z "$inv_body" ]] && grep -qE 'Scenario SC-[0-9]+:' "$sf"; then
248
+ declared=$(mktemp); cited=$(mktemp)
249
+ grep -oE 'SC-[0-9]+' <<<"$(grep -E 'Scenario SC-[0-9]+:' "$sf")" | sort -u > "$declared"
250
+ grep -oE 'SC-[0-9]+' "$plan" | sort -u > "$cited" || true
251
+ while IFS= read -r sc; do
252
+ grep -qx "$sc" "$cited" || \
253
+ finding "scenario $sc is declared but covered nowhere in spec.md" \
254
+ "list it under one task group's Scenarios covered (or acceptance criteria / [human-check]) before approval"
255
+ done < "$declared"
256
+ while IFS= read -r sc; do
257
+ grep -qx "$sc" "$declared" || \
258
+ finding "spec.md cites $sc which spec-functional.md does not declare" \
259
+ "fix the ID or declare the scenario; a coverage claim pointing at nothing verifies nothing"
260
+ done < "$cited"
261
+ rm -f "$declared" "$cited"
262
+ fi
263
+ fi
264
+
265
+ if (( fail == 0 )); then
266
+ echo "PASS validate-spec: $dir well-formed"
267
+ fi
268
+ exit $fail
@@ -0,0 +1,100 @@
1
+ ---
2
+ name: init
3
+ description: "DevOS: Map an existing codebase into DevOS knowledge artifacts and wire AGENTS.md. Not for product planning."
4
+ argument-hint: "[--full] [--reverse-engineer]"
5
+ disable-model-invocation: true
6
+ ---
7
+
8
+ # /devos:init
9
+
10
+ **Scan now, starting at Step 1.** No arguments is the normal invocation, not a missing input: the repository is the input. Answering with a question about what to onboard is the one failure this command has, and it looks exactly like the command not running at all.
11
+
12
+ **Goal:** produce the three knowledge artifacts, plus the product-knowledge skeletons. Nothing else.
13
+
14
+ - `devos/product/codebase-map.md`: where things live
15
+ - `devos/product/domain-model.md`: shared vocabulary (one page max)
16
+ - `devos/standards/conventions.md`: skeleton of project choices, if it doesn't exist yet
17
+ - `devos/product/knowledge/sources.md` plus the four product artifacts: where the product's own promises are written down (Step 3b)
18
+
19
+ `--full` forces a complete re-scan. Full product-suite onboarding (mission, backlog, roadmap) is the separate `product` command, not this one.
20
+
21
+ `--reverse-engineer` (brownfield only, and only when asked): read `${CLAUDE_SKILL_DIR}/references/reverse-engineer.md` now and follow it.
22
+
23
+ ## Step 1: Incremental check
24
+
25
+ If `codebase-map.md` exists, read its `commit:` header and diff against HEAD. Nothing significant changed → say the map is current and stop. Some areas changed → refresh only those sections and the commit hash. `--full` forces a complete re-scan.
26
+
27
+ ## Step 2: Explore
28
+
29
+ **Greenfield repo:** `git ls-files` lists no source files (fresh project) → skip `codebase-map.md` entirely. There is nothing to map, and a map of intentions misdirects every future plan. Interview briefly instead: intended stack, how the project will prove it works; write only `conventions.md` (and `domain-model.md` when the user names entities). Say what you skipped and why.
30
+
31
+ **First, detect the archetypes.** Run `python3 ${CLAUDE_SKILL_DIR}/scripts/detect-archetype.py --facts` (if `${CLAUDE_SKILL_DIR}` was not expanded, it is this skill's directory) from the repo root. It prints the archetype tags, the resolved version of every framework it detects, and the project's declared check scripts, in well under a second and with no model calls. The version table fills Key dependencies below, the check table fills Verification commands in `conventions.md`, and both come from disk rather than recall. (Plain `detect-archetype.py` with no flag still prints only the JSON tag list, for callers that want just detection.) The tags decide which optional sections Step 3 emits and which areas the fan-out below covers, since a `design:*` or `style:*` hit is worth a component-inventory branch a Go CLI never pays for. Detection is reported, never enforced: an archetype it misses produces an empty section the human fills in, which beats a wrong guess stated with authority.
32
+
33
+ Understand the repo well enough to write the three artifacts: structure, entry points, domains, key dependencies, recurring patterns. On a full scan (the first run, or `--full`) of a large or multi-domain repo, read one top-level subsystem at a time and keep only a short summary of each, so exploration noise stays out of this conversation. An incremental re-scan stays single-pass, because a small delta never pays for a split. You decide the subsystem split, and there is no prescribed scan procedure.
34
+
35
+ ## Step 3: Write the artifacts
36
+
37
+ `codebase-map.md` (commit-worthy, future sessions read this instead of re-scanning):
38
+
39
+ ```markdown
40
+ # Codebase Map
41
+ <!-- Map budget: ≤120 lines. A map says where things live; an inventory of every endpoint goes stale and bloats every future plan. Overflow means you're documenting content, not location — cut detail, not domains. -->
42
+ > commit: [git rev-parse HEAD] | generated: [date]
43
+
44
+ ## Structure
45
+ [top-level dirs and their roles, entry points]
46
+
47
+ ## Domains
48
+ | Domain | Paths | Notes |
49
+
50
+ ## Key dependencies
51
+ [the `--facts` version table verbatim, then DB and external services from config. A framework named without its version is the input that makes a future plan guess.]
52
+
53
+ ## Archetype sections (emit only when detected by detect-archetype.py)
54
+ [Optional sections, each included only when the corresponding archetype is detected. Empty sections cost zero tokens on projects they don't apply to. Read `${CLAUDE_SKILL_DIR}/references/archetype-sections.md` for the section list whenever any ui:*, design:*, style:*, state:*, data:*, infra:*, or monorepo:* tag fires.]
55
+ ```
56
+
57
+ `domain-model.md`: read `${CLAUDE_SKILL_DIR}/references/shape-model.md` and follow it in this conversation (the vocabulary questions need the main agent). Entity names become the official vocabulary, one page max.
58
+
59
+ `conventions.md` (**skeleton only if missing, mandatory sections always**), following these rules.
60
+
61
+ **When the file exists**, do not re-copy the template over it and do not leave it as-is either. Append any mandatory section it lacks, and refresh Verification commands from the current `--facts` table, since a check the project gained since the last run is a check nothing is running.
62
+
63
+ **When it is missing**, copy `${CLAUDE_SKILL_DIR}/references/conventions-template.md` (if `${CLAUDE_SKILL_DIR}` was not expanded by your harness, it is this skill's own directory, the folder containing this SKILL.md) and fill in what you can infer, each marked `[inferred, confirm]`: the test runner, the architecture pattern, hard rules found in configs, the Branching & workspace pattern from existing branch names via `git branch -r`, and the `Workspace setup:` line from the lockfile present (pnpm-lock.yaml → `pnpm install --prefer-offline`, package-lock.json → `npm ci`, uv.lock → `uv sync`, Gemfile.lock → `bundle install`, Cargo and Go need none). Delete sections that do not apply.
64
+
65
+ **Verification commands**, always filled. Every row of the `--facts` **Declared checks** table goes in, verbatim and without triage, because that table is mechanical and a judgement call about which of a project's own checks matter most is how a type-check or an accessibility suite ends up never running. Then add what no manifest declares: a Terraform validate, a headless editor load, a linter with no script entry, a functional suite that only runs inside docker-compose, a CI job invoking a script directly. The table reads package.json, justfile and Makefile, so read the CI config too for commands that appear there and in no manifest. With no detectable checks at all, ask the user in one question what command proves the project works, and accept "none".
66
+
67
+ **Preview command**, filled the same way from the `--facts` preview candidates: the script that serves the app plus its URL. A UI that nothing can start is a UI nothing can check. Accept "none" for a project with no UI.
68
+
69
+ **CI & deploy topology** is mandatory when a `ci:*` tag fires, filled from the pipeline file itself: stage order, the branch/tag → environment matrix, and the per-brand or per-tenant deploy variants. That matrix is the first thing a plan needs when it touches CI and the last thing it can infer, and a project deploying four environments off three branch rules reads as a single `main` pipeline to anyone who only saw the scripts.
70
+
71
+ **Design sections are filled or explicitly emptied.** When `--facts` reports a `design:*` or `style:*` tag, `Design system / tokens`, `Component conventions` and `Styling` must not ship as template comments. Record the token source and its location if you found one, or one line saying no design system is declared and UI is improvised per feature. A detected archetype with an undeclared convention is the same gap as an undeclared check, and it is the one that makes each new screen match neither of the last two.
72
+
73
+ **Scoped rules**: where an inferred convention has a real file-glob to attach to (a language's strict-mode setting, a per-directory architecture boundary you actually found enforced), draft it as `devos/standards/rules/<NN>-<category>/<slug>.md` (format in `references/rule-format.md`) instead of a `conventions.md` line, `[inferred, confirm]` like every other inference, and never one the codebase doesn't actually exhibit, because that is a guess wearing a rule's authority.
74
+
75
+ ## Step 3b: Record where the product is documented
76
+
77
+ The three artifacts above describe what the code does. Nothing in them says what the product promises its users, which is the gap that makes a ticket written in product language unreadable to a new engineer.
78
+
79
+ Ask one question, with the candidates you found as options: where is this product documented for its users? A help centre, a published policy, a partner contract, a Notion space, a PDF. Accept "nothing published".
80
+
81
+ Then write the links, never the content. The manifest is the absorb script's file, so create it with the script and let it keep the columns:
82
+
83
+ ```bash
84
+ python3 ${CLAUDE_SKILL_DIR}/../absorb/scripts/knowledge.py --dir devos/product/knowledge init
85
+ python3 ${CLAUDE_SKILL_DIR}/../absorb/scripts/knowledge.py --dir devos/product/knowledge import --collection <slug> --listing <file> --version <label>
86
+ ```
87
+
88
+ `sources.tsv` holds one row per article: id, collection, url, source date, and the state an absorb run left it in. `devos/product/knowledge/cache/` is what a fetch writes, and the repository ignores it.
89
+
90
+ Pasting article prose into the repository is the failure mode here: it goes stale with no way to tell, and it costs every future session the tokens. `/devos:absorb` reads this file, fetches what the engineer confirms is in scope, and commits distilled rules with a source and a read date per claim.
91
+
92
+ Emit `devos/product/glossary.md`, `capabilities.md`, `personas.md` and `constraints.md` as skeletons, each one page, each with its column header and a line saying absorbing a source fills it. A term the code names differently from the product is a glossary row you can often fill from the domain model and the code alone, so fill what you can now. An empty skeleton is correct: every stage that reads these treats them as optional.
93
+
94
+ ## Step 4: Validate
95
+
96
+ Show the three artifacts (or their diffs), and any drafted rule files, to the user. Ask which inferred conventions or rules are wrong. Once confirmed, run `python3 ${CLAUDE_SKILL_DIR}/scripts/render-rule.py` on each new rule file so it reaches every installed tool's native rules surface immediately, not just Claude's.
97
+
98
+ ## Step 5: Wire the project context
99
+
100
+ Read `${CLAUDE_SKILL_DIR}/references/context.md` and follow it to put the DevOS section into `AGENTS.md`, so every session reads the artifacts, not just `/devos` commands. Requires user approval before writing.
@@ -0,0 +1,15 @@
1
+ # Codebase-map archetype sections
2
+
3
+ Emit each section only when detect-archetype.py reports the matching tag. Empty sections cost zero tokens on projects they don't apply to.
4
+
5
+ - `## UI Framework`: framework, routing, rendering mode (when ui:* detected)
6
+ - `## Component Library`: library name, version, customization approach (when design:* detected)
7
+ - `## Design System`: token location, theme structure, extension process (when design:* detected)
8
+ - `## Styling`: methodology, breakpoints, dark mode, motion (when style:* detected)
9
+ - `## State Management`: library, store shape, persistence (when state:* detected)
10
+ - `## Testing Strategy`: unit / integration / e2e / visual, tools, coverage targets (always include if detectable)
11
+ - `## Data Pipeline`: orchestrator, transformations, warehouse (when data:* detected)
12
+ - `## Infrastructure`: IaC tools, environment topology, deploy gate (when infra:* detected)
13
+ - `## CI & deploy topology`: pipeline file, stage order, which branch or tag rule selects which environment, per-brand or per-tenant deploy variants (when ci:* detected)
14
+ - `## Workspace Layout`: monorepo package graph, shared configs, which tool drives the graph and how a single package is built or tested through it (when monorepo:* detected)
15
+ - `## Runtime Environment`: how the app and its dependencies are brought up locally, the compose services or cluster context, and which checks run inside one rather than on the host (when container:* detected)
@@ -0,0 +1,42 @@
1
+ # Wire the project context
2
+
3
+ Run this in the **main agent**: the change needs user approval before writing.
4
+
5
+ ## Sources
6
+
7
+ Read from `devos/` (each may not exist, include only what does): `product/mission.md` (first paragraph of the pitch), `product/tech-stack.md`, `product/domain-model.md`, `product/codebase-map.md`, `standards/conventions.md`, `standards/rules/**/*.md`. Fallback: git remote, directory name, filesystem scan.
8
+
9
+ ## Snippet format
10
+
11
+ ```markdown
12
+ # [Project Name]
13
+
14
+ [One sentence from mission.md]
15
+
16
+ ## Project Context
17
+
18
+ Read when relevant (they're short):
19
+ - Conventions & test style: devos/standards/conventions.md
20
+ - Scoped rules: devos/standards/rules/[list each file, skipping any marked `superseded-by:` - audit trail, not guidance]
21
+ - Vocabulary: devos/product/domain-model.md
22
+ - Codebase map: devos/product/codebase-map.md
23
+ - Tech stack: devos/product/tech-stack.md
24
+
25
+ These apply to ALL work in this project, direct requests included, not just /devos:* commands. Match existing test and code style; entity names come from the domain model. **Scoped rules matter even on tools with no native glob-attach mechanism** (Codex CLI, OpenCode, Pi): this section is the fallback that makes them visible at all, since `AGENTS.md` is read natively there but `devos/standards/rules/` isn't auto-attached per file the way Copilot's own rules surface is.
26
+
27
+ ## Spec Progress
28
+
29
+ Progress is derived from the filesystem: which artifact files exist in a spec folder
30
+ (planning/notes.md, spec-functional.md, spec.md, verifications/). There is no state
31
+ file, and none should be created: it would drift from the filesystem the moment either changes.
32
+ ```
33
+
34
+ List only the files that actually exist. A reference to a missing file is worse than no reference.
35
+
36
+ ## Insertion
37
+
38
+ Write the snippet into `AGENTS.md`, the canonical project context file. Touch only the sections this skill owns (`# [Project Name]`, `## Project Context`, `## Spec Progress`). If the file has the section, replace it and show the diff for confirmation. If the file exists without the section, prepend it. If the file does not exist, create it. If an old `## Project Structure` section from a previous DevOS version exists, offer to replace it with `## Project Context`. Leave every other existing section untouched, `## Language` and any other project-specific section included, they are not this skill's concern.
39
+
40
+ `AGENTS.md` is the only context file to create or update.
41
+
42
+ **User approval required before modification.**
@@ -0,0 +1,153 @@
1
+ ---
2
+ devos-contract: 1
3
+ ---
4
+ # Project Conventions
5
+
6
+ Choices this project has made. The agent already knows general best practices; this file only records what it can't guess. Filled in by `/devos:init` or by hand; every line here is a decision, not advice. Delete sections that don't apply.
7
+
8
+ > Tip: a convention that only applies to certain files (e.g. "money is integer cents" in `billing/`) belongs in `devos/standards/rules/` instead, so it auto-attaches when a matching file is edited rather than sitting here unread. `/devos:init` drafts these for you; see `${CLAUDE_PLUGIN_ROOT}/skills/init/references/rule-format.md` for the format (`globs:`, not `paths:`, the documented `paths:` frontmatter is a confirmed Claude Code bug that silently no-ops). Keep this file for project-wide choices with no file glob to attach to.
9
+
10
+ ## Verification commands
11
+
12
+ The commands that prove this project works: the verifier runs these as its primary quality check, whatever shape the project has (test runner, site-generator build, headless editor load, linter). One per line, with the expected result. **Every declared command gets run and reported by name** — a check that belongs here and isn't listed is a check that silently never runs, which is why `detect-archetype.py --facts` lists them mechanically instead of leaving it to inference.
13
+
14
+ - `npm test`: exit 0
15
+ - <!-- The --facts check table already covers every runner it can read: package.json scripts (through the lockfile's own package manager), justfile recipes, Makefile targets. Copy those rows in and add what no manifest declares. -->
16
+ - <!-- Where the project has its own runner (`scripts/test.mjs unit`, a bash entry point, a container-only suite), record the command the project's CI actually invokes, not the underlying tool. -->
17
+ - <!-- Record where each command runs when it is not the host: `docker compose exec app pnpm test:func` (needs `docker compose up -d` first), `kubectl exec deploy/api -- pytest`, or "inside the devcontainer". A container-only suite written here as the bare command fails on the host for reasons that have nothing to do with the change, and the verifier reports that as a failing test. -->
18
+ <!-- Frontend/UI: `npm run test:a11y`, `npm run test:visual`, `npm run storybook:build` -->
19
+ <!-- Mobile: `flutter test`, `xcodebuild test`, `./gradlew test` -->
20
+ <!-- CLI: `cargo test`, `go test ./...`, `python -m pytest` -->
21
+ <!-- Data/ML: `dbt test`, `pytest`, `mlflow models validate` -->
22
+ <!-- Infra: `terraform validate`, `terraform plan`, `kubectl apply --dry-run` -->
23
+ <!-- Static analysis: `eslint .`, `ruff check .`, `clippy`, `golangci-lint run` -->
24
+ <!-- Build proof: `npm run build`, `cargo build --release`, `go build ./...` -->
25
+ - <!-- Replace with your project's proof, e.g. a static site: `zola build` exit 0, link checker clean; an editor config: `nvim --headless "+qa"` exit 0, `luacheck lua/` clean. No automated checks at all? Write "none", the verifier then reports honestly what it couldn't verify instead of guessing. -->
26
+
27
+ ## Preview command
28
+
29
+ How to start this project so it can be looked at, and the URL it serves. Without it, "drive the UI" is not an actionable instruction and every visual acceptance criterion reports UNVERIFIED by default — on the surface where the most defects are invisible to tests, lint and build.
30
+
31
+ - <!-- [inferred, confirm] e.g. `npm run dev`, serves http://localhost:5173. A project with no UI writes "none" and the verifier reports honestly instead of pretending. -->
32
+
33
+ ## Testing
34
+
35
+ - Coverage target: **80%+ on business logic** (not on glue/config)
36
+ - Test timing: critical paths during development; full coverage at feature completion, not per intermediate change
37
+ - Naming & location: `[name].test.ts` co-located | `tests/integration/[name].integration.test.ts` | `tests/e2e/[name].e2e.test.ts`
38
+ - Suite budgets: unit < 30s, integration < 2min, e2e < 10min
39
+
40
+ ## Local CI (before every push)
41
+
42
+ Lint → type-check (strict, no `any`) → tests → build. All green, fail-fast. No "fix CI" commits.
43
+
44
+ ## Commits
45
+
46
+ - Conventional commits (`feat:`, `fix:`, `chore:`); one logical change per commit; imperative subject ≤ 72 chars
47
+ - <!-- Replace with your policy: squash-merge? ticket ID in subject? signed commits? -->
48
+
49
+ ## Branching & workspace
50
+
51
+ Which branch the pipeline works on, and *where* it works: in this checkout, or in an isolated git worktree so this checkout stays yours while the agent implements.
52
+
53
+ - Spec branches: `[spec-name]` off the default branch. The pipeline never commits to the default branch
54
+ - Protected branches beyond the default: none <!-- e.g. `develop`, `release/*`: treated like the default branch, branch off them, never commit on them -->
55
+ - Workspace: default
56
+ - Workspace path: `.worktrees/`
57
+ - Workspace setup: none
58
+
59
+ **Workspace** takes exactly one of three values:
60
+
61
+ | Value | Meaning |
62
+ |---|---|
63
+ | `in-place` | Always implement in this checkout (unavailable to you while the agent works) |
64
+ | `default` | L specs get a worktree, S/M run in place |
65
+ | `worktree` | Every implementation runs in a worktree; this checkout stays free |
66
+
67
+ **Workspace path**: the folder worktrees are created in. Inside the repo by default (`.worktrees/`), so add that one line to `.gitignore`. Any directory works if you prefer them beside the checkout.
68
+
69
+ **Workspace setup**: free text, any shell command; it runs once inside each fresh worktree to make it runnable. `pnpm install --prefer-offline`, `npm ci`, `uv sync`, `bundle install`; chain a copy when the app needs untracked config. `none` = a fresh checkout already runs (Go, Cargo, plain scripts).
70
+
71
+ Filled example, a pnpm app whose owner always wants the checkout free:
72
+
73
+ - Workspace: worktree
74
+ - Workspace path: `.worktrees/`
75
+ - Workspace setup: `cp ../../myapp/.env . && pnpm install --prefer-offline`
76
+
77
+ ## Error handling
78
+
79
+ - Fail loud at boundaries (validate input, reject early); never swallow an exception without logging it
80
+ - <!-- Replace with your stance: error types vs codes? retry policy? user-facing message rules? -->
81
+
82
+ ## Dependencies
83
+
84
+ - Adding a dependency is a decision, not a default: prefer stdlib/existing deps; new ones need a one-line justification in the PR
85
+ - <!-- Add your rules: approved registries? license constraints? pinning policy? -->
86
+
87
+ ## Architecture
88
+
89
+ - Layered: Presentation → Application → Domain → Infrastructure; dependencies point inward, domain imports no framework
90
+ - <!-- Replace with your actual architecture if different (e.g. "Rails conventions, fat models thin controllers") -->
91
+
92
+ ## Performance budgets
93
+
94
+ - API p95 < 200ms; DB query p95 < 50ms; paginate every list endpoint
95
+ - Frontend: Lighthouse > 90, FCP < 1.5s, CLS < 0.1
96
+
97
+ ## API compatibility
98
+
99
+ - Breaking a published API/event requires: version bump or deprecation window (state yours: e.g. "2 releases"), affected consumers listed in the plan, migration note in the changelog
100
+ - <!-- Replace with your policy: semver? event schema registry rules? who signs off on breaking changes? -->
101
+
102
+ ## Product-specific rules
103
+
104
+ - No emoji characters in UI: use the project's icon library
105
+ - <!-- Add hard rules the agent can't infer: "all money amounts are integer cents", "user-facing text goes through i18n", "feature flags via LaunchDarkly only" -->
106
+
107
+ ## Design system / tokens
108
+
109
+ When a `design:*` or `style:*` archetype is detected, this section is **filled or explicitly emptied**, never left as this comment. "No design system declared; UI is improvised per feature" is a decision someone can see and revisit. A template comment is a decision nobody made, and the cost lands one feature at a time as each new screen matches neither of the last two.
110
+
111
+ Name the axes where "unspecified" silently resolves to a model default: **accent + neutral palette, corner-radius scale, spacing scale, shadow/elevation policy, density, type scale**. Each named value is checkable against a built screen later; "clean and modern" is not.
112
+
113
+ - <!-- [inferred, confirm] Token files, theme structure, extension process. Delete if not applicable. -->
114
+
115
+ ## Component conventions
116
+
117
+ - <!-- [inferred, confirm] Naming, folder structure, prop patterns, story vs unit vs visual test. Delete if not applicable. -->
118
+
119
+ ## Styling
120
+
121
+ - <!-- [inferred, confirm] Methodology, breakpoints, dark mode, motion. Delete if not applicable. -->
122
+
123
+ ## Accessibility
124
+
125
+ - <!-- [inferred, confirm] WCAG target, tooling, required patterns. Delete if not applicable. -->
126
+
127
+ ## Visual testing
128
+
129
+ - <!-- [inferred, confirm] Tool, baseline management, review process. Delete if not applicable. -->
130
+
131
+ ## Internationalization
132
+
133
+ - <!-- [inferred, confirm] Library, key naming, extraction. Delete if not applicable. -->
134
+
135
+ ## Data contracts
136
+
137
+ - <!-- [inferred, confirm] Schema location, migration policy, backfill process. Delete if not applicable. -->
138
+
139
+ ## CI & deploy topology
140
+
141
+ What the pipeline does, and which branch or tag reaches which environment. A plan that has to add a job, a stage, or a new environment reads this before writing one. Without it, the agent invents a single-branch pipeline that deploys nowhere real.
142
+
143
+ - <!-- [inferred, confirm] Pipeline file(s) and stage order, e.g. `.gitlab-ci.yml`: install → check → test → build → deploy → version -->
144
+ - <!-- [inferred, confirm] Branch/tag → environment matrix, one row per target, e.g. `main` → staging, `release` → prod, `v*.*.*` tag → prod release. Name the per-brand/per-tenant variants explicitly if the same code deploys several times. -->
145
+ - <!-- [inferred, confirm] Which steps are manual, which are gated on approval, and how a bad deploy is rolled back. -->
146
+
147
+ ## Infrastructure
148
+
149
+ - <!-- [inferred, confirm] Environment topology, secret handling, deploy gate. Delete if not applicable. -->
150
+
151
+ ## Vocabulary
152
+
153
+ Entity names come from `../product/domain-model.md`: code, specs, and docs use those names exactly.
@@ -0,0 +1,3 @@
1
+ # Reverse-engineer mode (init)
2
+
3
+ Brownfield only, and only when asked. Run `bash ${CLAUDE_SKILL_DIR}/scripts/reverse-engineer.sh` from the repo root. It clusters the trailing 6 months of git history by capability and writes one unreviewed spec stub per cluster into `devos/specs/archive/`. Deterministic, no model calls. Say how many stubs it wrote and that every one is **unreviewed seed material** for the behavior corpus and `/devos:status --compare`, never a work item, never promoted into active `devos/specs/`. Skip this on a greenfield repo: with no history to cluster it writes nothing useful.