@tduyng/pi-devos 0.13.6 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (100) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/README.md +26 -33
  3. package/package.json +1 -2
  4. package/plugins/devos/agents/verifier.md +4 -30
  5. package/plugins/devos/pi/extension/devos.ts +16 -26
  6. package/plugins/devos/scripts/check-evidence-router.sh +7 -1
  7. package/plugins/devos/scripts/evidence-router.py +5 -3
  8. package/plugins/devos/scripts/gates/check-dod-core.sh +5 -3
  9. package/plugins/devos/scripts/gates/check-port-source.sh +1 -1
  10. package/plugins/devos/scripts/gates/check-scenario-coverage.sh +10 -8
  11. package/plugins/devos/scripts/gates/phase-gate.sh +6 -6
  12. package/plugins/devos/scripts/gates/plan-template-check.py +6 -12
  13. package/plugins/devos/scripts/gates/spec-contract.sh +19 -0
  14. package/plugins/devos/scripts/gates/spec-template-check.py +8 -21
  15. package/plugins/devos/scripts/gates/suite/01-dod.sh +485 -0
  16. package/plugins/devos/scripts/gates/suite/02-integrity.sh +310 -0
  17. package/plugins/devos/scripts/gates/suite/03-archetype.sh +255 -0
  18. package/plugins/devos/scripts/gates/suite/04-spec-validator.sh +183 -0
  19. package/plugins/devos/scripts/gates/suite/05-requires.sh +360 -0
  20. package/plugins/devos/scripts/gates/suite/06-clarify-adapters.sh +435 -0
  21. package/plugins/devos/scripts/gates/suite/07-lint-evals.sh +350 -0
  22. package/plugins/devos/scripts/gates/suite/08-converge.sh +591 -0
  23. package/plugins/devos/scripts/gates/suite/09-quality.sh +516 -0
  24. package/plugins/devos/scripts/gates/suite/10-eval-harness.sh +679 -0
  25. package/plugins/devos/scripts/gates/test-gates.sh +23 -4253
  26. package/plugins/devos/scripts/gates/test-integrity-rubric.sh +1 -1
  27. package/plugins/devos/scripts/gates/test-phase-gate.sh +5 -5
  28. package/plugins/devos/skills/build/SKILL.md +3 -3
  29. package/plugins/devos/skills/build/references/refactor.md +1 -1
  30. package/plugins/devos/skills/build/references/routes.md +4 -4
  31. package/plugins/devos/skills/frame/SKILL.md +22 -39
  32. package/plugins/devos/skills/frame/references/template.md +115 -0
  33. package/plugins/devos/skills/implement/SKILL.md +4 -4
  34. package/plugins/devos/skills/implement/references/dod.md +6 -1
  35. package/plugins/devos/skills/implement/references/implement.md +3 -1
  36. package/plugins/devos/skills/implement/references/plan.md +9 -27
  37. package/plugins/devos/skills/implement/references/resume.md +1 -1
  38. package/plugins/devos/skills/implement/references/verify-close.md +4 -3
  39. package/plugins/devos/skills/implement/scripts/ops-log.sh +2 -2
  40. package/plugins/devos/skills/implement/scripts/validate-spec.sh +17 -65
  41. package/plugins/devos/skills/init/references/context.md +1 -1
  42. package/plugins/devos/skills/review/SKILL.md +24 -47
  43. package/plugins/devos/skills/review/references/comments.md +13 -0
  44. package/plugins/devos/skills/review/references/reviewer.md +124 -0
  45. package/plugins/devos/skills/review/references/routing.md +35 -0
  46. package/plugins/devos/skills/review/scripts/__pycache__/prepare.cpython-313.pyc +0 -0
  47. package/plugins/devos/skills/review/scripts/prepare.py +763 -0
  48. package/plugins/devos/skills/spec/SKILL.md +5 -6
  49. package/plugins/devos/skills/spec/references/write-spec.md +36 -51
  50. package/plugins/devos/skills/spec/scripts/clarify.sh +4 -4
  51. package/plugins/devos/skills/status/SKILL.md +4 -4
  52. package/plugins/devos/skills/status/scripts/check-requires.py +4 -4
  53. package/plugins/devos/skills/status/scripts/convention-usage.sh +1 -1
  54. package/plugins/devos/skills/status/scripts/quality-correlation.sh +2 -25
  55. package/plugins/devos/scripts/gates/check-handoff.sh +0 -215
  56. package/plugins/devos/skills/design-taste/SKILL.md +0 -55
  57. package/plugins/devos/skills/design-taste/references/tells.md +0 -85
  58. package/plugins/devos/skills/design-taste/scripts/slop-scan.py +0 -305
  59. package/plugins/devos/skills/docs/SKILL.md +0 -22
  60. package/plugins/devos/skills/docs/references/backfill.md +0 -54
  61. package/plugins/devos/skills/docs/references/init.md +0 -43
  62. package/plugins/devos/skills/docs/references/status.md +0 -71
  63. package/plugins/devos/skills/docs/references/update.md +0 -80
  64. package/plugins/devos/skills/explain/SKILL.md +0 -45
  65. package/plugins/devos/skills/explain/references/quiz.md +0 -21
  66. package/plugins/devos/skills/frame/references/boundaries.md +0 -53
  67. package/plugins/devos/skills/frame/references/decompose.md +0 -96
  68. package/plugins/devos/skills/frame/references/impact.md +0 -43
  69. package/plugins/devos/skills/frame/references/interrogate.md +0 -68
  70. package/plugins/devos/skills/product/SKILL.md +0 -40
  71. package/plugins/devos/skills/product/references/planner.md +0 -54
  72. package/plugins/devos/skills/surgical-diff/SKILL.md +0 -23
  73. package/plugins/devos/skills/test-integrity/SKILL.md +0 -26
  74. package/plugins/devos/skills/verification-evidence/SKILL.md +0 -17
  75. package/plugins/devos/workflows/common/backlog-file-structure.md +0 -44
  76. package/plugins/devos/workflows/common/category-file-structure.md +0 -41
  77. package/plugins/devos/workflows/common/feature-line-format.md +0 -10
  78. package/plugins/devos/workflows/common/roadmap-file-structure.md +0 -51
  79. package/plugins/devos/workflows/common/suggest-categories.md +0 -76
  80. package/plugins/devos/workflows/common/suggest-milestones.md +0 -92
  81. package/plugins/devos/workflows/doc/doc-health.md +0 -137
  82. package/plugins/devos/workflows/doc/doc-writer.md +0 -44
  83. package/plugins/devos/workflows/doc/init-documentation.md +0 -196
  84. package/plugins/devos/workflows/doc/retro-documentation.md +0 -304
  85. package/plugins/devos/workflows/doc/templates/library.md +0 -58
  86. package/plugins/devos/workflows/doc/templates/service.md +0 -61
  87. package/plugins/devos/workflows/doc/update-documentation.md +0 -194
  88. package/plugins/devos/workflows/doc/write-documentation.md +0 -137
  89. package/plugins/devos/workflows/product/create-product-mission.md +0 -45
  90. package/plugins/devos/workflows/product/create-product-roadmap.md +0 -106
  91. package/plugins/devos/workflows/product/create-product-tech-stack.md +0 -19
  92. package/plugins/devos/workflows/product/gather-product-info.md +0 -25
  93. package/plugins/devos/workflows/product/resume-detection.md +0 -70
  94. package/plugins/devos/workflows/product/reverse-backlog.md +0 -118
  95. package/plugins/devos/workflows/product/reverse-domain-model.md +0 -86
  96. package/plugins/devos/workflows/product/reverse-product-plan.md +0 -81
  97. package/plugins/devos/workflows/product/reverse-tech-stack.md +0 -73
  98. package/plugins/devos/workflows/product/scan-deep.md +0 -113
  99. package/plugins/devos/workflows/product/scan-git.md +0 -122
  100. package/plugins/devos/workflows/product/scan-light.md +0 -154
@@ -1,85 +0,0 @@
1
- # Design tells a regex cannot see
2
-
3
- Read at the audit step, after `scripts/slop-scan.py` has taken the countable half.
4
-
5
- Nothing here is wrong by nature. Each entry is banned **as a default**, the shape that arrives when no one decided anything. A brief that explicitly asks for one gets it, and says so.
6
-
7
- ## Layout
8
-
9
- | Tell | Instead |
10
- |---|---|
11
- | Three equal feature cards in a row | Two-column zig-zag, one wide cell plus two narrow, or a list. This is the single most recognisable generated layout. |
12
- | Centred hero over a dark mesh or aurora gradient | Anything else. Asymmetric, left-aligned, image-led, type-led. |
13
- | Split header: giant left headline, small paragraph floating top-right | Sub-text under the headline, or a real two-column header where both columns share a baseline. |
14
- | Three or more consecutive sections with the same image-and-text split | At least four layout families across eight sections. |
15
- | Hairlines or crosshairs drawn to make the page feel designed | Rules that separate real content, or none. |
16
- | `border-t` and `border-b` on every row of a long list | One border between rows. Above about five rows, a different component. |
17
- | Bento grid where every cell is text on white | Two or more cells carry an image, a chart, a pattern. N items means exactly N cells, no empty tail. |
18
- | Progress or score bars with filled background tracks on a marketing page | A number, or a bar with no track. |
19
-
20
- ## Labels and micro-copy
21
-
22
- | Tell | Instead |
23
- |---|---|
24
- | An eyebrow above every section | One per three sections, at most. |
25
- | Poetic section labels: "Field notes", "From the field", "On our desks", "Currently on the bench" | "Testimonials", "Latest writing", "Now working on", or no label. |
26
- | "Quietly in use at", "Quietly trusted by" | "Used at", "Customers include", or let the logos speak. |
27
- | A micro-meta sentence under an eyebrow explaining what the section is for | Cut it. The headline and body already carry it. |
28
- | Generic step labels: "Stage 1", "Step 2", "Phase 03" | The verb is the label: Install, Configure, Ship. |
29
- | Headline broken with `<br>` and the second half italicised | Let it read as a sentence. |
30
- | Vertical rotated text | Only when the brief is explicitly experimental and it composes something. |
31
- | Decoration strip at the hero's bottom edge: `BRAND. MOTION. SPATIAL.` | Cut, unless the strip is real navigation. |
32
- | Locale, time or weather strip: `Lisbon 14:23 18C` | Only for a place-based brand or a genuinely distributed studio. |
33
- | Version stamps, build numbers, "last sync 4s ago" on a marketing page | Cut. Those are devtool fixtures. |
34
- | Live-stock counters: "Reservation 412 of 800" | Only with real data behind them. |
35
- | Decorative coloured dots before nav items, list rows, badges | Only where the dot carries real state, and then rarely. |
36
- | Two CTAs with the same intent ("Get in touch" and "Let's talk") | One. |
37
-
38
- ## Content and data
39
-
40
- | Tell | Instead |
41
- |---|---|
42
- | Invented brands in the Acme family: Nexus, SmartFlow, Cloudly, Zenith, Vertex, Lumina | A name that sounds like a real company in that industry, or the real one. |
43
- | A testimonial with a role and no person, or a person and no company | Both, or delete the quote. Never invent a customer. |
44
- | Round, perfect metrics | Messy real ones: 47.2%, 1,284 teams, 340ms. If there is no number, do not print one. |
45
- | Avatar egg icons and generic user glyphs | A real photo, initials, or nothing. |
46
- | Logo wall with category labels under each logo, or text wordmarks standing in for marks | Real marks, no labels. |
47
- | Copy that describes the product's category instead of what it does | The specific claim. "Reconciles two weeks of invoices in one pass" over "streamlines financial operations". |
48
-
49
- ## Media
50
-
51
- | Tell | Instead |
52
- |---|---|
53
- | Product UI faked out of styled divs: a fake dashboard, task list, terminal | A real screenshot, a generated image, a real component, or nothing. This is the strongest single tell. |
54
- | Fake version footers inside those fake screenshots | See above, the whole element goes. |
55
- | Pills or tags overlaid on photos: `Plate 02`, `Field notes` | Nothing, or a caption below the image. |
56
- | Photo-credit captions where no photographer exists | Credit real people for real photos. Otherwise a functional caption or none. |
57
- | Hand-rolled decorative SVG blobs and squiggles | A real asset, a CSS gradient, or empty space. |
58
-
59
- ## Motion
60
-
61
- | Tell | Instead |
62
- |---|---|
63
- | Infinite loops on decorative elements | Motion that starts, resolves, and stops. |
64
- | Two marquees on one page | One, or zero. |
65
- | Motion the copy claims and the page does not perform | Cut the claim or build the motion. |
66
- | Scroll hijack with no reason a user would name | Native scrolling. |
67
-
68
- Every animation should survive one question: what does this tell the user about hierarchy, state, or where they are? No answer means delete it.
69
-
70
- ## The default palettes to diverge from
71
-
72
- This is the "why does every AI page look the same" list. Recognise the family you are drifting into and leave it.
73
-
74
- - Violet-to-indigo gradient on near-black, roughly `#6366f1` to `#a855f7`.
75
- - Inter, slate-900 text, `bg-slate-50` surfaces, emerald accent for anything trustworthy.
76
- - Instrument Serif or Fraunces hero at `-0.03em`, paired with a geometric sans.
77
- - Premium-consumer beige, brass, oxblood, espresso. Cookware, wellness, artisan, every time.
78
- - Glassmorphism applied to every card rather than one surface that needs depth.
79
- - Zinc neutrals with a single saturated accent and `rounded-xl` everywhere.
80
-
81
- The fix is not a different fixed palette. A skill that hands you one produces pages that all look alike in a new way, which is how the reference implementation of this idea failed. Read the project's own tokens, and if it has none, settle them once with the human and write them down.
82
-
83
- ## Do not over-correct
84
-
85
- Clean, human design hits some of these by accident. One serif the brand actually owns, one three-card row where the three things genuinely are peers and every alternative reads worse, one dot that means "live". Act on clusters, not on single hits, and never trade a working layout for a novel one to score points here.
@@ -1,305 +0,0 @@
1
- #!/usr/bin/env python3
2
- """slop-scan: the countable AI design tells in frontend source.
3
-
4
- Deterministic, zero model calls. Only what a regex can prove lives here; the
5
- judgement half is references/tells.md, read by the model, not by grep.
6
-
7
- Usage: slop-scan.py [path...] scan (default: .), exit 1 if any FAIL
8
- slop-scan.py --selftest fixture check, needs no project
9
-
10
- FAIL is a tell with no legitimate reading. WARN is context-dependent: fix it
11
- or state the reason. A pattern that fires on honest code is a bug in the
12
- pattern and gets deleted, not documented around. Four were cut that way on the
13
- first real run, against promptfoo, leanspec, OpenSpec and pilot-shell:
14
- `h-screen` matched the correct `min-h-screen`, every em dash in a code comment
15
- was reported as a design tell, minified vendor bundles produced 200 hits from
16
- one line, and element-level scroll listeners on a data table are how that job
17
- is actually done.
18
-
19
- The unicode tells are assembled from bytes on purpose. A literal em dash in
20
- this file trips the very hooks that police em dashes, including this script.
21
-
22
- Why Python: the shell version ran `grep -qI` plus `awk 'length($0)>500'` on
23
- every file, two forks each, then made thirteen more passes over the whole tree
24
- with grep. It also recovered each finding by splitting grep's own output on
25
- colons, which silently lost the line number whenever a path contained one. This
26
- reads each file once, keeps the path and line it already has, and compiles the
27
- patterns once.
28
- """
29
- from __future__ import annotations
30
-
31
- import re
32
- import sys
33
- from pathlib import Path
34
-
35
- EM = "—"
36
- EN = "–"
37
- DOT = "·"
38
- ARR = "↓"
39
-
40
- SOURCE_SUFFIXES = (".html", ".htm", ".jsx", ".tsx", ".vue", ".svelte",
41
- ".astro", ".css", ".scss")
42
- PRUNE_DIRS = {"node_modules", ".git", "dist", "build", ".next", "vendor",
43
- "coverage", "__tests__", "__mocks__"}
44
- # A reserved-domain address or a stub user in a test is correct practice, and in
45
- # one real repository those files were 90 of the 160 findings. What ships to a
46
- # user is what this scans.
47
- NAME_EXCLUDE = (".test.", ".spec.", ".stories.")
48
-
49
- # The shell patterns were POSIX ERE. Two things do not carry over: the
50
- # bracket-expression classes, and the (^|[^x]) guard idiom, which here becomes a
51
- # lookbehind so the same positions match without consuming the neighbour.
52
- # severity, label, pattern.
53
- RULES: list[tuple[str, str, re.Pattern[str]]] = [
54
- ("FAIL", "em/en dash", re.compile(f"{EM}|{EN}")),
55
- ("FAIL", "section-number eyebrow", re.compile(
56
- rf"[0-9]{{2,3}}\s*{DOT}\s*[A-Za-z]|(?<![0-9])0[0-9]\s+/\s+[A-Za-z]")),
57
- ("FAIL", "scroll cue", re.compile(
58
- r"[Ss]croll to (explore|discover|begin|continue|reveal|walk)|"
59
- rf"{ARR}\s*[Ss]croll")),
60
- ("FAIL", "middle-dot chain", re.compile(f"{DOT}.*{DOT}")),
61
- ("FAIL", "placeholder identity", re.compile(
62
- r"John Doe|Jane Doe|John Smith|Acme\b|[Ll]orem ipsum")),
63
- ("FAIL", "fake-perfect stat", re.compile(r"99\.9{1,3}%|100% uptime")),
64
- ("FAIL", "pure-black text", re.compile(r"(?<![-\w])color:\s*#000(000)?\b")),
65
- ("FAIL", "AI marketing copy", re.compile(
66
- r"Elevate your|Unleash|Next-Gen|Revolutioniz|Game-chang|Supercharge|"
67
- r"Effortlessly|Cutting-edge|Seamlessly integrat")),
68
- ("WARN", "Inter as body font", re.compile(
69
- r"font-family:[^;]*\bInter\b|--font-inter")),
70
- ("WARN", "viewport unit", re.compile(
71
- r"(?<![-\w])h-screen\b|(?<![-\w])height:\s*100vh\b")),
72
- ("WARN", "window scroll listener", re.compile(
73
- r"window\.addEventListener\((['\"])scroll")),
74
- ("WARN", "launch label", re.compile(r"INVITE.ONLY|EARLY ACCESS|>\s*BETA\s*<")),
75
- ]
76
-
77
- # A lone dash standing in for a missing value in a cell or badge is a null
78
- # glyph, not prose, and two of the three real repositories this was first run
79
- # against use it that way. Strip those, and judge what is left: a dash inside a
80
- # sentence is still the tell.
81
- NULL_DASH = re.compile(rf"['\">`{{\(]\s*({EM}|{EN})\s*['\"<`\}}\)]")
82
-
83
- # A hit inside a code comment is invisible to whoever looks at the page, so it is
84
- # not a design tell. This is the whole reason the em-dash rule survives contact
85
- # with a real repository. The shell's case patterns were //* /* * # and {/*,
86
- # where the trailing * is a glob wildcard, so each means "starts with".
87
- COMMENT = re.compile(r"^(?://|/\*|\*|#|\{/\*)")
88
-
89
- MOTION = re.compile(r"@keyframes|transition:|animate-|framer-motion|gsap")
90
- REDUCED_MOTION = re.compile(r"prefers-reduced-motion")
91
-
92
-
93
- def is_comment(content: str) -> bool:
94
- return bool(COMMENT.match(content.lstrip()))
95
-
96
-
97
- def is_null_dash(content: str) -> bool:
98
- """True only when every dash on the line is a null glyph, so skip it.
99
-
100
- A line with no dash at all is not a null-dash line, and the nine non-dash
101
- rules depend on that distinction: returning True there silently suppressed
102
- every rule but the dash one.
103
- """
104
- if EM not in content and EN not in content:
105
- return False
106
- return not (EM in NULL_DASH.sub("", content) or EN in NULL_DASH.sub("", content))
107
-
108
-
109
- def list_files(roots: list[str]) -> list[Path]:
110
- found: list[Path] = []
111
- for root in roots:
112
- base = Path(root)
113
- if base.is_file():
114
- if base.suffix in SOURCE_SUFFIXES and not any(
115
- e in base.name for e in NAME_EXCLUDE):
116
- found.append(base)
117
- continue
118
- for dirpath, dirnames, filenames in __import__("os").walk(base):
119
- dirnames[:] = sorted(d for d in dirnames if d not in PRUNE_DIRS)
120
- for name in sorted(filenames):
121
- if name.startswith("."):
122
- continue
123
- if not name.endswith(SOURCE_SUFFIXES):
124
- continue
125
- if any(e in name for e in NAME_EXCLUDE):
126
- continue
127
- found.append(Path(dirpath) / name)
128
- return found
129
-
130
-
131
- def classify(path: Path) -> tuple[str | None, bool]:
132
- """Return (text, scanned). Two kinds of file are not authored design.
133
-
134
- A minified or vendored bundle holds one 40,000-character line and reports
135
- 200 tells from it. An encrypted or otherwise binary source file (git-crypt
136
- ships .tsx files like this) matches every byte pattern at random.
137
-
138
- A file with no non-blank character anywhere is empty or blank. It is
139
- authored, not generated, and it can hold no tell, so it is scanned and
140
- counted. Skipping it made a project whose only frontend file is empty report
141
- that it has no frontend files.
142
- """
143
- try:
144
- raw = path.read_bytes()
145
- except OSError:
146
- return None, False
147
- if not raw:
148
- return "", True
149
- try:
150
- text = raw.decode("utf-8")
151
- except UnicodeDecodeError:
152
- return None, False
153
- if "\x00" in text:
154
- return None, False
155
- if any(len(line) > 500 for line in text.splitlines()):
156
- return text, False
157
- return text, True
158
-
159
-
160
- def scan(paths: list[str]) -> tuple[str, bool]:
161
- candidates = list_files(paths)
162
- contents: list[tuple[Path, str]] = []
163
- skipped = 0
164
- for f in candidates:
165
- text, scanned = classify(f)
166
- if not scanned:
167
- skipped += 1
168
- continue
169
- contents.append((f, text))
170
-
171
- if not contents:
172
- return f"slop-scan: no frontend files under: {' '.join(paths)}", True
173
-
174
- fails = warns = 0
175
- out: list[str] = []
176
-
177
- for sev, label, pattern in RULES:
178
- for f, text in contents:
179
- for lineno, line in enumerate(text.splitlines(), 1):
180
- if not pattern.search(line):
181
- continue
182
- if is_comment(line):
183
- continue
184
- if is_null_dash(line):
185
- continue
186
- body = line.strip()[:70]
187
- out.append(f"{sev} {f}:{lineno} {label}: {body}")
188
- if sev == "FAIL":
189
- fails += 1
190
- else:
191
- warns += 1
192
-
193
- # Tree-level: motion with no escape hatch. Per file this says nothing, the
194
- # media query legitimately lives in one stylesheet for the whole app.
195
- joined = "\n".join(t for _f, t in contents)
196
- if MOTION.search(joined) and not REDUCED_MOTION.search(joined):
197
- out.append("WARN (tree) no prefers-reduced-motion: the page animates "
198
- "with no escape hatch")
199
- warns += 1
200
-
201
- summary = f"{fails} FAIL, {warns} WARN across {len(contents)} files"
202
- if skipped:
203
- summary += f" ({skipped} binary/generated skipped)"
204
- return "\n".join(out + [summary]), fails == 0
205
-
206
-
207
- # --- selftest ---------------------------------------------------------------
208
- # Every rule needs a sample in the dirty fixture. Add a rule without one and
209
- # this fails, which is the point: an untested pattern is a pattern nobody has
210
- # seen fire. The clean fixture carries the shapes that used to false-positive.
211
-
212
-
213
- def selftest() -> int:
214
- d = Path(__import__("tempfile").mkdtemp())
215
- import shutil as _sh
216
- try:
217
- (d / "dirty").mkdir()
218
- (d / "clean").mkdir()
219
- (d / "dirty/page.html").write_text(
220
- f"<h1>Ship faster {EM} without the mess</h1>\n"
221
- f"<h2>Ship faster {EN} really</h2>\n"
222
- f"<span>002 {DOT} Capabilities</span>\n"
223
- "<span>01 / INDEX</span>\n"
224
- "<p>Scroll to explore</p>\n"
225
- f"<p>{ARR} scroll</p>\n"
226
- f"<div>Lisbon {DOT} 14:23 {DOT} 18C</div>\n"
227
- "<blockquote>John Doe, Acme</blockquote>\n"
228
- "<b>99.9% uptime</b>\n"
229
- "<p>Elevate your workflow</p>\n"
230
- "<span>EARLY ACCESS</span>\n"
231
- '<div class="h-screen">\n'
232
- "<style>\n .title { color: #000; }\n"
233
- " body { font-family: Inter, sans-serif; }\n"
234
- " .card { transition: opacity 200ms; }\n</style>\n"
235
- "<script>window.addEventListener('scroll', onScroll)</script>\n"
236
- )
237
- (d / "clean/page.html").write_text(
238
- "<h1>Two weeks of invoices, reconciled in one pass</h1>\n"
239
- "<div className=\"min-h-screen max-h-screen\">\n"
240
- "<span>Filed 2026/01/12</span>\n"
241
- f"<td>{{row.contextWindow ?? '{EM}'}}</td>\n"
242
- f'<span className="text-muted">{EM}</span>\n'
243
- "<script>\n"
244
- f" // Batch metadata query {EM} fires as soon as the specs resolve\n"
245
- " tableBody.addEventListener('scroll', sync, { passive: true })\n"
246
- "</script>\n"
247
- "<style>\n"
248
- f" /* Brand accent {EN} a warm indigo */\n"
249
- " .title { color: #16110d; font-family: Switzer, system-ui, sans-serif; }\n"
250
- " footer { background-color: #000; }\n"
251
- " .card { transition: opacity 200ms; }\n"
252
- " @media (prefers-reduced-motion: reduce) { .card { transition: none; } }\n"
253
- "</style>\n"
254
- )
255
- (d / "clean/page.test.tsx").write_text(
256
- "it('accepts a reserved-domain address', () => {\n"
257
- ' render(<Login email="john.doe@example.com" name="John Doe" />)\n'
258
- "})\n"
259
- )
260
- (d / "clean/bundle.css").write_text(
261
- ".x{color:#000}" + "".join(f".pad-{i}{{margin:{i}px}}" for i in range(80)))
262
- (d / "clean/encrypted.tsx").write_bytes(
263
- b"GITCRYPT\x00\xcc\x22\xda\xfe\xb7\x8c John Doe \xe2\x80\x94\x00")
264
-
265
- rc = 0
266
- dirty, _ = scan([str(d / "dirty")])
267
- for _sev, label, _p in RULES:
268
- if f"{label}:" not in dirty:
269
- print(f"SELFTEST FAIL: rule '{label}' never fired on the dirty fixture")
270
- rc = 1
271
- if "no prefers-reduced-motion" not in dirty:
272
- print("SELFTEST FAIL: tree-level reduced-motion check never fired")
273
- rc = 1
274
- if scan([str(d / "dirty")])[1]:
275
- print("SELFTEST FAIL: dirty fixture exited 0")
276
- rc = 1
277
-
278
- clean, clean_ok = scan([str(d / "clean")])
279
- if any(l.startswith(("FAIL", "WARN")) for l in clean.splitlines()):
280
- print("SELFTEST FAIL: clean fixture produced findings:")
281
- print(clean)
282
- rc = 1
283
- if "2 binary/generated skipped" not in clean:
284
- print("SELFTEST FAIL: minified bundle was scanned instead of skipped")
285
- rc = 1
286
- if not clean_ok:
287
- print("SELFTEST FAIL: clean fixture exited non-zero")
288
- rc = 1
289
- if rc == 0:
290
- print(f"slop-scan selftest: {len(RULES)} rules + tree check OK")
291
- return rc
292
- finally:
293
- _sh.rmtree(d, ignore_errors=True)
294
-
295
-
296
- def main(argv: list[str]) -> int:
297
- if argv and argv[0] == "--selftest":
298
- return selftest()
299
- out, ok = scan(argv or ["."])
300
- print(out)
301
- return 0 if ok else 1
302
-
303
-
304
- if __name__ == "__main__":
305
- sys.exit(main(sys.argv[1:]))
@@ -1,22 +0,0 @@
1
- ---
2
- name: docs
3
- description: "DevOS: Initialize, update, backfill, or report coverage of project documentation against the real code."
4
- argument-hint: "<init|update [spec]|backfill|status>"
5
- disable-model-invocation: true
6
- ---
7
-
8
- # /devos:docs
9
-
10
- Optional, off until invoked. Documentation organized by functional domain.
11
-
12
- **Args:** $ARGUMENTS. The first word is the mode.
13
-
14
- ## Mode
15
-
16
- `${CLAUDE_SKILL_DIR}` is this skill's own directory. If it was not expanded, use the directory that holds this file.
17
-
18
- - `init`: set up the documentation plan, mapping, and skeletons. Once per project. Read `${CLAUDE_SKILL_DIR}/references/init.md` and follow it.
19
- - `update [spec]`: bring the documentation in line with an implemented spec. Read `${CLAUDE_SKILL_DIR}/references/update.md` and follow it.
20
- - `backfill`: document everything that exists already, from past specs and the code. Read `${CLAUDE_SKILL_DIR}/references/backfill.md` and follow it.
21
- - `status`: coverage, freshness, and completeness report. Read `${CLAUDE_SKILL_DIR}/references/status.md` and follow it.
22
- - anything else: print this list and one line naming the closest mode. Write nothing.
@@ -1,54 +0,0 @@
1
- # Retro-Documentation
2
-
3
- Generates consolidated documentation retrospectively from all past specs. For existing projects or to catch up on a significant documentation backlog.
4
-
5
- ---
6
-
7
-
8
-
9
- ---
10
-
11
- **When to use this command:**
12
- - Existing project starting documentation late
13
- - More than 2 specs behind on documentation (recommended by `/devos:docs update`)
14
- - To standardize/complete existing documentation
15
-
16
- ---
17
-
18
- ## Step 1: Check prerequisites
19
-
20
- ### 1.1 Existing specs
21
-
22
- ```bash
23
- ls -d devos/specs/*/ 2>/dev/null
24
- ```
25
-
26
- If no spec is found:
27
- ```
28
- ❌ No spec found in devos/specs/
29
-
30
- Retro-documentation requires at least one existing spec.
31
- Use /devos:docs init if you want to initialize the structure.
32
- ```
33
- **STOP**
34
-
35
- ---
36
-
37
- ## Step 2: Run the workflow
38
-
39
- **IMPORTANT:** This workflow uses interactive validations (grouping plan, writing plan). The main agent handles the interactions with you and runs the writing passes with `${CLAUDE_PLUGIN_ROOT}/workflows/doc/doc-writer.md` as their brief.
40
-
41
- Read and follow `${CLAUDE_PLUGIN_ROOT}/workflows/doc/retro-documentation.md`.
42
-
43
- ---
44
-
45
- ## Step 3: Final summary
46
-
47
- ```
48
- ✅ Retro-documentation complete
49
-
50
- 📄 Plan: devos/product/documentation-plan.md
51
- 📄 Mapping: devos/product/documentation-mapping.md
52
-
53
- Next step: /devos:docs status to check coverage
54
- ```
@@ -1,43 +0,0 @@
1
- # Initialize Documentation
2
-
3
- Initializes the project's consolidated functional documentation: documentation plan, mapping, and markdown skeletons organized by functional domain.
4
-
5
- ---
6
-
7
-
8
-
9
- ---
10
-
11
- **When to use this command:**
12
- - To set up the documentation structure for a new project
13
- - Run once per project
14
-
15
- ---
16
-
17
- ## Step 1: Check prerequisites
18
-
19
- Check that documentation hasn't already been initialized:
20
-
21
- ```bash
22
- ls devos/product/documentation-plan.md 2>/dev/null
23
- ```
24
-
25
- **If the file exists:**
26
- ```
27
- ❌ Documentation has already been initialized.
28
-
29
- The documentation plan already exists: devos/product/documentation-plan.md
30
-
31
- To update the documentation, use:
32
- - /devos:docs update <spec>: update for a spec
33
- - /devos:docs update: scan all specs
34
- ```
35
- **STOP**: Do not continue.
36
-
37
- ---
38
-
39
- ## Step 2: Run the workflow
40
-
41
- **IMPORTANT:** This workflow uses interactive Q&A with you and must be executed by the main agent. Do not hand it to a separate pass.
42
-
43
- Read and follow `${CLAUDE_PLUGIN_ROOT}/workflows/doc/init-documentation.md`.
@@ -1,71 +0,0 @@
1
- # Documentation Status
2
-
3
- Displays health metrics for the consolidated documentation: coverage, freshness, and structural completeness.
4
-
5
- ---
6
-
7
-
8
-
9
- ---
10
-
11
- **When to use this command:**
12
- - To identify areas to update as a priority
13
- - To check coverage after an update or a retro-documentation
14
- - To monitor overall documentation health
15
-
16
- ---
17
-
18
- ## Step 1: Check prerequisites
19
-
20
- ```bash
21
- ls devos/product/documentation-mapping.md 2>/dev/null
22
- ```
23
-
24
- If the mapping doesn't exist:
25
- ```
26
- ❌ No documentation mapping found.
27
-
28
- Documentation has not been initialized yet.
29
- Run first: /devos:docs init
30
- ```
31
- **STOP**
32
-
33
- ---
34
-
35
- ## Step 2: Run the workflow guide
36
-
37
- Run the workflow guide with this brief:
38
-
39
- ```
40
- You are the Documentation Health Agent for DevOS.
41
-
42
- ## Context
43
- - ARTIFACTS_DIR: devos
44
-
45
- ## Your Mission
46
-
47
- Read and follow `${CLAUDE_PLUGIN_ROOT}/workflows/doc/doc-health.md`.
48
- ```
49
-
50
- **WAIT** for that pass to complete.
51
-
52
-
53
- ---
54
-
55
- ## Step 3: Display results and recommendations
56
-
57
- Display that pass's output to the user.
58
-
59
- After displaying the metrics, propose actions:
60
-
61
- ```
62
- Recommended actions:
63
- [If coverage < 100%:]
64
- - /devos:docs update <spec> for undocumented specs
65
-
66
- [If completeness < 80%:]
67
- - Fill in placeholders in low-completeness files
68
-
69
- [If freshness > 30 days:]
70
- - /devos:docs update to check for missing updates
71
- ```
@@ -1,80 +0,0 @@
1
- # Update Documentation
2
-
3
- Updates the consolidated documentation after a spec has been implemented and tested.
4
-
5
- ---
6
-
7
-
8
-
9
- ---
10
-
11
- **Two modes:**
12
- - `/devos:docs update <spec-name>`: targeted mode (one spec)
13
- - `/devos:docs update`: global mode (scan all specs)
14
-
15
- **When to use this command:**
16
- - After a spec has been implemented and tested
17
- - To keep documentation in sync with the product
18
-
19
- ---
20
-
21
- ## Step 1: Parse arguments
22
-
23
- | Input | Mode | Variable |
24
- |-------|------|----------|
25
- | `/devos:docs update user-auth` | targeted | SPEC_NAME=user-auth |
26
- | `/devos:docs update` | global | SPEC_NAME=null |
27
-
28
- ---
29
-
30
- ## Step 2: Check prerequisites
31
-
32
- ### 2.1 Documentation plan
33
-
34
- ```bash
35
- ls devos/product/documentation-plan.md 2>/dev/null
36
- ```
37
-
38
- If the plan doesn't exist:
39
- ```
40
- ❌ No documentation plan found.
41
-
42
- Documentation must be initialized before it can be updated.
43
- Run first: /devos:docs init
44
- ```
45
- **STOP**
46
-
47
- ### 2.2 Implemented spec (targeted mode)
48
-
49
- If in targeted mode, check that the spec exists and is implemented:
50
-
51
- 1. Check `devos/specs/*${SPEC_NAME}*/verifications/verification.md` exists
52
-
53
- If the spec is not implemented:
54
- ```
55
- ❌ Spec [SPEC_NAME] is not yet implemented.
56
-
57
- Current status: [last completed phase]
58
- Run first: /devos:implement [SPEC_NAME]
59
- ```
60
- **STOP**
61
-
62
- ---
63
-
64
- ## Step 3: Run the workflow
65
-
66
- **IMPORTANT:** This workflow uses interactive validations with you (update plan, diffs). The main agent handles the interactions and runs the writing passes with `${CLAUDE_PLUGIN_ROOT}/workflows/doc/doc-writer.md` as their brief.
67
-
68
- Read and follow `${CLAUDE_PLUGIN_ROOT}/workflows/doc/update-documentation.md`.
69
-
70
- ---
71
-
72
- ## Step 4: Final summary
73
-
74
- ```
75
- ✅ Documentation updated for: [spec-name or "global"]
76
-
77
- 📄 Mapping: devos/product/documentation-mapping.md (refreshed)
78
-
79
- Next step: /devos:docs status to check coverage
80
- ```