@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,12 +1,12 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: spec
|
|
3
|
-
description: "DevOS: interview the engineer, capture a feature's requirements, and produce spec
|
|
3
|
+
description: "DevOS: interview the engineer, capture a feature's requirements, and produce the contract in spec.md. Not for a small change."
|
|
4
4
|
argument-hint: "[feature description | spec-name]"
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# /devos:spec
|
|
8
8
|
|
|
9
|
-
Run in the **main agent**: interview the engineer and produce `planning/notes.md` plus `spec
|
|
9
|
+
Run in the **main agent**: interview the engineer and produce `planning/notes.md` plus the contract in `spec.md` in one run, since the questions need the conversation that asks them.
|
|
10
10
|
|
|
11
11
|
**Feature:** $ARGUMENTS
|
|
12
12
|
|
|
@@ -28,10 +28,9 @@ A request that contradicts the code, the conventions, or an obvious constraint i
|
|
|
28
28
|
|
|
29
29
|
## Step 2: Capture the interview record
|
|
30
30
|
|
|
31
|
-
`planning/notes.md` is the record of the conversation, not a draft of the spec. Before synthesis, it holds
|
|
31
|
+
`planning/notes.md` is the record of the conversation, not a draft of the spec. Before synthesis, it holds two things and nothing else:
|
|
32
32
|
|
|
33
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
34
|
- **Open assumptions**: the guesses still unconfirmed, one line each, so a guess is not recorded as a settled requirement.
|
|
36
35
|
|
|
37
36
|
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.
|
|
@@ -42,7 +41,7 @@ If this feature adds a screen, a dialog, or an interactive flow, read `reference
|
|
|
42
41
|
|
|
43
42
|
## Step 3: Write the spec
|
|
44
43
|
|
|
45
|
-
Write `SPEC_DIR/spec
|
|
44
|
+
Write `SPEC_DIR/spec.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
45
|
|
|
47
46
|
`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
47
|
|
|
@@ -51,7 +50,7 @@ Write `SPEC_DIR/spec-functional.md` yourself, in this same turn. You hold the in
|
|
|
51
50
|
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
51
|
|
|
53
52
|
```
|
|
54
|
-
📊 [spec-name]: [✅/🔄/⏳ per phase: planning/notes.md, spec
|
|
53
|
+
📊 [spec-name]: [✅/🔄/⏳ per phase: planning/notes.md, spec.md contract, spec.md plan, verifications/verification.md]
|
|
55
54
|
🎯 Next: /devos:implement [spec-name]
|
|
56
55
|
```
|
|
57
56
|
|
|
@@ -1,42 +1,45 @@
|
|
|
1
|
-
# Write the
|
|
1
|
+
# Write the spec
|
|
2
|
+
|
|
3
|
+
One file, `SPEC_DIR/spec.md`, in two passes. This pass writes the contract: the Goal, the Scenarios and the Out of scope, plus a Behavior delta, Business rules and Functional constraints when the change needs them. The plan pass in `implement` appends the technical sections to the same file. There is no second spec file.
|
|
2
4
|
|
|
3
5
|
## 1. How long
|
|
4
6
|
|
|
5
|
-
As long as the behavior, and no longer. `validate-spec.sh` requires three things: a Goal, scenarios in `Scenario SC-n:` form, and an Out of
|
|
7
|
+
As long as the behavior, and no longer. `validate-spec.sh` requires three things: a Goal, scenarios in `Scenario SC-n:` form, and an Out of scope. Everything else earns its place or goes.
|
|
6
8
|
|
|
7
|
-
**M-sized work** (a few files, clear behavior) is
|
|
9
|
+
**M-sized work** (a few files, clear behavior) is the page in section 2. **L-sized work** (a user-visible feature, unenumerated edge cases) is section 4.
|
|
8
10
|
|
|
9
|
-
|
|
11
|
+
When a frame row is the source, write the scenarios from the frame's business rules and put the rule id in the scenario name, `Scenario SC-1: standard invoice (BR-1) / WHEN ...`. Name the frame path on a `Frame:` line under the Goal. Do not copy the frame's context, impact, scope prose or file list: the plan cites the frame instead.
|
|
10
12
|
|
|
11
|
-
|
|
13
|
+
Write each fact once. A function, error or path name goes in the plan's Technical requirements or Code Map, not in the contract as well.
|
|
14
|
+
|
|
15
|
+
## 2. M: one page
|
|
12
16
|
|
|
13
17
|
```markdown
|
|
18
|
+
---
|
|
19
|
+
devos-contract: 1
|
|
20
|
+
---
|
|
21
|
+
|
|
14
22
|
# [Feature Name]
|
|
15
23
|
|
|
16
|
-
##
|
|
24
|
+
## Goal
|
|
17
25
|
|
|
18
26
|
[1-2 sentences of business purpose]
|
|
19
27
|
|
|
20
|
-
##
|
|
28
|
+
## Scenarios
|
|
21
29
|
|
|
22
|
-
**Scenarios:**
|
|
23
30
|
- Scenario SC-1: [name] / WHEN [condition] / THEN [observable outcome]
|
|
24
31
|
- Scenario SC-2: [edge case] / WHEN [boundary or failure condition] / THEN [expected handling]
|
|
25
32
|
|
|
26
|
-
##
|
|
33
|
+
## Out of scope
|
|
27
34
|
|
|
28
35
|
- [Item 1 explicitly out of scope]
|
|
29
|
-
|
|
30
|
-
## Appendix
|
|
31
|
-
|
|
32
|
-
**Explicit contract anchors:** [verbatim names, signatures, public API or event names, and target paths supplied by the engineer, or `None supplied`.]
|
|
33
36
|
```
|
|
34
37
|
|
|
35
|
-
## 3. From the
|
|
38
|
+
## 3. From the interview
|
|
36
39
|
|
|
37
40
|
Read `planning/notes.md`, optional `planning/prototype.html`, and optional `devos/product/domain-model.md`. Domain-model entity names are the official vocabulary. For a prototype, read `references/prototype.md` and apply its state-vocabulary and data rules.
|
|
38
41
|
|
|
39
|
-
Extract the behavior, business rules, lifecycle states, and out-of-scope items.
|
|
42
|
+
Extract the behavior, business rules, lifecycle states, and out-of-scope items. Function names, signatures, event names and file paths the engineer supplied go verbatim into the plan's Technical requirements and Code Map, once. Do not infer one that was not supplied.
|
|
40
43
|
|
|
41
44
|
Copy from the notes, verbatim, when they hold any:
|
|
42
45
|
|
|
@@ -47,46 +50,34 @@ Omit either heading when the notes hold no matching entry.
|
|
|
47
50
|
|
|
48
51
|
## 4. L: the full shape
|
|
49
52
|
|
|
50
|
-
|
|
53
|
+
The M page plus Business rules, a Behavior delta and Functional constraints.
|
|
51
54
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
- **Two to four** Functionality subsections. More means the feature should be two specs.
|
|
55
|
-
- **Behavior delta**: name each capability in kebab-case, using the domain model when present. Read `devos/product/behaviors/<capability>.md` for a touched capability and quote current behavior in Modified and Removed entries, then check the matching `conflicts.log`. Two or more entries there earns a `## Known Volatility` section naming the conflict patterns.
|
|
55
|
+
- **Business rules**: only a rule no scenario already shows. Delete the section when the scenarios carry them.
|
|
56
|
+
- **Behavior delta**: name each capability in kebab-case, using the domain model when present. Read `devos/product/behaviors/<capability>.md` for a touched capability and quote current behavior in Modified and Removed entries, then check the matching `conflicts.log`. Two or more entries there earns a `## Known Volatility` section naming the conflict patterns. Leave Added entries out when the scenarios already say it.
|
|
56
57
|
- **A deliberate drop** reads `- [behavior]: **Reason:** [why]. **Replaced by:** [what covers it now, or "nothing, gone on purpose"].`
|
|
57
58
|
- **`Requires:`**, only when this spec depends on another unshipped spec. List the dependents as `Requires: [YYYY-MM-DD-name, ...]`, or a unique short suffix. Omit the line entirely when there are none. `/devos:status` reports unmet targets as `blocked-by`, and doctor flags an unknown name.
|
|
58
59
|
|
|
59
60
|
```markdown
|
|
61
|
+
---
|
|
62
|
+
devos-contract: 1
|
|
63
|
+
---
|
|
64
|
+
|
|
60
65
|
# [Feature Name]
|
|
61
66
|
|
|
62
|
-
##
|
|
67
|
+
## Goal
|
|
63
68
|
|
|
64
69
|
[1-2 sentences of business purpose]
|
|
65
70
|
|
|
66
|
-
##
|
|
71
|
+
## Scenarios
|
|
67
72
|
|
|
68
|
-
### 2.1 [Functionality 1]
|
|
69
|
-
**Outcome:** [what the user gets, in one line. This is the benefit a reviewer checks the delivered logic against, so it names the outcome and not the mechanism.]
|
|
70
|
-
|
|
71
|
-
**Behavior:**
|
|
72
|
-
1. [Step 1]
|
|
73
|
-
2. [Step 2]
|
|
74
|
-
3. [Result]
|
|
75
|
-
|
|
76
|
-
**Business rules:**
|
|
77
|
-
- [Rule 1]
|
|
78
|
-
|
|
79
|
-
**Acceptance criteria:**
|
|
80
|
-
- [ ] Criterion 1
|
|
81
|
-
- [ ] Criterion 2
|
|
82
|
-
|
|
83
|
-
**Scenarios:**
|
|
84
73
|
- Scenario SC-1: [name] / WHEN [condition] / THEN [observable outcome]
|
|
85
74
|
- Scenario SC-2: [edge case] / WHEN [boundary or failure condition] / THEN [expected handling]
|
|
86
75
|
|
|
76
|
+
## Business rules
|
|
87
77
|
|
|
88
|
-
|
|
78
|
+
- [Rule 1]
|
|
89
79
|
|
|
80
|
+
## Behavior delta
|
|
90
81
|
|
|
91
82
|
**Added** (capability: `[kebab-name]`):
|
|
92
83
|
- [New behavior, one line each]
|
|
@@ -96,7 +87,7 @@ Four things the block below deliberately does not carry, because guidance pasted
|
|
|
96
87
|
|
|
97
88
|
**Removed:** (none)
|
|
98
89
|
|
|
99
|
-
##
|
|
90
|
+
## Functional constraints
|
|
100
91
|
|
|
101
92
|
- [Constraint 1, functional only]
|
|
102
93
|
|
|
@@ -106,27 +97,21 @@ Four things the block below deliberately does not carry, because guidance pasted
|
|
|
106
97
|
|
|
107
98
|
Requires: [spec-name, ...]
|
|
108
99
|
|
|
109
|
-
##
|
|
100
|
+
## Out of scope
|
|
110
101
|
|
|
111
102
|
- [Item 1 explicitly out of scope]
|
|
112
|
-
|
|
113
|
-
## Appendix
|
|
114
|
-
|
|
115
|
-
**Q&A:** See `planning/notes.md`
|
|
116
|
-
|
|
117
|
-
**Explicit contract anchors:** [verbatim names, signatures, public API or event names, and target paths supplied by the engineer, or `None supplied`.]
|
|
118
103
|
```
|
|
119
104
|
|
|
120
105
|
## 5. Output rules
|
|
121
106
|
|
|
122
|
-
- Functional, validatable, and understandable without code. Technical detail only where it changes observable behavior
|
|
123
|
-
- State hard behavior as MUST or SHALL. Promote should, may, probably, and ideally to MUST, or move the item to Out of
|
|
107
|
+
- Functional, validatable, and understandable without code. Technical detail only where it changes observable behavior.
|
|
108
|
+
- State hard behavior as MUST or SHALL. Promote should, may, probably, and ideally to MUST, or move the item to Out of scope.
|
|
124
109
|
- Every behavior and business rule gets an executable WHEN/THEN scenario. Number `SC-n` sequentially, never renumber or reuse once validated, and append the next free ID for amendments. Plans and verification reports use these IDs internally. **Implementation tests use behavior-facing names.**
|
|
125
|
-
- No code blocks and no technical constraints here
|
|
110
|
+
- No acceptance-criteria list that repeats the scenarios. No code blocks and no technical constraints here: those go in the plan.
|
|
126
111
|
|
|
127
112
|
## 6. Check it
|
|
128
113
|
|
|
129
|
-
Run `validate-spec.sh SPEC_DIR` (`${CLAUDE_PLUGIN_ROOT}/skills/implement/scripts/validate-spec.sh`) and fix every FAIL. Then re-read what the validator cannot judge:
|
|
114
|
+
Run `validate-spec.sh SPEC_DIR` (`${CLAUDE_PLUGIN_ROOT}/skills/implement/scripts/validate-spec.sh`) and fix every FAIL. Then re-read what the validator cannot judge: Modified entries quote current behavior, Out of scope is non-empty, and hedges are promoted.
|
|
130
115
|
|
|
131
116
|
## 7. Scan for the gaps validation cannot see
|
|
132
117
|
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
#!/bin/bash
|
|
2
|
-
# clarify.sh: detect ambiguity in spec
|
|
2
|
+
# clarify.sh: detect ambiguity in the spec contract, zero model calls.
|
|
3
3
|
#
|
|
4
4
|
# Four signal classes:
|
|
5
5
|
# 1. Vague quantifiers (several, many, fast, soon, appropriate, reasonable)
|
|
@@ -20,10 +20,10 @@ if [[ -z "$SPEC_DIR" ]]; then
|
|
|
20
20
|
fi
|
|
21
21
|
|
|
22
22
|
[[ "$SPEC_DIR" != /* ]] && SPEC_DIR="$(pwd)/$SPEC_DIR"
|
|
23
|
-
SPEC_FUNCTIONAL="$SPEC_DIR/spec
|
|
23
|
+
SPEC_FUNCTIONAL="$SPEC_DIR/spec.md"
|
|
24
24
|
|
|
25
25
|
if [[ ! -f "$SPEC_FUNCTIONAL" ]]; then
|
|
26
|
-
echo "FAIL clarify: spec
|
|
26
|
+
echo "FAIL clarify: spec.md not found: $SPEC_FUNCTIONAL" >&2
|
|
27
27
|
exit 2
|
|
28
28
|
fi
|
|
29
29
|
|
|
@@ -157,7 +157,7 @@ if [[ $count -gt 0 ]]; then
|
|
|
157
157
|
done <<<"$findings"
|
|
158
158
|
fi
|
|
159
159
|
|
|
160
|
-
# Append or create the section in spec
|
|
160
|
+
# Append or create the section in the spec
|
|
161
161
|
if ! grep -q "^## Clarifications Needed" "$SPEC_FUNCTIONAL" 2>/dev/null; then
|
|
162
162
|
if [[ -n "$clar_section" ]]; then
|
|
163
163
|
printf '\n## Clarifications Needed\n%s' "$clar_section" >> "$SPEC_FUNCTIONAL"
|
|
@@ -26,8 +26,8 @@ For each folder in `devos/specs/` (the `archive/` subfolder is not a spec: every
|
|
|
26
26
|
| (none) | Empty | `/devos:spec` |
|
|
27
27
|
| `findings.md` and no `spec.md` | Spike finished | `/devos:build` on the recommendation in the findings |
|
|
28
28
|
| `planning/notes.md` | Functional draft | `/devos:spec` |
|
|
29
|
-
| `spec
|
|
30
|
-
| `spec.md` without verification | Implementation in progress | `/devos:implement` (resume) |
|
|
29
|
+
| `spec.md` with no `## Implementation Plan` | Functional spec | `/devos:implement` |
|
|
30
|
+
| `spec.md` with a plan, without verification | Implementation in progress | `/devos:implement` (resume) |
|
|
31
31
|
| `verifications/verification.md` | Complete, awaiting archive | finish `/devos:implement` (merge behavior delta + archive) |
|
|
32
32
|
| under `devos/specs/archive/` | Complete | ✅ done, optional `/devos:review --gaps` |
|
|
33
33
|
|
|
@@ -37,11 +37,11 @@ A spec can live in a worktree on its spec branch instead of this checkout. Deriv
|
|
|
37
37
|
|
|
38
38
|
## Frames
|
|
39
39
|
|
|
40
|
-
If `devos/frames/` exists, list one line per frame folder, derived from its
|
|
40
|
+
If `devos/frames/` exists, list one line per frame folder, derived from its `frame.md`: `name: Q open questions: T tickets, S with specs`. Count the questions with no `Answer:` line, the rows of its `## Tickets` table, and how many have a spec folder whose `Frame:` line names this frame (`rg -l 'Frame: .*<frame-name>' devos/specs`). A frame whose every ticket has a spec or is marked `not now` is done, and it says so. No new script.
|
|
41
41
|
|
|
42
42
|
## Dependency edges
|
|
43
43
|
|
|
44
|
-
After deriving phases, run `python3 ${CLAUDE_SKILL_DIR}/scripts/check-requires.py` (if `${CLAUDE_SKILL_DIR}` was not expanded, it is this skill's own directory) and merge its lines into the output. Optional `Requires: [spec-name, …]`
|
|
44
|
+
After deriving phases, run `python3 ${CLAUDE_SKILL_DIR}/scripts/check-requires.py` (if `${CLAUDE_SKILL_DIR}` was not expanded, it is this skill's own directory) and merge its lines into the output. Optional `Requires: [spec-name, …]` in `spec.md` declares that this spec depends on others. Shipped = folder under `devos/specs/archive/`. The script is deterministic (zero model calls):
|
|
45
45
|
|
|
46
46
|
- `blocked-by: <name>` — a required spec is not yet archived
|
|
47
47
|
- `blocks: <name>` — shipping this spec would unblock another (reverse of blocked-by)
|
|
@@ -112,7 +112,7 @@ class Graph:
|
|
|
112
112
|
# ---- edge collection -------------------------------------------------
|
|
113
113
|
|
|
114
114
|
def parse_requires(self, spec_file: Path) -> list[str]:
|
|
115
|
-
"""One Requires: token per line from a spec
|
|
115
|
+
"""One Requires: token per line from a spec.md."""
|
|
116
116
|
if not spec_file.is_file():
|
|
117
117
|
return []
|
|
118
118
|
text = spec_file.read_text(errors="replace")
|
|
@@ -159,7 +159,7 @@ class Graph:
|
|
|
159
159
|
|
|
160
160
|
def collect_edges_for(self, folder: Path) -> None:
|
|
161
161
|
name = folder.name
|
|
162
|
-
sf = folder / "spec
|
|
162
|
+
sf = folder / "spec.md"
|
|
163
163
|
if not sf.is_file():
|
|
164
164
|
return
|
|
165
165
|
for tok in self.parse_requires(sf):
|
|
@@ -341,7 +341,7 @@ def emit_concurrent(g: Graph) -> list[str]:
|
|
|
341
341
|
open_specs: list[str] = []
|
|
342
342
|
if g.specs.is_dir():
|
|
343
343
|
for d in sorted(p for p in g.specs.iterdir() if p.is_dir()):
|
|
344
|
-
if d.name == "archive" or not (d / "spec
|
|
344
|
+
if d.name == "archive" or not (d / "spec.md").is_file():
|
|
345
345
|
continue
|
|
346
346
|
if (d / "verifications" / "verification.md").is_file():
|
|
347
347
|
continue
|
|
@@ -517,7 +517,7 @@ def main(argv: list[str]) -> int:
|
|
|
517
517
|
out.append(" fix: use the full YYYY-MM-DD-name of one of them in the Requires: line")
|
|
518
518
|
elif kind == "self":
|
|
519
519
|
out.append(f"BROKEN Requires: {frm} Requires itself")
|
|
520
|
-
out.append(" fix: remove the self-edge from spec
|
|
520
|
+
out.append(" fix: remove the self-edge from spec.md")
|
|
521
521
|
for cline in g.emit_cycles():
|
|
522
522
|
out.append(cline)
|
|
523
523
|
out.append(" fix: break the cycle in one of the Requires: lines")
|
|
@@ -124,7 +124,7 @@ while IFS= read -r line || [[ -n "$line" ]]; do
|
|
|
124
124
|
case "$base" in
|
|
125
125
|
spec.md | notes.md | index.* | README.md | AGENTS.md | \
|
|
126
126
|
decisions.md | conventions.md | domain-model.md | package.json | \
|
|
127
|
-
verification.md
|
|
127
|
+
verification.md) continue ;;
|
|
128
128
|
esac
|
|
129
129
|
if grep -qF -- "$base" <<<"$haystack"; then
|
|
130
130
|
hit="$base" hit_kind="name"
|
|
@@ -13,9 +13,8 @@
|
|
|
13
13
|
# triage-loops: integer, or ? when the row predates the column
|
|
14
14
|
# audit-hits: hits/findings (e.g. 2/5), -/0 when the audit was clean,
|
|
15
15
|
# ?/N when the row predates the column and only N is known
|
|
16
|
-
# understanding: debt
|
|
17
|
-
#
|
|
18
|
-
# - (neither applied). Absent on rows predating the column.
|
|
16
|
+
# understanding: debt, explained, or -. No longer written, still validated
|
|
17
|
+
# on legacy rows.
|
|
19
18
|
#
|
|
20
19
|
# Columns 7, 8 and 9 are optional: rows written before they existed are shorter
|
|
21
20
|
# and are counted for everything the first six answer. An unknown value is
|
|
@@ -81,7 +80,6 @@ BEGIN {
|
|
|
81
80
|
total_findings = 0
|
|
82
81
|
total_specs = 0
|
|
83
82
|
audit_hits = 0; audit_found = 0; audit_rows = 0; audit_unknown = 0; audit_invalid = 0
|
|
84
|
-
debt_rows = 0; debt_explained = 0
|
|
85
83
|
}
|
|
86
84
|
{
|
|
87
85
|
if (NF < 6) next
|
|
@@ -143,13 +141,6 @@ BEGIN {
|
|
|
143
141
|
audit_invalid++
|
|
144
142
|
}
|
|
145
143
|
|
|
146
|
-
# Understanding (column 9). Only rows where the run actually hid work from
|
|
147
|
-
# the engineer are counted: a "-" row had no debt to pay back, so folding it
|
|
148
|
-
# in would inflate the rate with specs the question never applied to.
|
|
149
|
-
if (NF >= 9 && ($9 == "debt" || $9 == "explained")) {
|
|
150
|
-
debt_rows++
|
|
151
|
-
if ($9 == "explained") debt_explained++
|
|
152
|
-
}
|
|
153
144
|
}
|
|
154
145
|
END {
|
|
155
146
|
if (total_specs == 0) {
|
|
@@ -244,20 +235,6 @@ END {
|
|
|
244
235
|
print "Invalid triage-loop values: " invalid_triage_count " (excluded from triage averages)"
|
|
245
236
|
}
|
|
246
237
|
|
|
247
|
-
print ""
|
|
248
|
-
print "## Understanding Debt"
|
|
249
|
-
print ""
|
|
250
|
-
print "Specs whose work ran where the engineer could not watch it (a"
|
|
251
|
-
print "worktree, a summary instead of the code), and how many they came back"
|
|
252
|
-
print "to explain. A rate near zero means /devos:explain is not being used."
|
|
253
|
-
print ""
|
|
254
|
-
if (debt_rows > 0) {
|
|
255
|
-
printf "%d of %d spec(s) with hidden work were explained (%.0f%%)\n", \
|
|
256
|
-
debt_explained, debt_rows, 100 * debt_explained / debt_rows
|
|
257
|
-
} else {
|
|
258
|
-
print "(no rows carry an understanding column yet)"
|
|
259
|
-
}
|
|
260
|
-
|
|
261
238
|
print ""
|
|
262
239
|
print "## Signals"
|
|
263
240
|
print ""
|
|
@@ -1,215 +0,0 @@
|
|
|
1
|
-
#!/bin/bash
|
|
2
|
-
# check-handoff.sh: turn-end handoff gate for multi-role specs. In team mode,
|
|
3
|
-
# the active spec must record the handoff for the phase it has reached, every
|
|
4
|
-
# handoff line must name an artifact that exists, and every role in those lines
|
|
5
|
-
# must resolve to a member.
|
|
6
|
-
#
|
|
7
|
-
# Deterministic, no model call. Solo users no-op: absent,
|
|
8
|
-
# template-only, single-member, or unparseable members.md means no gate.
|
|
9
|
-
#
|
|
10
|
-
# Fail-open by construction (deliberately fail-open): this script exits
|
|
11
|
-
# non-zero for a policy decision and for nothing else. Every internal failure
|
|
12
|
-
# (no jq, unreadable root, malformed members file) allows.
|
|
13
|
-
#
|
|
14
|
-
# Usage: check-handoff.sh [project-root]
|
|
15
|
-
# Optional stdin: the harness's stop-hook payload. Read only for the loop
|
|
16
|
-
# guard, never required.
|
|
17
|
-
set -u
|
|
18
|
-
|
|
19
|
-
PROJECT_ROOT="${1:-.}"
|
|
20
|
-
cd "$PROJECT_ROOT" 2>/dev/null || exit 0
|
|
21
|
-
PROJECT_ROOT_REAL=$(pwd -P) || exit 0
|
|
22
|
-
|
|
23
|
-
# Resolve an existing path without relying on realpath, which is not available
|
|
24
|
-
# on every macOS installation. Canonicalize both the parent and any final
|
|
25
|
-
# symlink so containment checks see the actual artifact.
|
|
26
|
-
absolute_existing_path() {
|
|
27
|
-
local input="$1" dir current link hops=0
|
|
28
|
-
dir=$(cd "$(dirname "$input")" 2>/dev/null && pwd -P) || return 1
|
|
29
|
-
current="$dir/$(basename "$input")"
|
|
30
|
-
while [[ -L "$current" ]]; do
|
|
31
|
-
((hops++))
|
|
32
|
-
((hops <= 40)) || return 1
|
|
33
|
-
link=$(readlink "$current") || return 1
|
|
34
|
-
if [[ "$link" = /* ]]; then
|
|
35
|
-
current="$link"
|
|
36
|
-
else
|
|
37
|
-
current="$(dirname "$current")/$link"
|
|
38
|
-
fi
|
|
39
|
-
dir=$(cd "$(dirname "$current")" 2>/dev/null && pwd -P) || return 1
|
|
40
|
-
current="$dir/$(basename "$current")"
|
|
41
|
-
done
|
|
42
|
-
printf '%s\n' "$current"
|
|
43
|
-
}
|
|
44
|
-
|
|
45
|
-
# Loop guard. A stop-gate block the model cannot satisfy would block every
|
|
46
|
-
# subsequent stop forever, so honor the harness's own already-blocked-once
|
|
47
|
-
# signal and allow the second time through: `stop_hook_active` (Claude, Codex,
|
|
48
|
-
# Copilot). Never read a terminal, this script is also run by hand
|
|
49
|
-
# and from test-gates.sh with no stdin attached.
|
|
50
|
-
input=""
|
|
51
|
-
[[ -t 0 ]] || input=$(cat 2>/dev/null)
|
|
52
|
-
command -v jq >/dev/null 2>&1 || exit 0
|
|
53
|
-
if [[ -n "$input" ]]; then
|
|
54
|
-
guard=$(printf '%s' "$input" | jq -r '
|
|
55
|
-
if (.stop_hook_active // .stopHookActive // false) then "stop"
|
|
56
|
-
elif ((.loop_count // 0) >= 1) then "stop"
|
|
57
|
-
else "go" end' 2>/dev/null)
|
|
58
|
-
# "stop": already blocked once this turn chain. Anything other than a clean
|
|
59
|
-
# "go" means the payload did not parse, so the guard cannot be trusted, and
|
|
60
|
-
# a gate that cannot tell whether it already blocked must not block again.
|
|
61
|
-
[[ "$guard" == "go" ]] || exit 0
|
|
62
|
-
fi
|
|
63
|
-
|
|
64
|
-
MEMBERS="devos/team/members.md"
|
|
65
|
-
[[ -f "$MEMBERS" ]] || exit 0
|
|
66
|
-
|
|
67
|
-
# One member per line: `- @name: role: <role>, skills: [...]`. Three traps, all
|
|
68
|
-
# hit in practice:
|
|
69
|
-
# - skip fenced blocks: the template documents its own format inside one, and
|
|
70
|
-
# counting that line armed the team gate for a solo user.
|
|
71
|
-
# - an unrecognized role does not count as a member. A typo must fall back to
|
|
72
|
-
# solo (no gate), never arm a gate whose reason names a role that isn't real.
|
|
73
|
-
# - count with awk, never `grep -c ... || echo 0`, which prints "0\n0" on zero
|
|
74
|
-
# matches and made the arithmetic test below error out and fall THROUGH to
|
|
75
|
-
# the blocking path.
|
|
76
|
-
roster=$(awk '
|
|
77
|
-
/^```/ { fenced = !fenced; next }
|
|
78
|
-
fenced { next }
|
|
79
|
-
/^- @[A-Za-z0-9_-]+:[[:space:]]*role:/ && $0 !~ /@name:/ {
|
|
80
|
-
name = $0; sub(/^- @/, "", name); sub(/:.*$/, "", name)
|
|
81
|
-
role = $0; sub(/^.*role:[[:space:]]*/, "", role); sub(/[,[:space:]].*$/, "", role)
|
|
82
|
-
if (role ~ /^(po|architect|dev|qa)$/) print name "\t" role
|
|
83
|
-
}
|
|
84
|
-
' "$MEMBERS" 2>/dev/null)
|
|
85
|
-
|
|
86
|
-
member_count=$(printf '%s\n' "$roster" | awk 'NF' | wc -l | tr -d ' ')
|
|
87
|
-
(( member_count <= 1 )) && exit 0
|
|
88
|
-
|
|
89
|
-
# Active spec: the one the current branch names, else the newest that has
|
|
90
|
-
# started. Rule 19 already guarantees the branch: Phase B creates
|
|
91
|
-
# a `[spec-name]` branch before the first edit and never works on the default
|
|
92
|
-
# branch, so the checkout already knows which spec this turn belongs to and no
|
|
93
|
-
# state file is needed to ask it. Newest-wins remains the fallback for work
|
|
94
|
-
# that is not on a spec branch (an S route, a pre-rule-19 spec, a detached
|
|
95
|
-
# HEAD, or a non-git project root), which is exactly the old behaviour.
|
|
96
|
-
#
|
|
97
|
-
# Newest-wins alone was
|
|
98
|
-
# wrong for the one case the team surface exists to serve: with two specs open,
|
|
99
|
-
# the older one could reach any phase with no handoff recorded.
|
|
100
|
-
spec_dir=""
|
|
101
|
-
branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || true)
|
|
102
|
-
if [[ -n "$branch" ]]; then
|
|
103
|
-
cand="devos/specs/$branch"
|
|
104
|
-
if [[ -f "$cand/spec.md" || -f "$cand/spec-functional.md" ]]; then
|
|
105
|
-
spec_dir="$cand/"
|
|
106
|
-
fi
|
|
107
|
-
fi
|
|
108
|
-
if [[ -z "$spec_dir" ]]; then
|
|
109
|
-
for d in devos/specs/*/; do
|
|
110
|
-
[[ "$d" == "devos/specs/archive/" ]] && continue
|
|
111
|
-
[[ -f "${d}spec.md" || -f "${d}spec-functional.md" ]] || continue
|
|
112
|
-
spec_dir="$d"
|
|
113
|
-
done
|
|
114
|
-
fi
|
|
115
|
-
[[ -n "$spec_dir" ]] || exit 0
|
|
116
|
-
|
|
117
|
-
# Phase from artifacts, newest artifact wins: the transition that just
|
|
118
|
-
# completed is the one needing a recorded handoff.
|
|
119
|
-
if [[ -f "${spec_dir}verifications/verification.md" ]]; then
|
|
120
|
-
phase="verification"
|
|
121
|
-
need="verification.md"
|
|
122
|
-
elif [[ -f "${spec_dir}spec.md" ]]; then
|
|
123
|
-
phase="planning/implementation"
|
|
124
|
-
need="spec.md"
|
|
125
|
-
else
|
|
126
|
-
phase="requirements"
|
|
127
|
-
need="spec-functional.md"
|
|
128
|
-
fi
|
|
129
|
-
|
|
130
|
-
# The Handoff section lives in spec.md once planning has produced one, and in
|
|
131
|
-
# spec-functional.md before that (the requirements handoff has nowhere else to go).
|
|
132
|
-
if [[ -f "${spec_dir}spec.md" ]]; then
|
|
133
|
-
host="${spec_dir}spec.md"
|
|
134
|
-
else
|
|
135
|
-
host="${spec_dir}spec-functional.md"
|
|
136
|
-
fi
|
|
137
|
-
if [[ "$phase" == "verification" ]]; then
|
|
138
|
-
need_path=$(absolute_existing_path "${spec_dir}verifications/$need")
|
|
139
|
-
else
|
|
140
|
-
need_path=$(absolute_existing_path "$spec_dir$need")
|
|
141
|
-
fi
|
|
142
|
-
|
|
143
|
-
roles_available=$(printf '%s\n' "$roster" | awk -F'\t' 'NF {printf "@%s (%s) ", $1, $2}')
|
|
144
|
-
|
|
145
|
-
# The reason goes to stderr: an exit-2 hook's block message is read from
|
|
146
|
-
# stderr, so printing it to stdout blocks the turn with no explanation of why.
|
|
147
|
-
block() {
|
|
148
|
-
echo "BLOCKED: handoff gate, $phase phase of $spec_dir" >&2
|
|
149
|
-
printf '%s\n' "$@" >&2
|
|
150
|
-
echo "Handoff format in $host: - @from → @to | artifact | acceptance" >&2
|
|
151
|
-
echo "Members: $roles_available" >&2
|
|
152
|
-
exit 2
|
|
153
|
-
}
|
|
154
|
-
|
|
155
|
-
section=$(awk '/^## Handoff/ { f = 1; next } f && /^## / { exit } f' "$host" 2>/dev/null)
|
|
156
|
-
if [[ -z "${section//[[:space:]]/}" ]]; then
|
|
157
|
-
block "$host has no ## Handoff section with entries." \
|
|
158
|
-
"The $phase phase produced $need; record who hands it to whom."
|
|
159
|
-
fi
|
|
160
|
-
|
|
161
|
-
found_phase_line=0
|
|
162
|
-
while IFS='|' read -r who artifact accept; do
|
|
163
|
-
[[ -n "${who//[[:space:]-]/}" ]] || continue
|
|
164
|
-
|
|
165
|
-
if [[ "$who" != *"→"* && "$who" != *"->"* ]]; then
|
|
166
|
-
block "Handoff line is not a transition: $(printf '%s' "$who" | sed -E 's/^[[:space:]]*-[[:space:]]*//')" \
|
|
167
|
-
"Every line needs both sides: @from → @to."
|
|
168
|
-
fi
|
|
169
|
-
|
|
170
|
-
from=$(printf '%s' "$who" | sed -E 's/^[[:space:]]*-[[:space:]]*@?//; s/[[:space:]]*(→|->).*$//; s/[[:space:]]*$//')
|
|
171
|
-
to=$(printf '%s' "$who" | sed -E 's/^.*(→|->)[[:space:]]*@?//; s/[[:space:]]*$//')
|
|
172
|
-
artifact="${artifact#"${artifact%%[![:space:]]*}"}"
|
|
173
|
-
artifact="${artifact%"${artifact##*[![:space:]]}"}"
|
|
174
|
-
|
|
175
|
-
if [[ -z "$from" || -z "$to" ]]; then
|
|
176
|
-
block "Handoff line is missing one side of the transition: $(printf '%s' "$who" | sed -E 's/^[[:space:]]*-[[:space:]]*//')"
|
|
177
|
-
fi
|
|
178
|
-
if [[ -z "$artifact" || -z "${accept//[[:space:]]/}" ]]; then
|
|
179
|
-
block "Handoff line '$from → $to' is missing its artifact or acceptance field."
|
|
180
|
-
fi
|
|
181
|
-
|
|
182
|
-
for role in "$from" "$to"; do
|
|
183
|
-
printf '%s\n' "$roster" | awk -F'\t' -v t="$role" '$1 == t || $2 == t { hit = 1 } END { exit !hit }' ||
|
|
184
|
-
block "Handoff line '$from → $to' names @$role, which is not a member or role in $MEMBERS."
|
|
185
|
-
done
|
|
186
|
-
|
|
187
|
-
# The artifact a handoff promises must exist: a handoff naming a
|
|
188
|
-
# verification report that was never written is the same unbacked claim the
|
|
189
|
-
# DoD gate exists to catch (verification-evidence discipline).
|
|
190
|
-
artifact_path=""
|
|
191
|
-
if [[ -e "${spec_dir}${artifact}" ]]; then
|
|
192
|
-
artifact_path=$(absolute_existing_path "${spec_dir}${artifact}")
|
|
193
|
-
elif [[ -e "$artifact" ]]; then
|
|
194
|
-
artifact_path=$(absolute_existing_path "$artifact")
|
|
195
|
-
fi
|
|
196
|
-
if [[ -z "$artifact_path" ]]; then
|
|
197
|
-
block "Handoff line '$from → $to' names artifact '$artifact', which does not exist." \
|
|
198
|
-
"Produce it before recording the handoff, or fix the path (relative to $spec_dir or the project root)."
|
|
199
|
-
fi
|
|
200
|
-
|
|
201
|
-
case "$artifact_path" in
|
|
202
|
-
"$PROJECT_ROOT_REAL"/*) ;;
|
|
203
|
-
*) block "Handoff line '$from → $to' names artifact '$artifact' outside the project root." \
|
|
204
|
-
"Use an artifact inside $PROJECT_ROOT_REAL." ;;
|
|
205
|
-
esac
|
|
206
|
-
|
|
207
|
-
[[ "$artifact_path" == "$need_path" ]] && found_phase_line=1
|
|
208
|
-
done < <(printf '%s\n' "$section" | grep -E '^[[:space:]]*(-[[:space:]]*)?@' || true)
|
|
209
|
-
|
|
210
|
-
if (( found_phase_line == 0 )); then
|
|
211
|
-
block "The $phase phase produced $need, but no handoff line in $host names it." \
|
|
212
|
-
"Add the transition that hands $need to the next role."
|
|
213
|
-
fi
|
|
214
|
-
|
|
215
|
-
exit 0
|
|
@@ -1,55 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: design-taste
|
|
3
|
-
description: "A page or screen matches project UI, tokens, and look, or needs an AI design-tell scan."
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Design taste
|
|
7
|
-
|
|
8
|
-
Two jobs. Strip the generated look, and leave the project's own look behind. A page scrubbed of tells but built from model defaults still reads as generated at a glance, which is how every design skill that ships its own palette fails: three projects using it look like each other instead of like themselves.
|
|
9
|
-
|
|
10
|
-
## Order of work
|
|
11
|
-
|
|
12
|
-
1. **Read the direction.** `devos/standards/conventions.md`, sections Design system / tokens, Component conventions, Styling, Accessibility. Plus every rule under `devos/standards/rules/` whose glob matches the files you are about to touch.
|
|
13
|
-
2. **Read the real tokens, never recall them**. The theme file, the Tailwind config, the CSS custom properties, one existing screen the user already accepts. A palette recalled from training is a palette shared with every other project.
|
|
14
|
-
3. **No direction on file?** Settle it first, see below, an unstated axis resolves to the model default, never invent one silently.
|
|
15
|
-
4. **Declare the read in one line** before writing code: page kind, audience, direction, and where the palette and type come from. Ask one clarifying question only where the read genuinely diverges, never a list of them.
|
|
16
|
-
5. **Build.**
|
|
17
|
-
6. **Scan.** `python3 ${CLAUDE_SKILL_DIR}/scripts/slop-scan.py <paths you touched>` (if `${CLAUDE_SKILL_DIR}` was not expanded, it is this skill's own directory). Every FAIL is fixed. Every WARN is fixed or carries one stated reason.
|
|
18
|
-
7. **Audit** against [references/tells.md](references/tells.md) and answer two questions, one line each:
|
|
19
|
-
- Which parts of this would be identical if a different project ran the same prompt?
|
|
20
|
-
- Which visible string is invented: a name, a number, a customer, a metric?
|
|
21
|
-
|
|
22
|
-
Step 7 catches what a regex cannot. Skip it and you ship a page that passes the scan and still looks generated.
|
|
23
|
-
|
|
24
|
-
## Where the project's look comes from
|
|
25
|
-
|
|
26
|
-
Six axes decide whether a screen looks like this project or like the model: accent and neutral palette, type stack, corner-radius scale, spacing scale, shadow policy, density. Every axis left unspecified resolves to a model default, and that default is identical across every project on earth. That is the entire mechanism behind "all AI pages look the same".
|
|
27
|
-
|
|
28
|
-
So when they are unspecified, settle them once with the human and write them where they get re-read:
|
|
29
|
-
|
|
30
|
-
- The axes go in `conventions.md` under Design system / tokens, which already names them.
|
|
31
|
-
- What must hold on every future UI edit goes in a scoped rule at `devos/standards/rules/01-standards/<slug>.md`, then run `python3 ${CLAUDE_PLUGIN_ROOT}/skills/init/scripts/render-rule.py` on it so every installed tool attaches it at edit time.
|
|
32
|
-
|
|
33
|
-
Never invent a new artifact type to hold this, and never leave a palette in the conversation only.
|
|
34
|
-
|
|
35
|
-
## Hard rules
|
|
36
|
-
|
|
37
|
-
- Zero em dash and en dash in visible strings. Restructure the sentence.
|
|
38
|
-
- Every visible string is real or is a marked placeholder the human will replace. Never an invented customer, testimonial, or metric.
|
|
39
|
-
- Text and focus rings meet WCAG AA against their own background, in every theme the page ships.
|
|
40
|
-
- Every animation has a reduced-motion path.
|
|
41
|
-
- One theme per page. No section inverts mid-page unless the direction says it does.
|
|
42
|
-
- No product UI faked out of styled divs. A real screenshot, a real component, or nothing.
|
|
43
|
-
- This skill carries no palette, on purpose. Do not ask it for one.
|
|
44
|
-
|
|
45
|
-
## A reference the user brought
|
|
46
|
-
|
|
47
|
-
A linked URL or a pasted screenshot is material, not a specification. Name what is being taken (the grid, the type scale, the motion pacing) and what is not: never reproduce a competitor's page or lift their copy, that crosses from studying a reference into cloning it.
|
|
48
|
-
|
|
49
|
-
## Redesign
|
|
50
|
-
|
|
51
|
-
Audit before touching anything: what the current page does well, what breaks, what is load-bearing brand. State what stays. Logo, brand colour, product names, legal copy and prices never change silently.
|
|
52
|
-
|
|
53
|
-
## Not this skill's job
|
|
54
|
-
|
|
55
|
-
Charts and dashboards: the `dataviz` skill owns chart form and colour. Data-table UX. Choosing a component library or framework, which comes from `/devos:init`'s archetype detection and lands in `conventions.md`.
|