@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,114 @@
1
+ #!/usr/bin/env python3
2
+ """render-rule: canonical rule files into every other tool's native surface.
3
+
4
+ render-rule.py <canonical-rule.md> [more files or directories...]
5
+ render-rule.py devos/standards/rules/<NN>-<category>/<slug>.md [...]
6
+
7
+ Renders canonical rule files (Claude Code's own globs-frontmatter format, see
8
+ references/rule-format.md) into every other tool's native rules surface, for
9
+ whichever tools are actually installed in the current project (rule 21/22).
10
+ Zero model calls. A directory argument expands to its *.md files, which is how
11
+ a preset pack applies in one command.
12
+
13
+ Detected by directory presence, same convention as the framework's own install
14
+ scripts: .github/ -> Copilot CLI. Codex, OpenCode and Pi have no native rules
15
+ surface; nothing is written for them here, init folds the rule into AGENTS.md
16
+ instead.
17
+
18
+ Exit 0 = rendered (or nothing to render), 1 = malformed input, 2 = usage.
19
+
20
+ Why Python: the shell version read each rule through cat, three awk passes and
21
+ four grep/sed/cut calls, roughly a dozen processes and a subshell each, to
22
+ split one file on its frontmatter fences. A twenty-rule preset pack paid that
23
+ two hundred and forty times. This reads the file once.
24
+ """
25
+ from __future__ import annotations
26
+
27
+ import re
28
+ import sys
29
+ from pathlib import Path
30
+
31
+ FENCE = "---"
32
+ SUPERSEDED = re.compile(r"^superseded-by:[ \t]*(.*)$", re.M)
33
+ GLOBS = re.compile(r"^globs:[ \t]*(.*)$", re.M)
34
+
35
+ NO_COPILOT = ("render-rule: no Copilot install detected here; nothing to render "
36
+ "(Codex/OpenCode/Pi fold rules into AGENTS.md via init instead).")
37
+
38
+
39
+ def render_one(src: Path) -> int:
40
+ if not src.is_file():
41
+ print(f"FAIL render-rule: canonical rule file not found: '{src}'", file=sys.stderr)
42
+ print(" fix: pass a devos/standards/rules/<NN>-<category>/<slug>.md path",
43
+ file=sys.stderr)
44
+ return 2
45
+
46
+ slug = src.stem
47
+ category_dir = src.parent.name
48
+ content = src.read_text()
49
+
50
+ if not content.startswith(FENCE + "\n"):
51
+ print(f"FAIL render-rule: '{src}' has no frontmatter", file=sys.stderr)
52
+ return 1
53
+
54
+ # The opener alone is not frontmatter. Without a closing fence the body
55
+ # comes out empty and the tool would write a frontmatter-only instruction
56
+ # file that drops the rule text.
57
+ lines = content.split("\n")
58
+ close = next((i for i, l in enumerate(lines[1:], 1) if l == FENCE), None)
59
+ if close is None:
60
+ print(f"FAIL render-rule: '{src}' has an unterminated frontmatter block "
61
+ f"(no closing ---)", file=sys.stderr)
62
+ return 1
63
+
64
+ fm = "\n".join(lines[1:close])
65
+ sup = SUPERSEDED.search(fm)
66
+ if sup:
67
+ print(f"skip {src}: superseded ({sup.group(1).strip()}) - kept as audit "
68
+ f"trail, no longer enforced")
69
+ return 0
70
+ # Everything after the second fence, trailing blank lines dropped so the
71
+ # write below controls its own ending. Fence lines inside the body are kept:
72
+ # the shell's awk had `next` on /^---$/ and so silently dropped a markdown
73
+ # horizontal rule from the rendered instruction file.
74
+ body = "\n".join(lines[close + 1:]).rstrip("\n")
75
+
76
+ m = GLOBS.search(fm)
77
+ apply_to = m.group(1).replace(" ", "") if m else "**"
78
+
79
+ if not Path(".github").is_dir():
80
+ print(NO_COPILOT)
81
+ return 0
82
+
83
+ out = Path(".github/instructions") / f"{category_dir.split('-', 1)[-1]}-{slug}.instructions.md"
84
+ out.parent.mkdir(parents=True, exist_ok=True)
85
+ out.write_text(f'---\napplyTo: "{apply_to}"\n---\n\n{body}\n')
86
+ print(f"wrote {out}")
87
+ return 0
88
+
89
+
90
+ def main(argv: list[str]) -> int:
91
+ if not argv:
92
+ print("usage: render-rule.py <rule.md> [more.md|dir ...]", file=sys.stderr)
93
+ return 2
94
+
95
+ rc_total = 0
96
+ for arg in argv:
97
+ p = Path(arg)
98
+ if p.is_dir():
99
+ members = sorted((f for f in p.rglob("*.md") if f.is_file()),
100
+ key=lambda f: str(f))
101
+ for f in members:
102
+ # A malformed file reports itself; everything else in the pack
103
+ # still renders, so a directory member never propagates 2.
104
+ if render_one(f) != 0:
105
+ rc_total = 1
106
+ else:
107
+ rc = render_one(p)
108
+ if rc != 0:
109
+ rc_total = rc
110
+ return rc_total
111
+
112
+
113
+ if __name__ == "__main__":
114
+ sys.exit(main(sys.argv[1:]))
@@ -0,0 +1,162 @@
1
+ #!/bin/bash
2
+ # reverse-engineer.sh: cluster the trailing 6 months of git history by product
3
+ # capability and write one unreviewed spec stub per cluster to
4
+ # devos/specs/archive/. Aggregate, never enumerate: one stub per capability
5
+ # cluster, not one per commit.
6
+ #
7
+ # Cluster key per changed file:
8
+ # plugins/<plugin>/skills/<skill>/... -> plugins/<plugin>/skills/<skill>
9
+ # plugins/devos/<tool>/... (copilot, codex, pi, opencode) -> <integration>
10
+ # docs/... CHANGELOG.md README.md -> excluded (process/planning,
11
+ # not a product capability); a commit touching one of these alongside a
12
+ # real cluster path still counts toward that real cluster.
13
+ # anything else -> its top-level path segment
14
+ #
15
+ # Usage: reverse-engineer.sh [--dry-run] [REPO_DIR] (default: current dir)
16
+ #
17
+ # --dry-run reports the stubs it would write and writes nothing. The output path
18
+ # is relative and fixed, so an invocation aimed at the wrong directory drops
19
+ # unreviewed stubs into a tracked specs/archive/ with no way to preview or
20
+ # redirect; that is not a hypothetical, it is how 155 of them once landed in
21
+ # this repository's own archive.
22
+ set -u
23
+
24
+ DRY_RUN=0
25
+ for a in "$@"; do
26
+ case "$a" in
27
+ --dry-run) DRY_RUN=1 ;;
28
+ *) REPO_DIR="$a" ;;
29
+ esac
30
+ done
31
+ REPO_DIR="${REPO_DIR:-.}"
32
+ cd "$REPO_DIR" || { echo "FAIL reverse-engineer: no such directory: $REPO_DIR" >&2; exit 1; }
33
+ ARCHIVE_DIR="devos/specs/archive"
34
+
35
+ # The git log below sends stderr to /dev/null, which turned "this is not a
36
+ # repository" into an empty result and then into the zero-cluster line: a
37
+ # directory with no history at all was reported as six months with none in
38
+ # it, the same greenfield reading the reference tells the operator to expect.
39
+ if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
40
+ echo "FAIL reverse-engineer: not a git repository: $(pwd)" >&2
41
+ exit 1
42
+ fi
43
+
44
+ LOG=$(git log --since="6 months ago" --name-only --pretty=format:'@@%H%x09%s' 2>/dev/null)
45
+
46
+ if [[ -z "$LOG" ]]; then
47
+ echo "no clusters found in the last 6 months"
48
+ exit 0
49
+ fi
50
+
51
+ tmp=$(mktemp -d)
52
+ trap 'rm -rf "$tmp"' EXIT
53
+
54
+ # One row per (cluster, commit-hash, subject) touch, deduped by awk below.
55
+ # cluster_key(path) prints the cluster key for a changed file, or nothing if
56
+ # the path is process/planning-only.
57
+ printf '%s\n' "$LOG" | awk -v OUT="$tmp/touches.tsv" '
58
+ function cluster_key(path, parts, n) {
59
+ if (path ~ /^plugins\/[^\/]+\/skills\/[^\/]+\//) {
60
+ n = split(path, parts, "/")
61
+ return "plugins/" parts[2] "/skills/" parts[4]
62
+ }
63
+ if (path ~ /^plugins\/devos\/(copilot|codex|pi|opencode)\//) {
64
+ n = split(path, parts, "/")
65
+ return "plugins/devos/" parts[3]
66
+ }
67
+ if (path ~ /^(roadmaps|docs)\// || path == "CHANGELOG.md" || path == "README.md") {
68
+ return ""
69
+ }
70
+ n = split(path, parts, "/")
71
+ if (n == 1) return "" # a lone root-level file (AGENTS.md, LICENSE,
72
+ # cliff.toml, justfile, .gitignore, ...) is config/meta,
73
+ # not a product capability on its own.
74
+ return parts[1]
75
+ }
76
+ /^@@/ {
77
+ line = $0
78
+ sub(/^@@/, "", line)
79
+ split(line, hs, "\t")
80
+ hash = hs[1]; subject = hs[2]
81
+ next
82
+ }
83
+ NF > 0 {
84
+ key = cluster_key($0)
85
+ if (key != "") print key "\t" hash "\t" subject >> OUT
86
+ }
87
+ '
88
+
89
+ if [[ ! -s "$tmp/touches.tsv" ]]; then
90
+ echo "no clusters found in the last 6 months"
91
+ exit 0
92
+ fi
93
+
94
+ mkdir -p "$ARCHIVE_DIR"
95
+ today=$(date +%Y-%m-%d)
96
+ cluster_count=0
97
+
98
+ for key in $(cut -f1 "$tmp/touches.tsv" | sort -u); do
99
+ cluster_count=$((cluster_count + 1))
100
+ rows="$tmp/cluster_$cluster_count.tsv"
101
+ awk -F'\t' -v k="$key" '$1 == k' "$tmp/touches.tsv" > "$rows"
102
+
103
+ file_touches=$(wc -l < "$rows" | tr -d ' ')
104
+ commit_count=$(cut -f2 "$rows" | sort -u | wc -l | tr -d ' ')
105
+
106
+ # Goal-line candidate: first feat:/fix: subject touching this cluster,
107
+ # in encounter order; skip chore(release) and bare docs:-only subjects
108
+ # whenever a better one exists.
109
+ goal_subject=""
110
+ while IFS=$'\t' read -r _ _ subject; do
111
+ case "$subject" in
112
+ feat:*|fix:*|feat\(*|fix\(*)
113
+ goal_subject="$subject"
114
+ break
115
+ ;;
116
+ esac
117
+ done < "$rows"
118
+ if [[ -z "$goal_subject" ]]; then
119
+ while IFS=$'\t' read -r _ _ subject; do
120
+ case "$subject" in
121
+ chore\(release\)*) continue ;;
122
+ *) goal_subject="$subject"; break ;;
123
+ esac
124
+ done < "$rows"
125
+ fi
126
+ [[ -z "$goal_subject" ]] && goal_subject=$(cut -f3 "$rows" | head -1)
127
+
128
+ cluster_name=$(printf '%s' "$key" | tr '/' '-')
129
+ target="$ARCHIVE_DIR/$today-$cluster_name.spec.md"
130
+ if [[ -e "$target" ]]; then
131
+ n=2
132
+ while [[ -e "$ARCHIVE_DIR/$today-$cluster_name-$n.spec.md" ]]; do
133
+ n=$((n + 1))
134
+ done
135
+ target="$ARCHIVE_DIR/$today-$cluster_name-$n.spec.md"
136
+ fi
137
+
138
+ {
139
+ echo "# ${key}"
140
+ echo ""
141
+ echo "> generated from git history, unreviewed"
142
+ echo ""
143
+ echo "## Goal"
144
+ echo "$goal_subject"
145
+ echo ""
146
+ echo "## User Story"
147
+ echo "### US-1: ${key}"
148
+ echo "**As a** user of this capability"
149
+ echo "**I want** [placeholder — review and fill in]"
150
+ echo "**So that** [placeholder — review and fill in]"
151
+ echo ""
152
+ echo "## Source"
153
+ echo "$commit_count commits, $file_touches file touches, trailing 6 months."
154
+ } > "$target"
155
+ echo "would write $target" && [[ "$DRY_RUN" -eq 1 ]] && rm -f "$target"
156
+ done
157
+
158
+ if [[ "$DRY_RUN" -eq 1 ]]; then
159
+ echo "dry-run: $cluster_count stub(s) would go to $ARCHIVE_DIR, nothing written"
160
+ else
161
+ echo "wrote $cluster_count stub(s) to $ARCHIVE_DIR"
162
+ fi
@@ -0,0 +1,29 @@
1
+ ---
2
+ name: learn
3
+ description: "When a durable lesson has nowhere to go, file it in the narrowest place, never a new file type."
4
+ argument-hint: "[the lesson, or nothing to be asked]"
5
+ ---
6
+
7
+ # /devos:learn
8
+
9
+ **Input:** `$ARGUMENTS`, or ask "what should be remembered from this?" if empty.
10
+
11
+ **Self-trigger:** the same command shape ran twice this session. Propose promoting it to a script under the project's `scripts/` or the nearest skill's `scripts/`, written once and invoked by path forever after. One line, apply on a yes, then route it through the normal steps below, usually a one-line note in `codebase-map.md` naming the script. Twice is the threshold, since a sequence that ran once is a guess about the future.
12
+
13
+ No new artifact type is ever created here. Every lesson lands somewhere DevOS already reads: a check in `test-gates.sh` or `evals/check-*.sh`, `conventions.md`, `devos/standards/rules/`, `domain-model.md`, `codebase-map.md`, the active spec's own `decisions.md`, or a new skill (handed off, not authored inline). If none fit, the lesson is dropped and you're told why.
14
+
15
+ ## Step 1: Score
16
+
17
+ Read `references/scoring.md` and apply its provenance rule, then its Keep, Narrow, Drop, and Unverified verdicts. Stop with the reference's one-line explanation when a verdict is not Keep or Narrow. Narrow uses the narrowest durable destination.
18
+
19
+ ## Step 2: Reconcile
20
+
21
+ Read `references/destinations.md`'s reconciliation rule. Compare the lesson with the likely destination and classify it as new, covered, updates, or supersedes before writing anything.
22
+
23
+ ## Step 3: Route
24
+
25
+ Read `references/destinations.md` and take the first matching destination. Write to exactly one place. A mechanically checkable lesson becomes an enforced test or check, not a prose duplicate. Follow the reference's budget, reversal, handoff, and no-fit rules.
26
+
27
+ ## Step 4: Report
28
+
29
+ One line: destination, reconciliation classification, and (for supersedes) what it replaced. No destination fit → "Dropped: [why]", nothing written.
@@ -0,0 +1,43 @@
1
+ # Reconciling and routing a kept lesson
2
+
3
+ ## Reconciliation
4
+
5
+ Read the likely destination file (or files, if more than one plausibly fits) before writing anything. Classify against what's already there:
6
+
7
+ - **new**: nothing in the destination says this, in any form. Write it.
8
+ - **covered**: the destination already states this fact, possibly in different words. Write nothing. Report where it already lives. Compare the meaning, not the wording, before choosing `new`.
9
+ - **updates**: the destination has a related fact that has changed (a tool was swapped, a threshold moved). Replace the old line in place. Do not leave both.
10
+ - **supersedes**: the destination has an *older, now-wrong* entry this lesson directly contradicts and corrects. Replace it, and leave the trail **in the file**, not only in the report: one trailing clause on the new line, in the style `conventions.md` already uses (`(Said "six" while listing seven until 0.8.4.)`). The reversal is itself the knowledge: delete it and the next reader re-proposes what was already tried and reverted. One clause, never a changelog.
11
+
12
+ Choose `covered` before `updates` or `supersedes` when the existing entry already says the same current fact. A lesson that reconciles as `covered` is the success case, not a failure: it proves the artifact didn't need a second copy.
13
+
14
+ ## Destination table
15
+
16
+ Take the first row that fits, reading top down.
17
+
18
+ | Kind of lesson | Destination | Notes |
19
+ |---|---|---|
20
+ | **Mechanically checkable**: a script could decide it (an exit code, a shape, a file that must exist, a pattern that must not appear) | A test in `plugins/devos/scripts/gates/test-gates.sh`, or a check in `evals/check-*.sh` wired into `just verify` | The check replaces the prose entry; don't write both. It must fail against the pre-fix code (`conventions.md`, Testing). |
21
+ | Project-wide choice, no file glob to scope it | `devos/standards/conventions.md` | Append/replace the relevant section line; match the file's own terse, decision-not-advice style. |
22
+ | Convention scoped to specific files | `devos/standards/rules/<NN>-<category>/<slug>.md` | Same format and category taxonomy as `/devos:init`'s rule drafting (see `${CLAUDE_PLUGIN_ROOT}/skills/init/references/rule-format.md`). Run `python3 ${CLAUDE_PLUGIN_ROOT}/skills/init/scripts/render-rule.py` after writing so it reaches every installed tool, not just Claude. |
23
+ | Vocabulary (entity name, relationship) | `devos/product/domain-model.md` | One line, matching its existing entries; never restate an entity that's already named. |
24
+ | Structural fact (where something lives, a dependency) | `devos/product/codebase-map.md` | Budgeted at ≤120 lines: see "Writing into a budgeted destination" below before appending. |
25
+ | Reusable workflow, not a fact | Nowhere (hand off) | This skill states the hand-off and stops; it does not author the new skill. |
26
+ | Gotcha specific to the in-progress spec | `SPEC_DIR/decisions.md` | Already `implement`'s own mechanism (a `- D-N: [decision], why` line); not a new destination, just the existing one. |
27
+ | None of the above fit | Nowhere | Report "Dropped: [reason]." A lesson with no real destination is not durable enough to keep (see `scoring.md`). |
28
+
29
+ ### Writing into a budgeted destination
30
+
31
+ Two destinations carry a hard line budget, because nearly every command loads them: `codebase-map.md` at 120 lines and `domain-model.md` at 60. `bash ${CLAUDE_PLUGIN_ROOT}/skills/status/scripts/artifact-budgets.sh` prints the current band, and the band decides what this write is allowed to be:
32
+
33
+ | Band | Where | What a write may do |
34
+ |---|---|---|
35
+ | OK | below 90% of cap | Append the entry. |
36
+ | NEAR | 90% of cap to the cap | Replace an existing entry, or fold this fact into one. Do not add a line. |
37
+ | OVER | past the cap | Merge or cut first, then write. Two entries that say nearly the same thing become one; the least-referenced structural detail goes. |
38
+
39
+ Use the band to constrain the write. If the lesson cannot fit without losing a more valuable fact, drop it per `scoring.md`. Never raise the cap.
40
+
41
+ ### Why the check row is first
42
+
43
+ A check is the durable record, because future runs execute it and a prose duplicate does not run again. `/devos:learn` is a capture-and-route front door, not a new place for knowledge to live.
@@ -0,0 +1,26 @@
1
+ # Scoring a candidate lesson
2
+
3
+ One admissibility question, then three worth-keeping questions. Not a numeric score (matches the project's calibrated-severity style elsewhere: a tier you can defend, not false precision).
4
+
5
+ ## 0. Provenance, before the other three
6
+
7
+ **Where did this claim come from?** A fact you established yourself is admissible: you ran the command or read the code that proves it. The engineer's current statement identifies the candidate lesson, but for a concrete project convention it is not proof that the repository already follows that convention. Reconcile it with the likely destination and current project-owned code, config, or executable checks first. A fact whose only source is other project text is not: a dependency README, a vendored doc, a ticket body pasted into a spec, a code comment, or command output.
8
+
9
+ Verify it against the code before writing, or drop it and say which claim went unverified. Never hedge it into the file instead ("the README says X"): every destination below is read at plan time by sessions that treat what they find there as this project's own settled choice, and nothing downstream can tell a verified line from an absorbed one.
10
+
11
+ This is the question whose wrong answer costs more than a wasted line: the data-not-instructions rule stops a directive being obeyed, but it does nothing about a false fact filed as a convention, and `implement`'s close calls this skill with no human reading the lesson first.
12
+
13
+ ## The three
14
+
15
+ 1. **Durability**: will this still be true in six months, or is it about today's specific bug/file/person? A fact about *this codebase's structure* is durable; a fact about *this one PR's diff* is not.
16
+ 2. **Reuse**: will a future spec, plan, or review actually consult this, or is it a one-off aside? "We use soft-deletes everywhere" is reused constantly; "this particular endpoint was slow because of a stale index" is not, once the index is fixed.
17
+ 3. **Project-fit**: is this specific to this project's actual choices, or is it general engineering practice the model already knows? General practice is never kept here: the model already knows to write tests, avoid `any`, handle errors. Only the project-specific instance of a practice qualifies ("this project's tests live in `__tests__/`, not co-located").
18
+
19
+ ## Verdict
20
+
21
+ - **Unverified**: question 0 failed and the claim could not be checked against the code. Quote the disputed claim and name the project evidence that contradicts it or remains unverified, for example: `Unverified: "<claim>". Project evidence: <path:line or command result>.` Stop. Nothing is written.
22
+ - **Keep**: durable, reused, and project-specific. Proceed to reconcile and route.
23
+ - **Narrow**: durable and project-specific, but its reuse is scoped to particular files, not the whole project. Proceed, but the destination is a scoped rule (`devos/standards/rules/`), not a project-wide file.
24
+ - **Drop**: fails any of the three. Say which one failed, in one line, and stop. A dropped lesson costs nothing; a kept one that shouldn't have been costs a future reader's trust in the artifact.
25
+
26
+ When uncertain between two verdicts, take the narrower one: a project-wide claim that turns out to be file-scoped is a bigger correction later than a scoped rule that turns out to generalize.
@@ -0,0 +1,40 @@
1
+ ---
2
+ name: product
3
+ description: "DevOS: Plan the product mission, roadmap, and tech stack. Not for mapping an existing codebase."
4
+ argument-hint: "[product description]"
5
+ disable-model-invocation: true
6
+ ---
7
+
8
+ # [0] Product Planning Process
9
+
10
+ You are helping to plan and document the mission, roadmap and tech stack for the current product. This will include:
11
+
12
+ - **Gathering Information**: The user's product vision, user personas, problems and key features
13
+ - **Mission Document**: Take what you've gathered and create a concise mission document
14
+ - **Roadmap**: Create a phased development plan with prioritized features
15
+ - **Tech stack**: Establish the technical stack used for all aspects of this product's codebase
16
+
17
+ This process will create these files in `devos/product/` directory.
18
+
19
+ ### PHASE 1: Gather Product Requirements
20
+
21
+ Work through `${CLAUDE_SKILL_DIR}/references/planner.md` (if `${CLAUDE_SKILL_DIR}` was not expanded, it is this skill's own directory) to create comprehensive product documentation (mission.md, roadmap.md, backlog.md, backlog category files, tech-stack.md under `devos/product/`). Take everything the user gave about the product idea, purpose, features, target users, and any other details.
22
+
23
+ ### PHASE 2: Inform the user
24
+
25
+ After all steps are complete, output the following to inform the user:
26
+
27
+ ```
28
+ Your product planning is all set!
29
+
30
+ ✅ Product mission: `devos/product/mission.md`
31
+ ✅ Product roadmap: `devos/product/roadmap.md`
32
+ ✅ Product backlog: `devos/product/backlog.md`
33
+ ✅ Product categories: `devos/product/backlog/*.md`
34
+ ✅ Product tech stack: `devos/product/tech-stack.md`
35
+
36
+ 📋 **Roadmap** contains features planned in milestones.
37
+ 📦 **Backlog** contains features not yet assigned to a milestone.
38
+
39
+ NEXT STEP 👉 `/devos:init` to define the domain model (business vocabulary)
40
+ ```
@@ -0,0 +1,54 @@
1
+ You are a product planning specialist. Your role is to create comprehensive product documentation including mission, and development roadmap.
2
+
3
+ # Product Planning
4
+
5
+ ## Core Responsibilities
6
+
7
+ 1. **Gather Requirements**: Collect from user their product idea, list of key features, target users and any other details they wish to provide
8
+ 2. **Create Product Documentation**: Generate mission, and roadmap files
9
+ 3. **Define Product Vision**: Establish clear product purpose and differentiators
10
+ 4. **Plan Development Phases**: Create structured roadmap with prioritized features
11
+ 5. **Document Product Tech Stack**: Document the tech stack used on all aspects of this product's codebase
12
+
13
+ ## Workflow
14
+
15
+ ### Step 1: Gather Product Requirements
16
+
17
+ Read and follow `${CLAUDE_PLUGIN_ROOT}/workflows/product/gather-product-info.md`.
18
+
19
+ ### Step 2: Create Mission Document
20
+
21
+ Read and follow `${CLAUDE_PLUGIN_ROOT}/workflows/product/create-product-mission.md`.
22
+
23
+ ### Step 3: Create Development Roadmap
24
+
25
+ Read and follow `${CLAUDE_PLUGIN_ROOT}/workflows/product/create-product-roadmap.md`.
26
+
27
+ ### Step 4: Document Tech Stack
28
+
29
+ Read and follow `${CLAUDE_PLUGIN_ROOT}/workflows/product/create-product-tech-stack.md`.
30
+
31
+ ### Step 5: Final Validation
32
+
33
+ Verify all files created successfully:
34
+
35
+ ```bash
36
+ # Validate core product files
37
+ for file in mission.md roadmap.md tech-stack.md backlog.md; do
38
+ if [ ! -f "devos/product/$file" ]; then
39
+ echo "Error: Missing $file"
40
+ else
41
+ echo "✓ Created devos/product/$file"
42
+ fi
43
+ done
44
+
45
+ # Validate category files
46
+ category_count=$(ls devos/product/backlog/*.md 2>/dev/null | wc -l)
47
+ echo "✓ Created $category_count category files in devos/product/backlog/"
48
+
49
+ echo "Product planning complete! Review your product documentation in devos/product/"
50
+ ```
51
+
52
+ ## User Standards & Preferences Compliance
53
+
54
+ If `devos/standards/conventions.md` exists, make sure the product mission and roadmap don't conflict with the choices recorded there.
@@ -0,0 +1,77 @@
1
+ ---
2
+ name: review
3
+ description: "DevOS: Review a diff, working tree, or spec folder against the project's conventions and behavior; --gaps checks a spec is finished."
4
+ argument-hint: "[spec-name | files | --base branch | a..b | --lean | --gaps]"
5
+ disable-model-invocation: true
6
+ ---
7
+
8
+ # /devos:review
9
+
10
+ The model already knows general review practice, and most harnesses now ship a reviewer of their own. What neither can know without reading this project's files is what this project **declared**: its rules, its vocabulary, its current behavior. That brief is what this command produces, and the review runs in a fresh context on it, with the findings routed back here.
11
+
12
+ **Target:** $ARGUMENTS
13
+
14
+ `${CLAUDE_SKILL_DIR}` is this skill's own directory. If it was not expanded, use the directory that holds this file.
15
+
16
+ Flag parsing happens before any resolution, so a flag never reaches a command or a `git` invocation:
17
+
18
+ - `--lean`: after the correctness pass, run a second pass hunting over-engineering only (ponytail-review style: dead code, reinvented stdlib, speculative abstractions), reported as a separate section. Off by default. Lean findings are noise while correctness is still open.
19
+ - `--gaps`: check completeness instead of quality. Read `${CLAUDE_SKILL_DIR}/references/gaps.md` and follow it, then stop. Use it for a spec whose implementation was cut short or a change made outside the pipeline.
20
+
21
+ Current diff, staged + unstaged (default target when no argument was given):
22
+
23
+ ```!
24
+ git diff --name-only HEAD 2>/dev/null; git diff --name-only --cached 2>/dev/null
25
+ ```
26
+
27
+ ## Step 1: Resolve the target to a file list
28
+
29
+ Target resolution table: empty → the injected diff (fallback `HEAD~1`, else stop and ask); spec folder name → the files in spec.md's `**Files:**` sections plus the spec artifacts themselves; file paths → those files; `--base [branch]` or `a..b` → diff since `git merge-base` (state the base used).
30
+
31
+ A `--base` naming the checked-out branch resolves to an empty diff: say so and ask for the real base rather than reviewing nothing.
32
+
33
+ Then, if no spec was named, grep the resolved files against the `**Files:**` sections of `devos/specs/*/spec.md`. Exactly one non-archived spec claims any of them → review in spec mode against it, say which. Zero or several → plain mode, say so in one line.
34
+
35
+ **Hot-path bias.** Before reviewing, read recently-changed paths (`git log --since="6 months ago" --name-only --pretty=format:`) and bias attention toward them: a file changed often is where defects cluster, so it earns scrutiny over a quiet file of the same size.
36
+
37
+ ## Step 2: Build the ground-truth brief
38
+
39
+ Read these, skip whichever are absent, and **quote the lines that bear on the resolved files**. A path is not a brief: whatever reviews this may not open the file, and an unquoted rule is one the review will not cite.
40
+
41
+ - `devos/standards/conventions.md`: the project's rules. A finding citing a conventions line is first-class.
42
+ - `devos/standards/rules/`: scoped rules filed by path glob. Include one only where its `globs:` matches a resolved file, and name the rule's own path with it.
43
+ - `devos/product/domain-model.md`: the official entity names. A new `Users` where the model says `User` is vocabulary drift, and drift is a finding.
44
+ - `devos/product/behaviors/`: current observable behavior for the capabilities the change touches. Code contradicting a behavior file is a finding to raise, never silently resolved in either direction.
45
+ - Spec mode only: `spec-functional.md` (the contract) and `spec.md` (the plan). Change-vs-contract gaps outrank style.
46
+
47
+ Found none of them? The brief is `none, generic practice only, run /devos:init`. Say that in the relay instead of hiding it: a review with nothing to cite is the generic one any model gives for free, and the caller needs to know that is what they got.
48
+
49
+ `plugins/devos/scripts/evidence-router.py` narrows that brief to a reading list. `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/evidence-router.py --task "<the change in one line>" --files <the resolved files> [--spec <spec folder>]` prints the blocks that bear on the change, quoted with their line ranges. A long `conventions.md` or a change touching many behavior files is what it is for.
50
+
51
+ It is a reading list rather than a verdict, and it never replaces the quote-the-line rule above, because a rule it dropped is still a finding once you read it. It is not a gate, so its exit code carries no verdict.
52
+
53
+ ## Step 3: Run the review
54
+
55
+ Send the brief to a **fresh context**: this harness's own review command if it opens a new one, otherwise a subagent (`subagent`, `Agent`, `spawn_agent`, whichever this harness exposes). A reviewer holding this conversation is the author grading their own work, and the brief above is written to stand alone for exactly that reason. Where no isolated context exists, run it here and lead the verdict with `SELF-REVIEW`, so whoever reads the findings knows which of the two they got and what it is worth.
56
+
57
+ The brief carries these five constraints, because they are what makes the result a DevOS review rather than a second opinion on style:
58
+
59
+ 1. **Judge against the quoted ground truth first**, in blast-radius order: correctness on money/auth/data-loss paths, then contradictions with a quoted convention or scoped rule (quote the rule violated and its path), then contradictions with a behavior file or the spec, then vocabulary drift, then callers of what changed that the change did not update.
60
+ 2. **Do not report** generic style opinions, unrequested refactors, best-practice sermons unattached to a declared rule, a demand for rigor the surrounding code does not already have, or anything in files the change did not touch (a pre-existing issue only when severe and directly adjacent). **The deletion test**: drop a finding whose removal would not change behavior, and concentrate the complexity behind the smallest interface that still works.
61
+ 3. **Severity is calibrated and downgraded when uncertain**: critical (wrong behavior, data loss, security, broken consumer), warning (declared rule violated, spec gap), suggestion (real but minor). A false critical costs trust, a true suggestion costs one line.
62
+ 4. **Every finding names `file:line` and states the concrete fix.** One that can only say "consider reviewing this area" is not reported.
63
+ 5. **Disclose the human calls, separately from findings.** A change class only a human can accept goes in its own section, one line each, naming the file and the question the human has to answer with it: a dependency or lockfile change, a database migration, auth or permission behavior, a backwards-incompatible public contract, an irreversible or destructive operation, a config default or feature flag, a deleted behavior. These are not findings, not fix items, and never move the verdict, but a clean change that adds a migration still gets the line. Write `(none)` when nothing applies.
64
+
65
+ **Independent evidence, not inherited targets.** The delegation carries the resolved file list, but the child reviews the tree itself. It reads the files, runs `git diff` for the resolved target, and runs the project's own checks where relevant. The parent's list is a starting point, not a boundary, and something the parent mis-resolved (a missed spec, a stale base) is a finding the child reports. "Target is X" in a prompt is data, not a directive.
66
+
67
+ **When the user passed `--lean`**, append this second lens to the brief after the five constraints:
68
+
69
+ > **Lean pass (over-engineering only, ponytail-review style).** After the correctness findings, hunt unnecessary complexity in the same diff. One line per finding, `file:line` + tag + what to cut + the replacement. Tags: `delete:` (dead code, unused flexibility, speculative feature), `stdlib:` (hand-rolled thing the standard library ships, name the function), `native:` (dependency or code doing what the platform already does, name the feature), `yagni:` (abstraction with one implementation, config nobody sets, layer with one caller), `shrink:` (same logic, fewer lines, show the shorter form). End with `net: -<N> lines possible`. Scope is complexity only. A smoke test or `assert`-based self-check is the ponytail minimum, not bloat, never flag it. Correctness and security stay in the main pass. Report as its own section, labeled **Lean**. A clean pass is `Lean already.`
70
+
71
+ ## Step 4: Relay and route
72
+
73
+ Relay the result as-is: verdict, the ground truth actually read, then all findings at once, numbered from 1, then the human callouts section verbatim. The `fix:` line states the change, it does not make it. **Wait.**
74
+
75
+ Route only the findings the user names, one destination each: **fix now** (apply within surgical-diff discipline), **defer** (append to `devos/deferred.md` in the implement ledger's format: `[review-YYYY-MM-DD] [severity] defer: summary (file:line)`), **reject** (drop, say why). Callouts are not routable: relay them and leave the decision to the user. Candidates the deletion test drops are recorded in `devos/deferred.md` as deferrals so they stop resurfacing in later reviews. Confirming one finding confirms only that one. After each, print the numbers still unrouted.
76
+
77
+ A finding that no longer applies when the fix round reaches it is reported stale and dropped, never forced through. Close a fix-now round with what was fixed, what was deferred and why, and the check that ran. Only deferrals reach disk, so when the user stops with findings left, say once that re-running re-derives whatever is still unfixed.
@@ -0,0 +1,26 @@
1
+ # Gap scan
2
+
3
+ Is this implementation actually finished? Detects placeholders, TODOs, and spec-vs-code gaps.
4
+
5
+ **Spec:** $ARGUMENTS
6
+
7
+ ## Step 1: Resolve the spec
8
+
9
+ - Spec given → `Glob devos/specs/*[spec-name]*` and use the match (ask only if ambiguous).
10
+ - No spec given → list available specs and ask which one. **Wait.**
11
+ - No `spec.md` in the folder → stop: there's no implementation plan to verify against; point to `/devos:implement`.
12
+
13
+ ## Step 2: Verify completeness
14
+
15
+ Apply the `verifier` agent's completeness lens, `${CLAUDE_PLUGIN_ROOT}/agents/verifier.md`, to this brief:
16
+
17
+ ```
18
+ SPEC_DIR: devos/specs/[spec-name]
19
+ Lens: completeness only (skip the quality lens).
20
+ Verify the implementation against ${SPEC_DIR}/spec.md and write
21
+ ${SPEC_DIR}/verifications/verification.md.
22
+ ```
23
+
24
+ ## Step 3: Relay
25
+
26
+ Show the verdict line and the report path. If placeholders were found, flag them as blocking: code that compiles but does nothing.
@@ -0,0 +1,58 @@
1
+ ---
2
+ name: spec
3
+ description: "DevOS: interview the engineer, capture a feature's requirements, and produce spec-functional.md. Not for a small change."
4
+ argument-hint: "[feature description | spec-name]"
5
+ ---
6
+
7
+ # /devos:spec
8
+
9
+ Run in the **main agent**: interview the engineer and produce `planning/notes.md` plus `spec-functional.md` in one run, since the questions need the conversation that asks them.
10
+
11
+ **Feature:** $ARGUMENTS
12
+
13
+ ## Step 0: Spec folder
14
+
15
+ Set `SPEC_DIR` to a matching existing folder. For a new feature, create `devos/specs/YYYY-MM-DD-[feature-name-kebab-case]/planning/`. If the same feature has a folder under another date, ask whether to continue it or create a new one, then wait. With no feature description, ask what to spec.
16
+
17
+ If `devos/product/roadmap.md` exists, read `references/roadmap-link.md` and follow it.
18
+
19
+ ## Step 1: Read context, summarize, and ask in one round
20
+
21
+ Read in parallel, skipping missing files: `devos/product/mission.md`, `roadmap.md`, `tech-stack.md`, `backlog.md`, `domain-model.md`, `codebase-map.md`, `glossary.md`, `capabilities.md`, `personas.md`, `constraints.md`, `decisions.md`, any `knowledge/` page whose subject the ask names, and `behaviors/<capability>.md` for the capabilities this feature touches. Use `domain-model.md` entity names as the official vocabulary, and treat a `decisions.md` row as settled instead of reopening it. If the user pasted a ticket, extract its requirements, constraints, and out-of-scope items first.
22
+
23
+ Then one round, not two. Open with a 3-5 line summary of the feature as you read it, and put any open questions in the same message. A separate "is this right?" followed by a separate question round spends two engineer turns to learn one thing.
24
+
25
+ Ask only where a wrong guess would be expensive: a different actor, a money, auth, or data-loss path, a public interface other code depends on, or a choice between two designs that both work. Everything else is your call, and you state the decision in the spec for the engineer to correct. If real ambiguity remains after the ticket or the summary, read `references/question-craft.md` for how to shape the round.
26
+
27
+ A request that contradicts the code, the conventions, or an obvious constraint is the one case that always earns a question, asked in plain words with what you found and what you propose.
28
+
29
+ ## Step 2: Capture the interview record
30
+
31
+ `planning/notes.md` is the record of the conversation, not a draft of the spec. Before synthesis, it holds three things and nothing else:
32
+
33
+ - **Q&A**: the questions you actually asked and the answers you got, verbatim where the answer carried a decision.
34
+ - **Explicit contract anchors**: any function or method names, signatures, public API or event names, and target file paths the engineer supplied, copied verbatim. Mark absent ones unspecified rather than inferring them.
35
+ - **Open assumptions**: the guesses still unconfirmed, one line each, so a guess is not recorded as a settled requirement.
36
+
37
+ It does not hold functionality, business rules, edge cases, or out-of-scope. Those are the spec, and the same agent writes both in one turn, so a second copy in the notes is forty lines that get rewritten immediately. Real L features in this repo carried 26 to 47 lines of exactly that duplication. The interview record alone is about a dozen.
38
+
39
+ ## Step 2b: Prototype, only when a screen or interactive flow is added
40
+
41
+ If this feature adds a screen, a dialog, or an interactive flow, read `references/prototype.md` and follow it. **Otherwise skip this step without reading that file**: backend, CLI, API, data, and infrastructure work never prototype.
42
+
43
+ ## Step 3: Write the spec
44
+
45
+ Write `SPEC_DIR/spec-functional.md` yourself, in this same turn. You hold the interview, so a second pass re-reading the notes to rewrite them spends a full pass restating what you already know. The behavior is written here, once, and does not belong in the notes.
46
+
47
+ `references/write-spec.md` carries the template, the output rules, how to carry an engineer override or an unconfirmed assumption across from the notes, the re-read list, and the `validate-spec.sh` run with its fix-every-FAIL instruction.
48
+
49
+ ## Step 4: Report
50
+
51
+ Confirm the artifacts exist, including `planning/prototype.html` when Step 2b ran. Print the phase status and hand off. This is not a gate: the plan approval in `implement`'s Phase A is the single place the engineer says go, so do not ask for a second one here.
52
+
53
+ ```
54
+ 📊 [spec-name]: [✅/🔄/⏳ per phase: planning/notes.md, spec-functional.md, spec.md, verifications/verification.md]
55
+ 🎯 Next: /devos:implement [spec-name]
56
+ ```
57
+
58
+ On Pi the next command is `/skill:implement [spec-name]`, since Pi skill names cannot carry the `devos:` prefix. Print the spelling this harness actually accepts.