@agent-ix/quoin 0.5.0 → 0.5.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/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.5.0",
4
+ "version": "0.5.1",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "files": [
@@ -42,6 +42,21 @@ file under the matching directory:
42
42
  > If a request asks for functional requirements and you produced only table rows
43
43
  > in `spec.md`, the request is **not done** — create the `FR-XXX.md` files.
44
44
 
45
+ ## Writing good requirements
46
+
47
+ The templates and Quire enforce *shape*; you supply the *judgment*. Author it well
48
+ here so `spec-review` has less to send back. Three principles — full guidance with
49
+ examples in [references/writing-good-requirements.md](references/writing-good-requirements.md):
50
+
51
+ - **Scope: tight beats broad.** Prefer a narrow spec that fully defines its slice over
52
+ a sprawling, vague one. Treat `spec.md` §2.2 Out of Scope as first-class — decide
53
+ your non-goals deliberately; an empty Out-of-Scope is a smell.
54
+ - **User stories: INVEST + no solution-prescribing.** Describe the user need with a
55
+ real "so that …"; let the FRs pick the mechanism.
56
+ - **Acceptance criteria: cover the unhappy paths, be concrete.** Author happy/error/edge
57
+ and negative cases up front, in measurable terms ("returns HTTP 422 within 200ms",
58
+ not "handles errors gracefully").
59
+
45
60
  ## Process
46
61
 
47
62
  Run only the steps the request needs; stop after IT.
@@ -56,9 +71,12 @@ Run only the steps the request needs; stop after IT.
56
71
  - `spec.md` — **REQUIRED when starting a new spec**: the
57
72
  `type: master-requirements` root/index at `spec/spec.md`, authored from
58
73
  `assets/spec-template.md` (or `assets/app-spec-template.md` for an
59
- application). Then → StR → US →
74
+ application); keep scope tight and fill Out of Scope deliberately
75
+ (see [references/writing-good-requirements.md](references/writing-good-requirements.md)).
76
+ Then → StR → US (INVEST, no solution-prescribing — same reference) →
60
77
  **derive FR from US** (see [references/us-to-fr.md](references/us-to-fr.md))
61
- → FR → NFR → IT (see [references/integration-tests.md](references/integration-tests.md)).
78
+ → FR (cover unhappy paths, measurable ACs — same reference)
79
+ → NFR → IT (see [references/integration-tests.md](references/integration-tests.md)).
62
80
  4. Keep traceability in frontmatter `relationships:` (e.g. a US `traces_to` its
63
81
  FRs; an FR/NFR/IT links back to the US/FR it serves).
64
82
  5. Run `quire validate <glob> [glob2 ...]` over the changed spec scope and fix
@@ -80,6 +98,9 @@ each with an Acceptance Criteria table (the `fr.md` skeleton enforces the shape)
80
98
 
81
99
  - Derive FRs from the driving user story — see
82
100
  [references/us-to-fr.md](references/us-to-fr.md).
101
+ - Make the ACs count: cover happy/error/edge and negative cases in concrete,
102
+ measurable terms — see
103
+ [references/writing-good-requirements.md](references/writing-good-requirements.md).
83
104
  - A behavioral FR has no `object:` field. A **domain-typed** FR carries
84
105
  `object: <type>` (e.g. `entity`, `event`, `api_endpoint`, `process`,
85
106
  `configuration`) and uses that type's structural template. Look up the
@@ -0,0 +1,61 @@
1
+ # Writing Good Requirements
2
+
3
+ Load this when authoring StR/US/FR/NFR artifacts. The templates and Quire enforce
4
+ *shape*; this file carries the *judgment* that makes a requirement good, not just
5
+ well-formed. Authoring well here means `spec-review` has less to send back.
6
+
7
+ ## Scope: tight beats broad
8
+
9
+ A narrow spec that fully defines its slice beats a sprawling one full of gaps.
10
+ Resist widening scope to "cover everything" — an expansive, vague spec is worse than
11
+ a tight, sharp one.
12
+
13
+ Treat the `spec.md` §2.2 **Out of Scope** list as first-class. Deliberately decide
14
+ what you are **not** building and write it down — an empty Out-of-Scope section is a
15
+ smell, not a default. Naming non-goals is how you prevent scope creep during
16
+ implementation.
17
+
18
+ > **Bad:** §2.2 left empty; §2.1 In Scope reads "all user-facing features".
19
+ > **Good:** In Scope: "CSV import of contacts". Out of Scope: "XLSX/JSON import,
20
+ > de-duplication, field mapping UI — see future work."
21
+
22
+ ## User stories: INVEST + anti-patterns
23
+
24
+ Aim for **INVEST** stories: **I**ndependent, **N**egotiable, **V**aluable,
25
+ **E**stimable, **S**mall, **T**estable.
26
+
27
+ Catch these anti-patterns while authoring, not in review:
28
+
29
+ - **Vagueness** — "make it faster" says nothing testable. Name the user, the want,
30
+ and a measurable outcome.
31
+ - **Solution-prescribing** — "add a dropdown menu" prescribes a mechanism. A user
32
+ story describes the *need*; the FRs choose the mechanism. If the US already names
33
+ the implementation, you have skipped the problem.
34
+ - **Missing rationale** — every US carries a real "so that …". If you can't state the
35
+ value, question whether the story belongs in the spec.
36
+ - **Internal focus** — "so that the team has less to maintain" benefits the team, not
37
+ the user. Frame the value around the user/stakeholder outcome.
38
+
39
+ > **Bad:** "As a user, I want a dropdown to pick a timezone."
40
+ > **Good:** "As a traveling user, I want event times shown in my current timezone so
41
+ > that I don't miss meetings after I change locations." (The picker, if any, is an FR.)
42
+
43
+ ## Acceptance criteria: cover the unhappy paths, be concrete
44
+
45
+ ACs are authored *here*, with the US/FR — don't defer coverage thinking to
46
+ `spec-matrix`. Front-load it:
47
+
48
+ - **Happy / error / edge from the start.** Walk the same ground the Six Coverage Rules
49
+ (`spec-matrix`) will later check — error paths, constraint boundaries, state
50
+ transitions, edge cases — while the behavior is fresh.
51
+ - **Negative cases.** State what must *not* happen, not just what should: rejects,
52
+ refuses, never persists, leaves state unchanged.
53
+ - **Concrete and measurable.** "Returns HTTP 422 within 200ms", not "handles errors
54
+ gracefully". Avoid subjective language (fast, robust, user-friendly) — if it can't
55
+ be measured, it can't be verified.
56
+ - **Behavior, not implementation.** Assert the observable outcome, not how the code
57
+ achieves it.
58
+
59
+ > **Bad:** "The system handles invalid input gracefully."
60
+ > **Good:** "Given a payload missing `email`, when POST /contacts is called, then the
61
+ > system returns HTTP 422 with error code `MISSING_FIELD` and persists no record."