@andresmassello/uscha 1.51.3 → 1.53.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/README.md +20 -6
- package/package.json +1 -1
- package/uscha-kit/.claude/skills/uscha-adr-refine/SKILL.md +203 -161
- package/uscha-kit/.claude/skills/uscha-characterize/SKILL.md +40 -0
- package/uscha-kit/.claude/skills/uscha-devloop/SKILL.md +40 -0
- package/uscha-kit/.claude/skills/uscha-discovery/SKILL.md +203 -161
- package/uscha-kit/.claude/skills/uscha-mirador/SKILL.md +192 -168
- package/uscha-kit/.claude/skills/uscha-reverse-discovery/SKILL.md +42 -0
- package/uscha-kit/.claude/skills/uscha-rubric/SKILL.md +119 -79
- package/uscha-kit/.claude/skills/uscha-status/SKILL.md +24 -0
- package/uscha-kit/.claude/skills/uscha-sysdoc/SKILL.md +128 -88
- package/uscha-kit/.claude-plugin/plugin.json +1 -1
- package/uscha-kit/.codex-plugin/plugin.json +1 -1
- package/uscha-kit/README.md +1 -1
- package/uscha-kit/VERSION +1 -1
- package/uscha-kit/install-uscha.py +68 -40
- package/uscha-kit/skills/uscha-adr-refine/SKILL.md +203 -161
- package/uscha-kit/skills/uscha-characterize/SKILL.md +40 -0
- package/uscha-kit/skills/uscha-devloop/SKILL.md +40 -0
- package/uscha-kit/skills/uscha-discovery/SKILL.md +203 -161
- package/uscha-kit/skills/uscha-mirador/SKILL.md +192 -168
- package/uscha-kit/skills/uscha-reverse-discovery/SKILL.md +42 -0
- package/uscha-kit/skills/uscha-rubric/SKILL.md +119 -79
- package/uscha-kit/skills/uscha-status/SKILL.md +24 -0
- package/uscha-kit/skills/uscha-sysdoc/SKILL.md +128 -88
- package/uscha-kit/uscha.config.json +1 -1
|
@@ -1,79 +1,119 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: uscha-rubric
|
|
3
|
-
description: >
|
|
4
|
-
Grade the change against the versioned RUBRIC.md (the ACCEPTANCE of the
|
|
5
|
-
non-testable: conventions, error-handling sanity, API ergonomics, doc quality)
|
|
6
|
-
and ingest the verdict into the ledger. This skill is a THIN ADAPTER for
|
|
7
|
-
Claude Code: the portable core is templates/rubric-grader-prompt.md (works on
|
|
8
|
-
Codex, Gemini CLI, Cursor, raw API, or a human) + the vendor-neutral JSON
|
|
9
|
-
contract that `qa_ledger.py rubric-ingest` validates. Advisory by default;
|
|
10
|
-
gates only when the human declares it. Invoke for "grade the rubric",
|
|
11
|
-
"evaluá la rúbrica", "rubric pass".
|
|
12
|
-
allowed-tools: Read, Write, Glob, Grep, Bash
|
|
13
|
-
disable-model-invocation: false
|
|
14
|
-
---
|
|
15
|
-
|
|
16
|
-
# uscha-rubric — grade the non-testable against versioned criteria (adapter)
|
|
17
|
-
|
|
18
|
-
**Architecture note (read this first).** You are the Claude Code ADAPTER of a
|
|
19
|
-
vendor-neutral layer. The core is: `RUBRIC.md` (versioned criteria) + the JSON
|
|
20
|
-
contract + `qa_ledger.py rubric-ingest` (stdlib, runs anywhere). ANY runner can be
|
|
21
|
-
the grader — this skill just wraps the neutral prompt so Claude Code users get it
|
|
22
|
-
in one command. Never add Claude-specific behavior to the contract.
|
|
23
|
-
|
|
24
|
-
##
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
##
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
1
|
+
---
|
|
2
|
+
name: uscha-rubric
|
|
3
|
+
description: >
|
|
4
|
+
Grade the change against the versioned RUBRIC.md (the ACCEPTANCE of the
|
|
5
|
+
non-testable: conventions, error-handling sanity, API ergonomics, doc quality)
|
|
6
|
+
and ingest the verdict into the ledger. This skill is a THIN ADAPTER for
|
|
7
|
+
Claude Code: the portable core is templates/rubric-grader-prompt.md (works on
|
|
8
|
+
Codex, Gemini CLI, Cursor, raw API, or a human) + the vendor-neutral JSON
|
|
9
|
+
contract that `qa_ledger.py rubric-ingest` validates. Advisory by default;
|
|
10
|
+
gates only when the human declares it. Invoke for "grade the rubric",
|
|
11
|
+
"evaluá la rúbrica", "rubric pass".
|
|
12
|
+
allowed-tools: Read, Write, Glob, Grep, Bash
|
|
13
|
+
disable-model-invocation: false
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
# uscha-rubric — grade the non-testable against versioned criteria (adapter)
|
|
17
|
+
|
|
18
|
+
**Architecture note (read this first).** You are the Claude Code ADAPTER of a
|
|
19
|
+
vendor-neutral layer. The core is: `RUBRIC.md` (versioned criteria) + the JSON
|
|
20
|
+
contract + `qa_ledger.py rubric-ingest` (stdlib, runs anywhere). ANY runner can be
|
|
21
|
+
the grader — this skill just wraps the neutral prompt so Claude Code users get it
|
|
22
|
+
in one command. Never add Claude-specific behavior to the contract.
|
|
23
|
+
|
|
24
|
+
## Orientation markers (non-negotiable)
|
|
25
|
+
|
|
26
|
+
The operator must never have to ask "where am I?" or "what happens now?". Two markers, always.
|
|
27
|
+
They are navigation, not ceremony: one line per turn, one block at the end.
|
|
28
|
+
|
|
29
|
+
**Open every turn with a breadcrumb**, then the content:
|
|
30
|
+
|
|
31
|
+
`[uscha · rubric · <step> → <target>]`
|
|
32
|
+
|
|
33
|
+
- `<step>` — `Q<n>` for a question, `pass <n>` for a loop iteration, `step <n>` otherwise.
|
|
34
|
+
Count what has actually happened. **Never write a denominator** (`Q4/12`): this phase
|
|
35
|
+
converges, its length is not known in advance, and an invented total is exactly the kind of
|
|
36
|
+
narrated number the method forbids. **When the ledger already measures the count** (the QA
|
|
37
|
+
loop's `loop_count`), use the measured number — never keep a parallel tally of your own.
|
|
38
|
+
- `<target>` — the artifact this turn feeds (`SPEC`, `ADR-003`, `ACCEPTANCE`, `LEDGER`,
|
|
39
|
+
`RECEIVED`, ...). Drop `→ <target>` only when the turn genuinely feeds none.
|
|
40
|
+
|
|
41
|
+
**Close with the close block ONCE, when the skill finishes** — not on every turn. Ending
|
|
42
|
+
without it is a defect, even when the phase converged cleanly:
|
|
43
|
+
|
|
44
|
+
```
|
|
45
|
+
[uscha · rubric · CLOSED]
|
|
46
|
+
Produced: <files actually written, or "nothing">
|
|
47
|
+
Blocks: <what stands between here and the next phase, or "nothing">
|
|
48
|
+
Next: <the next action, and why it is that one>
|
|
49
|
+
Run: <the exact command or skill to invoke>
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
This is **not** the implementation handoff some skills also emit: that one is a prompt for
|
|
53
|
+
whoever implements next, this one is navigation for the human operator, and both can appear.
|
|
54
|
+
|
|
55
|
+
`Blocks` and `Next` are **derived from the state you just produced** — never copied from a
|
|
56
|
+
fixed route, **including any `Flow:` line in this file**. Those lines are the nominal path;
|
|
57
|
+
open ADR experiments, an unclosed spike, an unapproved golden or a red gate all change what
|
|
58
|
+
genuinely comes next, and the derived answer wins. If the next phase cannot start yet, name it
|
|
59
|
+
and say exactly what unblocks it.
|
|
60
|
+
|
|
61
|
+
Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`, `Produced`,
|
|
62
|
+
`Blocks`, `Next`, `Run`) verbatim — they are the method's vocabulary and the smoke checks them.
|
|
63
|
+
|
|
64
|
+
## Protocol
|
|
65
|
+
|
|
66
|
+
1. **Locate the rubric**: `defaults.rubric.file` in `uscha.config.json`, else
|
|
67
|
+
`./RUBRIC.md`. If absent, offer to create one from `templates/RUBRIC.md` and STOP
|
|
68
|
+
(the criteria are the human's to approve — propose, don't impose).
|
|
69
|
+
2. **Validate structure first** (facts block):
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
QL="./.claude/skills/uscha-devloop/qa_ledger.py"
|
|
73
|
+
[ -f "$QL" ] || QL="$HOME/.codex/skills/uscha-devloop/qa_ledger.py"
|
|
74
|
+
[ -f "$QL" ] || QL="$HOME/plugins/uscha/skills/uscha-devloop/qa_ledger.py"
|
|
75
|
+
[ -f "$QL" ] || QL="$HOME/.claude/skills/uscha-devloop/qa_ledger.py"
|
|
76
|
+
python3 $QL spec-check --rubric RUBRIC.md # exit 1 = fix the rubric before grading
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
3. **Grade with ISOLATED context** — follow `templates/rubric-grader-prompt.md` to
|
|
80
|
+
the letter: read ONLY the diff + RUBRIC.md (not the maker's reasoning, not the PR
|
|
81
|
+
body). For every criterion emit `pass|fail`; **evidence `file:line` is mandatory
|
|
82
|
+
for any verdict that affects the score** (a positive's pass, a negative's fail) —
|
|
83
|
+
without it the engine discards the verdict. Anchors calibrate you; when in doubt,
|
|
84
|
+
fail (the optimist bias is the failure mode this layer exists to counter).
|
|
85
|
+
4. **Write the contract JSON** to `reports/rubric-grade.json`:
|
|
86
|
+
|
|
87
|
+
```json
|
|
88
|
+
{"criteria": [{"id": "RB-01", "verdict": "pass",
|
|
89
|
+
"evidence": "src/x.py:42 — ...", "note": "..."}]}
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
5. **Ingest** (the ledger validates IDs, applies evidence-or-nothing, computes the
|
|
93
|
+
weighted score vs threshold, and persists — advisory by default):
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
python3 $QL rubric-ingest --repo <REPO> --report reports/rubric-grade.json \
|
|
97
|
+
--iteration <N> # add --gate ONLY if the human declared it
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
A below-threshold score with the gate declared (config `defaults.rubric.gate: true`
|
|
101
|
+
or `--gate`) blocks convergence and caps readiness ≤65 through the existing ledger
|
|
102
|
+
plumbing. Without the declaration it advises — never silently escalate it yourself.
|
|
103
|
+
|
|
104
|
+
## Non-negotiables
|
|
105
|
+
|
|
106
|
+
- **Maker ≠ grader**: never grade a change you authored in this same context. Run
|
|
107
|
+
the grade in a fresh/isolated pass (that separation is the entire value).
|
|
108
|
+
- **Evidence-or-nothing**: a verdict without a `file:line` citation does not count —
|
|
109
|
+
the engine enforces it, you comply with it.
|
|
110
|
+
- The rubric file is the HUMAN's criterion: propose edits, never rewrite it silently
|
|
111
|
+
(tracked-markdown protocol applies).
|
|
112
|
+
- This layer never replaces the hard gates (tests, golden, gate-check, simplicity):
|
|
113
|
+
it is the structured-guess layer — facts block, guesses advise.
|
|
114
|
+
|
|
115
|
+
## Relationship to the other skills
|
|
116
|
+
|
|
117
|
+
- `uscha-devloop` runs this in Phase 3b alongside gate-check when a rubric exists.
|
|
118
|
+
- `uscha-discovery` / `uscha-adr-refine` are where the human's quality criteria
|
|
119
|
+
crystallize — a RUBRIC.md can be drafted there (step: quality bar).
|
|
@@ -19,6 +19,30 @@ skill (**pull** — one screen when the human asks), and the **mirador** (bird's
|
|
|
19
19
|
HTML). This skill exists because some surfaces never show a statusline; the answer
|
|
20
20
|
is the same data, printed in chat when requested.
|
|
21
21
|
|
|
22
|
+
## Orientation markers (non-negotiable)
|
|
23
|
+
|
|
24
|
+
The operator must never have to ask "where am I?" or "what happens now?".
|
|
25
|
+
|
|
26
|
+
This skill is a **one-shot read-only readout**: its block IS the answer. It therefore does NOT
|
|
27
|
+
take the conversational close block — that would be exactly the padding this skill forbids.
|
|
28
|
+
It carries the two minimal markers instead.
|
|
29
|
+
|
|
30
|
+
**Open with a breadcrumb:**
|
|
31
|
+
|
|
32
|
+
`[uscha · status · step <n> → <target>]`
|
|
33
|
+
|
|
34
|
+
**End with the two routing lines, and nothing else:**
|
|
35
|
+
|
|
36
|
+
```
|
|
37
|
+
Next: <the next action, derived from what this readout just showed>
|
|
38
|
+
Run: <the exact command or skill to invoke>
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
`Next` is **derived** from the state you just read — never copied from a fixed route,
|
|
42
|
+
including any `Flow:` line in this file. If nothing is actionable, say that plainly rather
|
|
43
|
+
than inventing a step. Keep the CONTENT in the conversation's language and the labels
|
|
44
|
+
(`Next`, `Run`) verbatim — the smoke suite checks for them.
|
|
45
|
+
|
|
22
46
|
## Contract
|
|
23
47
|
|
|
24
48
|
- **Read-only over persisted facts.** Never run `readiness`, tests, or gates. The
|
|
@@ -1,88 +1,128 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: uscha-sysdoc
|
|
3
|
-
description: >
|
|
4
|
-
Generate a single self-contained, navigable HTML deck (PowerPoint-style, keyboard +
|
|
5
|
-
click navigation) documenting a system in two parallel tracks: a commercial/CEO view
|
|
6
|
-
and a technical view. Pulls real metrics from QA-LEDGER.json, includes inline SVG
|
|
7
|
-
diagrams, dark control-room aesthetic. Invoke for "document this system",
|
|
8
|
-
"make the system deck", "commercial + tech doc". Pairs with the dev-loop skill.
|
|
9
|
-
allowed-tools: Read, Write, Glob, Grep, Bash
|
|
10
|
-
disable-model-invocation: false
|
|
11
|
-
---
|
|
12
|
-
|
|
13
|
-
# sys-doc — two-view system deck generator
|
|
14
|
-
|
|
15
|
-
Produce ONE self-contained `.html` file (no external assets, no CDN, no localStorage)
|
|
16
|
-
that reads like a slide deck and documents the system on two tracks the reader can
|
|
17
|
-
switch between at any time:
|
|
18
|
-
|
|
19
|
-
- **Commercial / CEO track** — what the system does, the value, the risk posture, the
|
|
20
|
-
status. No code. Plain business language. Money/time/reliability framing.
|
|
21
|
-
- **Technical track** — architecture, modules, data flow, contracts, QA results,
|
|
22
|
-
coverage, known deferred issues.
|
|
23
|
-
|
|
24
|
-
##
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
[
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
-
|
|
72
|
-
|
|
73
|
-
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
1
|
+
---
|
|
2
|
+
name: uscha-sysdoc
|
|
3
|
+
description: >
|
|
4
|
+
Generate a single self-contained, navigable HTML deck (PowerPoint-style, keyboard +
|
|
5
|
+
click navigation) documenting a system in two parallel tracks: a commercial/CEO view
|
|
6
|
+
and a technical view. Pulls real metrics from QA-LEDGER.json, includes inline SVG
|
|
7
|
+
diagrams, dark control-room aesthetic. Invoke for "document this system",
|
|
8
|
+
"make the system deck", "commercial + tech doc". Pairs with the dev-loop skill.
|
|
9
|
+
allowed-tools: Read, Write, Glob, Grep, Bash
|
|
10
|
+
disable-model-invocation: false
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
# sys-doc — two-view system deck generator
|
|
14
|
+
|
|
15
|
+
Produce ONE self-contained `.html` file (no external assets, no CDN, no localStorage)
|
|
16
|
+
that reads like a slide deck and documents the system on two tracks the reader can
|
|
17
|
+
switch between at any time:
|
|
18
|
+
|
|
19
|
+
- **Commercial / CEO track** — what the system does, the value, the risk posture, the
|
|
20
|
+
status. No code. Plain business language. Money/time/reliability framing.
|
|
21
|
+
- **Technical track** — architecture, modules, data flow, contracts, QA results,
|
|
22
|
+
coverage, known deferred issues.
|
|
23
|
+
|
|
24
|
+
## Orientation markers (non-negotiable)
|
|
25
|
+
|
|
26
|
+
The operator must never have to ask "where am I?" or "what happens now?". Two markers, always.
|
|
27
|
+
They are navigation, not ceremony: one line per turn, one block at the end.
|
|
28
|
+
|
|
29
|
+
**Open every turn with a breadcrumb**, then the content:
|
|
30
|
+
|
|
31
|
+
`[uscha · sysdoc · <step> → <target>]`
|
|
32
|
+
|
|
33
|
+
- `<step>` — `Q<n>` for a question, `pass <n>` for a loop iteration, `step <n>` otherwise.
|
|
34
|
+
Count what has actually happened. **Never write a denominator** (`Q4/12`): this phase
|
|
35
|
+
converges, its length is not known in advance, and an invented total is exactly the kind of
|
|
36
|
+
narrated number the method forbids. **When the ledger already measures the count** (the QA
|
|
37
|
+
loop's `loop_count`), use the measured number — never keep a parallel tally of your own.
|
|
38
|
+
- `<target>` — the artifact this turn feeds (`SPEC`, `ADR-003`, `ACCEPTANCE`, `LEDGER`,
|
|
39
|
+
`RECEIVED`, ...). Drop `→ <target>` only when the turn genuinely feeds none.
|
|
40
|
+
|
|
41
|
+
**Close with the close block ONCE, when the skill finishes** — not on every turn. Ending
|
|
42
|
+
without it is a defect, even when the phase converged cleanly:
|
|
43
|
+
|
|
44
|
+
```
|
|
45
|
+
[uscha · sysdoc · CLOSED]
|
|
46
|
+
Produced: <files actually written, or "nothing">
|
|
47
|
+
Blocks: <what stands between here and the next phase, or "nothing">
|
|
48
|
+
Next: <the next action, and why it is that one>
|
|
49
|
+
Run: <the exact command or skill to invoke>
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
This is **not** the implementation handoff some skills also emit: that one is a prompt for
|
|
53
|
+
whoever implements next, this one is navigation for the human operator, and both can appear.
|
|
54
|
+
|
|
55
|
+
`Blocks` and `Next` are **derived from the state you just produced** — never copied from a
|
|
56
|
+
fixed route, **including any `Flow:` line in this file**. Those lines are the nominal path;
|
|
57
|
+
open ADR experiments, an unclosed spike, an unapproved golden or a red gate all change what
|
|
58
|
+
genuinely comes next, and the derived answer wins. If the next phase cannot start yet, name it
|
|
59
|
+
and say exactly what unblocks it.
|
|
60
|
+
|
|
61
|
+
Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`, `Produced`,
|
|
62
|
+
`Blocks`, `Next`, `Run`) verbatim — they are the method's vocabulary and the smoke checks them.
|
|
63
|
+
|
|
64
|
+
## Inputs
|
|
65
|
+
|
|
66
|
+
1. **Metrics (authoritative):** run the ledger summary and use its numbers verbatim —
|
|
67
|
+
never invent figures.
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
QL="./.claude/skills/uscha-devloop/qa_ledger.py" # instalacion por proyecto
|
|
71
|
+
[ -f "$QL" ] || QL="$HOME/.codex/skills/uscha-devloop/qa_ledger.py" # Codex raw-skills install
|
|
72
|
+
[ -f "$QL" ] || QL="$HOME/plugins/uscha/skills/uscha-devloop/qa_ledger.py" # Codex plugin install
|
|
73
|
+
[ -f "$QL" ] || QL="$HOME/.claude/skills/uscha-devloop/qa_ledger.py" # Claude global install
|
|
74
|
+
python3 $QL summary --json > /tmp/qa-summary.json
|
|
75
|
+
python3 $QL readiness --json > /tmp/qa-readiness.json
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
From the summary use: `total_steps`, `by_tool`, `by_repo`, `aggregate`, `escalations`.
|
|
79
|
+
From readiness use: `score`, `status`, `cap_reason`, `dimensions`, `acceptance`,
|
|
80
|
+
`by_repo`. Render readiness as a **semaphore widget** at the top of slide 5 and as a
|
|
81
|
+
per-repo readiness column on the technical QA slide: green ≥80, amber 50–79, red <50,
|
|
82
|
+
and always print the `cap_reason` when a hard cap is active.
|
|
83
|
+
|
|
84
|
+
2. **System understanding:** read the ADR/PLAN, CLAUDE.md, module layout, and key
|
|
85
|
+
contracts to describe architecture and value. If no ledger exists, ask whether to
|
|
86
|
+
proceed without QA metrics (the deck still works, just without the QA section).
|
|
87
|
+
|
|
88
|
+
3. **Tracked-markdown protocol:** the HTML output itself is not tracked markdown, so
|
|
89
|
+
generate freely. But if asked to also update a tracked `.md`, ask for its current
|
|
90
|
+
version first.
|
|
91
|
+
|
|
92
|
+
## Structure (each is one navigable slide)
|
|
93
|
+
|
|
94
|
+
1. **Title** — system name, one-line purpose, date, run id.
|
|
95
|
+
2. **Track switcher** — persistent toggle: Commercial ⇄ Technical (affects which
|
|
96
|
+
slides/sections show; default Commercial).
|
|
97
|
+
3. Commercial: **What it does** (plain language, the job it removes).
|
|
98
|
+
4. Commercial: **Value & status** (what's done, what's in flight, risk posture).
|
|
99
|
+
5. Commercial: **Quality at a glance** — coverage %, tests count, a simple
|
|
100
|
+
"issues found and resolved" readout from `by_tool`. No jargon.
|
|
101
|
+
6. Technical: **Architecture** — inline SVG: modules/repos as boxes, data flow as
|
|
102
|
+
arrows, external systems (DB, external APIs, devices) distinct.
|
|
103
|
+
7. Technical: **Key contracts / interfaces** — the seams between repos/modules.
|
|
104
|
+
8. Technical: **QA results** — per-tool table (reported / fixed / %fixed / deferred /
|
|
105
|
+
suppressed), coverage per repo, tests/kLOC, escalations list.
|
|
106
|
+
9. Technical: **Deferred issues** — summarize `ISSUES-DEFERRED.md` honestly.
|
|
107
|
+
10. **Smoke checklist** — the manual verification steps.
|
|
108
|
+
|
|
109
|
+
## Build constraints
|
|
110
|
+
|
|
111
|
+
- Single `.html`, all CSS/JS inline. Works opened directly from disk and deployable to
|
|
112
|
+
Cloudflare Pages / S3 as-is.
|
|
113
|
+
- **No localStorage / sessionStorage** (won't run in some sandboxes). Hold nav state in
|
|
114
|
+
JS variables only.
|
|
115
|
+
- Navigation: arrow keys (← →), on-screen prev/next, a slide index/dots, and Esc for an
|
|
116
|
+
overview grid. Slide counter visible.
|
|
117
|
+
- Diagrams are hand-authored inline `<svg>` using `currentColor`/CSS variables so they
|
|
118
|
+
theme with the deck. No raster images, no external diagram libs.
|
|
119
|
+
- Aesthetic: dark control-room (deep neutral background, one accent, high-contrast
|
|
120
|
+
mono for technical figures), but keep the Commercial track clean and uncluttered.
|
|
121
|
+
- Accessible: semantic headings, `aria-label`s on nav controls, visible focus, contrast
|
|
122
|
+
AA. Readable when printed (print stylesheet flattens slides to a linear document).
|
|
123
|
+
|
|
124
|
+
## Output
|
|
125
|
+
|
|
126
|
+
Write to `docs/system-deck.html` (or the path the human gives). Then state the file
|
|
127
|
+
path and the two or three things the reader should look at first. Do not paste the HTML
|
|
128
|
+
into chat — present the file.
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
|
|
3
3
|
"name": "uscha",
|
|
4
|
-
"version": "1.
|
|
4
|
+
"version": "1.53.0",
|
|
5
5
|
"displayName": "Uscha",
|
|
6
6
|
"description": "Spec-driven development for LLM coding agents: 9 skills (discovery, adr-refine, reverse-discovery, characterize, devloop, sysdoc, rubric, mirador, status) + a stdlib measurement engine (qa_ledger.py, 29 subcommands + universal installer + npm/npx router). Facts block, guesses advise; the human approves.",
|
|
7
7
|
"author": {
|
package/uscha-kit/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# uscha-kit
|
|
2
2
|
|
|
3
|
-
**Kit version:** v1.
|
|
3
|
+
**Kit version:** v1.53.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
|
|
4
4
|
|
|
5
5
|
Spec-driven orchestrator + multi-repo QA for Claude Code, with a deterministic ledger.
|
|
6
6
|
**Nine skills** (`uscha-discovery`, `uscha-adr-refine`, `uscha-devloop`, `uscha-sysdoc`, `uscha-reverse-discovery`,
|
package/uscha-kit/VERSION
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
uscha-kit 1.
|
|
1
|
+
uscha-kit 1.53.0
|