@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.
- package/CHANGELOG.md +23 -0
- package/README.md +26 -33
- package/package.json +1 -2
- package/plugins/devos/agents/verifier.md +4 -30
- package/plugins/devos/pi/extension/devos.ts +16 -26
- package/plugins/devos/scripts/check-evidence-router.sh +7 -1
- package/plugins/devos/scripts/evidence-router.py +5 -3
- package/plugins/devos/scripts/gates/check-dod-core.sh +5 -3
- package/plugins/devos/scripts/gates/check-port-source.sh +1 -1
- package/plugins/devos/scripts/gates/check-scenario-coverage.sh +10 -8
- package/plugins/devos/scripts/gates/phase-gate.sh +6 -6
- package/plugins/devos/scripts/gates/plan-template-check.py +6 -12
- package/plugins/devos/scripts/gates/spec-contract.sh +19 -0
- package/plugins/devos/scripts/gates/spec-template-check.py +8 -21
- package/plugins/devos/scripts/gates/suite/01-dod.sh +485 -0
- package/plugins/devos/scripts/gates/suite/02-integrity.sh +310 -0
- package/plugins/devos/scripts/gates/suite/03-archetype.sh +255 -0
- package/plugins/devos/scripts/gates/suite/04-spec-validator.sh +183 -0
- package/plugins/devos/scripts/gates/suite/05-requires.sh +360 -0
- package/plugins/devos/scripts/gates/suite/06-clarify-adapters.sh +435 -0
- package/plugins/devos/scripts/gates/suite/07-lint-evals.sh +350 -0
- package/plugins/devos/scripts/gates/suite/08-converge.sh +591 -0
- package/plugins/devos/scripts/gates/suite/09-quality.sh +516 -0
- package/plugins/devos/scripts/gates/suite/10-eval-harness.sh +679 -0
- package/plugins/devos/scripts/gates/test-gates.sh +23 -4253
- package/plugins/devos/scripts/gates/test-integrity-rubric.sh +1 -1
- package/plugins/devos/scripts/gates/test-phase-gate.sh +5 -5
- package/plugins/devos/skills/build/SKILL.md +3 -3
- package/plugins/devos/skills/build/references/refactor.md +1 -1
- package/plugins/devos/skills/build/references/routes.md +4 -4
- package/plugins/devos/skills/frame/SKILL.md +22 -39
- package/plugins/devos/skills/frame/references/template.md +115 -0
- package/plugins/devos/skills/implement/SKILL.md +4 -4
- package/plugins/devos/skills/implement/references/dod.md +6 -1
- package/plugins/devos/skills/implement/references/implement.md +3 -1
- package/plugins/devos/skills/implement/references/plan.md +9 -27
- package/plugins/devos/skills/implement/references/resume.md +1 -1
- package/plugins/devos/skills/implement/references/verify-close.md +4 -3
- package/plugins/devos/skills/implement/scripts/ops-log.sh +2 -2
- package/plugins/devos/skills/implement/scripts/validate-spec.sh +17 -65
- package/plugins/devos/skills/init/references/context.md +1 -1
- package/plugins/devos/skills/review/SKILL.md +24 -47
- package/plugins/devos/skills/review/references/comments.md +13 -0
- package/plugins/devos/skills/review/references/reviewer.md +124 -0
- package/plugins/devos/skills/review/references/routing.md +35 -0
- package/plugins/devos/skills/review/scripts/__pycache__/prepare.cpython-313.pyc +0 -0
- package/plugins/devos/skills/review/scripts/prepare.py +763 -0
- package/plugins/devos/skills/spec/SKILL.md +5 -6
- package/plugins/devos/skills/spec/references/write-spec.md +36 -51
- package/plugins/devos/skills/spec/scripts/clarify.sh +4 -4
- package/plugins/devos/skills/status/SKILL.md +4 -4
- package/plugins/devos/skills/status/scripts/check-requires.py +4 -4
- package/plugins/devos/skills/status/scripts/convention-usage.sh +1 -1
- package/plugins/devos/skills/status/scripts/quality-correlation.sh +2 -25
- package/plugins/devos/scripts/gates/check-handoff.sh +0 -215
- package/plugins/devos/skills/design-taste/SKILL.md +0 -55
- package/plugins/devos/skills/design-taste/references/tells.md +0 -85
- package/plugins/devos/skills/design-taste/scripts/slop-scan.py +0 -305
- package/plugins/devos/skills/docs/SKILL.md +0 -22
- package/plugins/devos/skills/docs/references/backfill.md +0 -54
- package/plugins/devos/skills/docs/references/init.md +0 -43
- package/plugins/devos/skills/docs/references/status.md +0 -71
- package/plugins/devos/skills/docs/references/update.md +0 -80
- package/plugins/devos/skills/explain/SKILL.md +0 -45
- package/plugins/devos/skills/explain/references/quiz.md +0 -21
- package/plugins/devos/skills/frame/references/boundaries.md +0 -53
- package/plugins/devos/skills/frame/references/decompose.md +0 -96
- package/plugins/devos/skills/frame/references/impact.md +0 -43
- package/plugins/devos/skills/frame/references/interrogate.md +0 -68
- package/plugins/devos/skills/product/SKILL.md +0 -40
- package/plugins/devos/skills/product/references/planner.md +0 -54
- package/plugins/devos/skills/surgical-diff/SKILL.md +0 -23
- package/plugins/devos/skills/test-integrity/SKILL.md +0 -26
- package/plugins/devos/skills/verification-evidence/SKILL.md +0 -17
- package/plugins/devos/workflows/common/backlog-file-structure.md +0 -44
- package/plugins/devos/workflows/common/category-file-structure.md +0 -41
- package/plugins/devos/workflows/common/feature-line-format.md +0 -10
- package/plugins/devos/workflows/common/roadmap-file-structure.md +0 -51
- package/plugins/devos/workflows/common/suggest-categories.md +0 -76
- package/plugins/devos/workflows/common/suggest-milestones.md +0 -92
- package/plugins/devos/workflows/doc/doc-health.md +0 -137
- package/plugins/devos/workflows/doc/doc-writer.md +0 -44
- package/plugins/devos/workflows/doc/init-documentation.md +0 -196
- package/plugins/devos/workflows/doc/retro-documentation.md +0 -304
- package/plugins/devos/workflows/doc/templates/library.md +0 -58
- package/plugins/devos/workflows/doc/templates/service.md +0 -61
- package/plugins/devos/workflows/doc/update-documentation.md +0 -194
- package/plugins/devos/workflows/doc/write-documentation.md +0 -137
- package/plugins/devos/workflows/product/create-product-mission.md +0 -45
- package/plugins/devos/workflows/product/create-product-roadmap.md +0 -106
- package/plugins/devos/workflows/product/create-product-tech-stack.md +0 -19
- package/plugins/devos/workflows/product/gather-product-info.md +0 -25
- package/plugins/devos/workflows/product/resume-detection.md +0 -70
- package/plugins/devos/workflows/product/reverse-backlog.md +0 -118
- package/plugins/devos/workflows/product/reverse-domain-model.md +0 -86
- package/plugins/devos/workflows/product/reverse-product-plan.md +0 -81
- package/plugins/devos/workflows/product/reverse-tech-stack.md +0 -73
- package/plugins/devos/workflows/product/scan-deep.md +0 -113
- package/plugins/devos/workflows/product/scan-git.md +0 -122
- 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
|
-
```
|