@agent-ix/quoin 0.4.0 → 0.4.1
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 +0 -8
- package/default-modules.yaml +16 -16
- package/package.json +1 -1
- package/skills/spec-ears-analysis/SKILL.md +89 -0
- package/skills/spec-matrix/SKILL.md +23 -0
- package/skills/spec-review/SKILL.md +4 -3
package/README.md
CHANGED
|
@@ -105,14 +105,6 @@ The default module set defines the spec archetypes and domain-object vocabulary.
|
|
|
105
105
|
- **`spec-risk-complexity-analysis`** — technical risk and volatility before tasking
|
|
106
106
|
- **`spec-security-analysis`** — applicable security standards and compliance traceability
|
|
107
107
|
|
|
108
|
-
### Agent Workflows
|
|
109
|
-
|
|
110
|
-
Multi-agent workflows that fan out, run lenses in parallel, and synthesize results:
|
|
111
|
-
|
|
112
|
-
- **`review`** — parallel review lenses → dedupe → sync
|
|
113
|
-
- **`matrix`** — coverage analysis and Test Matrix construction
|
|
114
|
-
- **`to-plan`** — requirements → dependency-aware TDD plan
|
|
115
|
-
|
|
116
108
|
## Install
|
|
117
109
|
|
|
118
110
|
Installing quoin into Claude is **two steps**: the CLI (from public npm) and the plugin
|
package/default-modules.yaml
CHANGED
|
@@ -10,73 +10,73 @@ schemaVersion: 1
|
|
|
10
10
|
name: quoin-default-modules
|
|
11
11
|
entries:
|
|
12
12
|
- name: spec-artifacts-iso
|
|
13
|
-
version: "0.
|
|
13
|
+
version: "0.5.0"
|
|
14
14
|
defaultEnabled: true
|
|
15
15
|
source:
|
|
16
16
|
type: git-subdir
|
|
17
17
|
url: agent-ix/spec-artifacts-iso
|
|
18
18
|
path: spec_artifacts_iso
|
|
19
|
-
ref: v0.
|
|
19
|
+
ref: v0.5.0
|
|
20
20
|
|
|
21
21
|
- name: spec-artifacts-app
|
|
22
|
-
version: "0.
|
|
22
|
+
version: "0.3.0"
|
|
23
23
|
defaultEnabled: true
|
|
24
24
|
source:
|
|
25
25
|
type: git-subdir
|
|
26
26
|
url: agent-ix/spec-artifacts-app
|
|
27
27
|
path: spec_artifacts_app
|
|
28
|
-
ref: v0.
|
|
28
|
+
ref: v0.3.0
|
|
29
29
|
|
|
30
30
|
- name: spec-artifacts-process
|
|
31
|
-
version: "0.
|
|
31
|
+
version: "0.5.0"
|
|
32
32
|
defaultEnabled: true
|
|
33
33
|
source:
|
|
34
34
|
type: git-subdir
|
|
35
35
|
url: agent-ix/spec-artifacts-process
|
|
36
36
|
path: spec_artifacts_process
|
|
37
|
-
ref: v0.
|
|
37
|
+
ref: v0.5.0
|
|
38
38
|
|
|
39
39
|
- name: spec-objects-business
|
|
40
|
-
version: "0.
|
|
40
|
+
version: "0.4.0"
|
|
41
41
|
defaultEnabled: true
|
|
42
42
|
source:
|
|
43
43
|
type: git-subdir
|
|
44
44
|
url: agent-ix/spec-objects-business
|
|
45
45
|
path: spec_objects_business
|
|
46
|
-
ref: v0.
|
|
46
|
+
ref: v0.4.0
|
|
47
47
|
|
|
48
48
|
- name: spec-objects-architecture
|
|
49
|
-
version: "0.
|
|
49
|
+
version: "0.4.0"
|
|
50
50
|
defaultEnabled: true
|
|
51
51
|
source:
|
|
52
52
|
type: git-subdir
|
|
53
53
|
url: agent-ix/spec-objects-architecture
|
|
54
54
|
path: spec_objects_architecture
|
|
55
|
-
ref: v0.
|
|
55
|
+
ref: v0.4.0
|
|
56
56
|
|
|
57
57
|
- name: spec-objects-enterprise
|
|
58
|
-
version: "0.
|
|
58
|
+
version: "0.3.0"
|
|
59
59
|
defaultEnabled: true
|
|
60
60
|
source:
|
|
61
61
|
type: git-subdir
|
|
62
62
|
url: agent-ix/spec-objects-enterprise
|
|
63
63
|
path: spec_objects_enterprise
|
|
64
|
-
ref: v0.
|
|
64
|
+
ref: v0.3.0
|
|
65
65
|
|
|
66
66
|
- name: spec-objects-operational
|
|
67
|
-
version: "0.
|
|
67
|
+
version: "0.4.0"
|
|
68
68
|
defaultEnabled: true
|
|
69
69
|
source:
|
|
70
70
|
type: git-subdir
|
|
71
71
|
url: agent-ix/spec-objects-operational
|
|
72
72
|
path: spec_objects_operational
|
|
73
|
-
ref: v0.
|
|
73
|
+
ref: v0.4.0
|
|
74
74
|
|
|
75
75
|
- name: spec-objects-security
|
|
76
|
-
version: "0.
|
|
76
|
+
version: "0.3.0"
|
|
77
77
|
defaultEnabled: true
|
|
78
78
|
source:
|
|
79
79
|
type: git-subdir
|
|
80
80
|
url: agent-ix/spec-objects-security
|
|
81
81
|
path: spec_objects_security
|
|
82
|
-
ref: v0.
|
|
82
|
+
ref: v0.3.0
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@agent-ix/quoin",
|
|
3
3
|
"description": "Spec-driven development for Claude Code — author validated, ISO/IEC/IEEE 29148-aligned specs, then plan and build against them.",
|
|
4
|
-
"version": "0.4.
|
|
4
|
+
"version": "0.4.1",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"files": [
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: spec-ears-analysis
|
|
3
|
+
description: Analyze requirement statements (FR/NFR/StR) for EARS requirement-grammar conformance and author a SpecReview of the findings.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# EARS Requirement-Grammar Analysis
|
|
7
|
+
|
|
8
|
+
This skill analyzes the natural-language **requirement statements** in a spec
|
|
9
|
+
(FR Description/Behavior/Constraints, NFR Statement, StR Stakeholder Need)
|
|
10
|
+
against **EARS** (Easy Approach to Requirements Syntax), and authors one
|
|
11
|
+
`SpecReview` document recording the findings.
|
|
12
|
+
|
|
13
|
+
It pairs the **deterministic engine check** (quire-rs FR-042, the `iso-spec-core`
|
|
14
|
+
grammar) with the **semantic judgment the engine cannot make** — together they
|
|
15
|
+
form the lens.
|
|
16
|
+
|
|
17
|
+
## Process
|
|
18
|
+
|
|
19
|
+
1. **Run the engine check.** From the repo root:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
quire validate --scope . "spec/**/*.md" --summary
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Read the `[ears:<check>]` warnings and the `GrammarSummary` line. The engine
|
|
26
|
+
flags, per statement:
|
|
27
|
+
- `non-singular` — more than one `shall` (can't map cleanly to one AC).
|
|
28
|
+
- `vague-response` — `support`/`handle`/`manage`/`process`/`provide`/
|
|
29
|
+
`enable`/`be able to` (unverifiable).
|
|
30
|
+
- `missing-subject` — no named system/actor before `shall`.
|
|
31
|
+
- `non-canonical-trigger` — `On …`/`Upon`/`After`/`During` instead of
|
|
32
|
+
`When …`/`While …`.
|
|
33
|
+
- `unclassifiable` — has `shall` but matches no EARS pattern.
|
|
34
|
+
|
|
35
|
+
These are advisory (they never fail `quire validate`); this lens records
|
|
36
|
+
them as review findings.
|
|
37
|
+
|
|
38
|
+
2. **Add the semantic judgment** (what the engine cannot check deterministically):
|
|
39
|
+
- **Keyword-vs-intent** — does a `When …` statement describe a momentary
|
|
40
|
+
*event*, or is it really a continuous `While …` *state* (or vice-versa)?
|
|
41
|
+
- **Genuinely concrete response** — a statement can pass the vague-verb
|
|
42
|
+
lexicon yet still be unmeasurable ("shall be fast", "shall be robust").
|
|
43
|
+
- **Right pattern for the obligation** — an unwanted condition stated as
|
|
44
|
+
`When …` instead of `If … then …`.
|
|
45
|
+
|
|
46
|
+
3. **Author the SpecReview.** Fetch the template once:
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
quoin write --types SpecReview
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Write one document to `spec/reviews/ears-conformance.md` with
|
|
53
|
+
`analysis: ears-conformance` in the frontmatter, a `## Summary` (one or two
|
|
54
|
+
sentences: how many statements, how many clean, the dominant defect), and a
|
|
55
|
+
validated `## Findings` table:
|
|
56
|
+
|
|
57
|
+
| ID | Severity | Summary | Refs |
|
|
58
|
+
| --- | --- | --- | --- |
|
|
59
|
+
| FND-001 | medium | FR-001 Description packs two `shall` into one statement — split into atomic requirements | FR-001 |
|
|
60
|
+
| FND-002 | low | FR-003 leads with `On startup, …`; use `When the service starts, …` | FR-003 |
|
|
61
|
+
|
|
62
|
+
- `Severity` ∈ `low`/`medium`/`high`. Suggested mapping: `non-singular`
|
|
63
|
+
and `missing-subject` → **medium** (they degrade traceability);
|
|
64
|
+
`vague-response`/`unclassifiable` → **medium** when the response is truly
|
|
65
|
+
unverifiable, else **low**; `non-canonical-trigger` → **low** (cosmetic).
|
|
66
|
+
Raise to **high** any statement whose ambiguity changes what gets built.
|
|
67
|
+
- `Refs` names the offending FR/NFR/StR id.
|
|
68
|
+
- Combine the engine findings with your step-2 semantic findings into one
|
|
69
|
+
table; attribute each row to its statement.
|
|
70
|
+
|
|
71
|
+
4. **Validate + record.**
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
quire validate --scope . "spec/reviews/ears-conformance.md"
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Fix any structural errors in the review doc. The doc syncs into filament-core
|
|
78
|
+
as a `SpecReview` artifact like every other analysis lens.
|
|
79
|
+
|
|
80
|
+
## Notes
|
|
81
|
+
|
|
82
|
+
- Scope is **requirement-bearing** artifacts only: FR, NFR, StR. US stories
|
|
83
|
+
(`As a / I want / So that`) and tests are out of scope.
|
|
84
|
+
- This lens is advisory by default. To make EARS a **gate** for a converted
|
|
85
|
+
repo, run `quire validate --strict` in that repo's CI — `--strict` escalates
|
|
86
|
+
the EARS warnings to a failing exit.
|
|
87
|
+
- Per-archetype dialects the engine already applies (don't re-flag them): an
|
|
88
|
+
enumerated `The X SHALL:` + numbered list is one statement; StR may use a
|
|
89
|
+
stakeholder subject; an NFR with no trigger is fine.
|
|
@@ -16,6 +16,29 @@ Use this skill to create the requirements Test Matrix and ensure comprehensive c
|
|
|
16
16
|
5. State Transition: Test all valid state transitions (if applicable).
|
|
17
17
|
6. Edge Case: Identify and test extreme/unusual scenarios.
|
|
18
18
|
|
|
19
|
+
## EARS precondition (atomic, mappable requirements)
|
|
20
|
+
|
|
21
|
+
Coverage (Rule 1) is only meaningful when each requirement states **one**
|
|
22
|
+
obligation — a statement packing two `shall` clauses cannot map cleanly to one
|
|
23
|
+
Acceptance Criterion, so its matrix row is ambiguous. Before building the
|
|
24
|
+
matrix, run the EARS requirement-grammar check:
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
quire validate --scope . "spec/**/*.md" --summary
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Treat these `[ears:…]` findings as **un-mappable requirements to fix first**,
|
|
31
|
+
not coverage you can claim:
|
|
32
|
+
|
|
33
|
+
- `non-singular` — split the statement into one requirement per `shall`, then
|
|
34
|
+
map each to its own AC/TC.
|
|
35
|
+
- `unclassifiable` / `missing-subject` — the obligation is unclear; clarify the
|
|
36
|
+
requirement before authoring a TC against it.
|
|
37
|
+
|
|
38
|
+
Do not mark the matrix ✅ Complete while non-singular or unclassifiable
|
|
39
|
+
requirements remain — the coverage they appear to have is illusory. (The check
|
|
40
|
+
is advisory; this skill treats it as a quality gate for the matrix.)
|
|
41
|
+
|
|
19
42
|
## Process
|
|
20
43
|
|
|
21
44
|
1. Initialize:
|
|
@@ -17,10 +17,10 @@ Before reviewing, present these options to the user and let them choose:
|
|
|
17
17
|
|
|
18
18
|
- **base** — the **Checklist** only: ID formats, US/FR/TC quality, and the six coverage
|
|
19
19
|
rules. No analysis skills.
|
|
20
|
-
- **all** — `base` plus all
|
|
21
|
-
- **subset** — `base` plus the analyses the user picks from the
|
|
20
|
+
- **all** — `base` plus all seven analyses below.
|
|
21
|
+
- **subset** — `base` plus the analyses the user picks from the seven below.
|
|
22
22
|
|
|
23
|
-
The
|
|
23
|
+
The seven analyses:
|
|
24
24
|
|
|
25
25
|
| Analysis | Skill |
|
|
26
26
|
| --- | --- |
|
|
@@ -30,6 +30,7 @@ The six analyses:
|
|
|
30
30
|
| evidence | `spec-evidence-analysis` |
|
|
31
31
|
| risk-complexity | `spec-risk-complexity-analysis` |
|
|
32
32
|
| scope-boundary | `spec-scope-boundary-analysis` |
|
|
33
|
+
| ears-conformance | `spec-ears-analysis` |
|
|
33
34
|
|
|
34
35
|
## Process
|
|
35
36
|
|