@rqml/schema 0.1.1 → 0.1.3

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.
Files changed (4) hide show
  1. package/dist/index.js +1 -1
  2. package/dist/index.js.map +1 -1
  3. package/package.json +1 -1
  4. package/templates/AGENTS.md +35 -18
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rqml/schema",
3
- "version": "0.1.1",
3
+ "version": "0.1.3",
4
4
  "description": "Canonical RQML XSD schemas (the single source of truth), example documents, and the AGENTS.md template, with a typed version resolver. Schema text is inlined for offline, bundler-friendly consumption.",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",
package/templates/AGENTS.md CHANGED
@@ -11,7 +11,7 @@
11
11
 
12
12
  ---
13
13
 
14
- This project uses **RQML** as the single source of truth for system intent. Familiarize yourself with the documentation at https://rqml.org/docs/user-guide/
14
+ This project uses **RQML** as the single source of truth for system intent. Familiarize yourself with the documentation at https://rqml.org/docs/user-guide/ and the development process at https://rqml.org/docs/development-process/
15
15
 
16
16
  **Specification file:** Specification lives in a single .rqml file in the root of the project - convention is `requirements.rqml`. Multiple .rqml files may be employed in multirepo projects, in such cases a .rqml spec applies to everything that is higher in the project tree, unless overridden by another .rqml file.
17
17
 
@@ -29,7 +29,11 @@ rqml check # deterministic gate: validation + coverage + drift (
29
29
  rqml status # re-anchor: spec, coverage, and drift state
30
30
  rqml show <REQ-ID> # one requirement: statement, acceptance criteria, trace neighborhood
31
31
  rqml impact <ID> # what is affected, transitively, if this artifact changes
32
+ rqml overview # readable projection of the spec (--section/--id to scope)
33
+ rqml matrix # traceability matrix: status, goals, code, tests, coverage gaps
32
34
  rqml link <REQ-ID> <path> # record an implements edge + drift baseline (--type verifiedBy for tests)
35
+ rqml approve <REQ-ID> # transition a requirement's status (default approved)
36
+ rqml gate # block implementation of non-approved requirements
33
37
  rqml skeleton <kind> # schema-valid snippet: req | edge | testCase | stateMachine
34
38
  ```
35
39
 
@@ -39,35 +43,45 @@ Run `rqml status` when you start a session to re-anchor on the spec. Run `rqml c
39
43
 
40
44
  ## Core Principle: Spec-First Development
41
45
 
42
- ```
43
- [Elicit] → [Specify] → [Implement] → [Verify] → [Trace]
44
- ↑____________________←______________________|
45
- ```
46
-
47
46
  Code follows specification, not the reverse. If code and spec diverge, the spec is authoritative—update the code or negotiate a spec change with the developer.
48
47
 
48
+ RQML organizes work into a **five-stage process** (https://rqml.org/docs/development-process/). Each stage produces a durable artifact in version control; verification feeds back to the spec, so it is a loop:
49
+
50
+ | Stage | Task | Output |
51
+ |-------|------|--------|
52
+ | **Spec** | Capture intent as requirements | `requirements.rqml` |
53
+ | **Design** | Decide architecture, record decisions | ADRs in `.rqml/adr/` |
54
+ | **Plan** | Break work into agent-sized stages | `.rqml/plan.md` |
55
+ | **Code** | Implement specified behavior, keep traces current | code + tests |
56
+ | **Verify** | Prove coverage and catch drift | trace graph + `rqml check` |
57
+
58
+ Never skip ahead: do not implement behavior that is not specified, and do not make a significant architectural choice without recording it as an ADR.
59
+
49
60
  ---
50
61
 
51
62
  ## Workflow
52
63
 
53
- ### 1. Elicit
54
- Ask clarifying questions until you understand the goal, scope, acceptance criteria, and constraints. Don't assume—capture assumptions as `<notes>` or `<issue>` elements.
55
-
56
- ### 2. Specify
57
- **Never implement unspecified behavior.** Update the `.rqml` file before coding:
64
+ ### 1. Spec
65
+ Ask clarifying questions until you understand the goal, scope, acceptance criteria, and constraints. Don't assume—capture assumptions as `<notes>` or `<issue>` elements. **Never implement unspecified behavior.** Update the `.rqml` file before coding:
58
66
  - Add a `<req>` with statement and acceptance criteria
59
67
  - Set appropriate `type`, `priority`, and `status="draft"`
60
- - Get developer confirmation before proceeding
68
+ - Get developer confirmation; only `status="approved"` requirements drive implementation
69
+
70
+ ### 2. Design
71
+ Before building, decide *how*. Record each significant architectural decision as an **Architecture Decision Record (ADR)** in `.rqml/adr/`, following the canonical format (https://rqml.org/docs/development-process/design): `NNNN-kebab-case-slug.md`, with Status, Classification, Context, Options considered, Decision, and Consequences. A decision is ADR-worthy when there are real alternatives or the choice constrains future work; skip ADRs for low-level implementation details. ADRs are immutable once accepted—supersede, don't edit.
72
+
73
+ ### 3. Plan
74
+ Break approved requirements into a staged implementation plan at `.rqml/plan.md`, framed for coding agents: each stage names its goal, the requirement IDs it addresses, the files it touches, and how to verify it.
61
75
 
62
- ### 3. Implement
63
- Read the requirement first: `rqml show REQ-XXX`. Check blast radius before changing existing artifacts: `rqml impact REQ-XXX`. If you discover missing requirements, stop and add them to the spec first. After implementing, record the trace link:
76
+ ### 4. Code (Implement)
77
+ Read the requirement first: `rqml show REQ-XXX`. Check blast radius before changing existing artifacts: `rqml impact REQ-XXX`. Honor the ADRs. If you discover missing requirements, stop and add them to the spec first. After implementing, record the trace link:
64
78
 
65
79
  ```bash
66
80
  rqml link REQ-XXX src/path/to/implementation.ts
67
81
  ```
68
82
 
69
- ### 4. Verify
70
- Add tests that reference requirement IDs, then record verification:
83
+ ### 5. Verify
84
+ Add tests that reference requirement IDs, then record verification and run the gate:
71
85
 
72
86
  ```bash
73
87
  rqml link REQ-XXX test/path/to/test.ts --type verifiedBy
@@ -90,10 +104,12 @@ rqml check # must exit 0 before you are done
90
104
 
91
105
  | Aspect | relaxed | standard | strict | certified |
92
106
  |--------|---------|----------|--------|-----------|
93
- | Elicitation | Major features | Testable reqs | Edge cases | Formal |
107
+ | Spec (elicitation) | Major features | Testable reqs | Edge cases | Formal |
94
108
  | Spec-first | Recommended | Required | Required | Approved first |
109
+ | Design (ADRs) | Optional | Significant choices | All architectural choices | With approval |
110
+ | Plan | Optional | For multi-stage work | Required | Required |
95
111
  | Code traces | Optional | New features | All changes | With metadata |
96
- | Test traces | Optional | New reqs | All reqs | Full matrix |
112
+ | Verify (test traces) | Optional | New reqs | All reqs | Full matrix |
97
113
  | Ghost features | Allowed | Blocked | Blocked | Blocked |
98
114
 
99
115
  ---
@@ -106,6 +122,7 @@ For PRs and commits:
106
122
  ## RQML Trace Summary
107
123
 
108
124
  **Requirements:** REQ-xxx (added/modified/implemented)
125
+ **Design:** ADR-xxxx — decision recorded (if any)
109
126
  **Implementation:** `path/to/file` — what changed
110
127
  **Verification:** `path/to/test` — what it verifies
111
128
  **Open items:** gaps, assumptions, follow-ups