@agent-ix/quoin 0.3.7 → 0.4.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 +54 -3
- package/default-modules.yaml +2 -2
- package/dist/{cli-CNlT2O2s.js → cli-CQCkDA9J.js} +69 -59
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +1 -1
- package/dist/index.js +1 -1
- package/package.json +3 -3
- package/skills/gap-analysis/SKILL.md +97 -0
- package/skills/gap-analysis/references/step-1-target-selection.md +53 -0
- package/skills/gap-analysis/references/step-2-plan-completion.md +49 -0
- package/skills/gap-analysis/references/step-3-matrix-verification.md +54 -0
- package/skills/gap-analysis/references/step-4-underspecified-code.md +63 -0
- package/skills/gap-analysis/references/step-5-semantic-review.md +51 -0
- package/skills/gap-analysis/references/step-6-specreview-artifact.md +95 -0
- package/skills/spec-to-plan/SKILL.md +29 -8
- package/skills/spec-to-plan/references/step-0-plan-selection.md +121 -0
- package/skills/spec-to-plan/references/step-1-analysis.md +23 -3
- package/skills/spec-to-plan/references/step-2-test-plan.md +4 -2
- package/skills/spec-to-plan/references/step-3-execution-plan.md +52 -25
- package/skills/spec-to-plan/workflow-assets/skills/to-plan/templates/implementation-plan/default.md +2 -1
- package/skills/spec-to-plan/workflow-assets/skills/to-plan/workflows/to-plan/def.yaml +4 -1
package/README.md
CHANGED
|
@@ -15,6 +15,57 @@ workflows agents need to write and validate specs directly as Markdown.
|
|
|
15
15
|
|
|
16
16
|
`quoin` is built on the [Quire](https://github.com/agent-ix/quire-rs) document standard and validation engine by Agent-IX.
|
|
17
17
|
|
|
18
|
+
> **Why:** AI agents write code fast but drift from vague intent. Quoin makes the spec the source of truth — your agent authors a validated, traceable spec first, then plans and builds against it.
|
|
19
|
+
|
|
20
|
+
## How
|
|
21
|
+
|
|
22
|
+
In Claude Code, Codex, or the coding agent of your choice:
|
|
23
|
+
|
|
24
|
+
#### 1. Ideate & Specify
|
|
25
|
+
|
|
26
|
+
Ideate, then pass your idea to `/specify`. A `specification` containing `user stories`, `functional requirements`,
|
|
27
|
+
`stakeholder requirements`, `non-functional requirements`, and other artifacts will be created.
|
|
28
|
+
|
|
29
|
+
```
|
|
30
|
+
> /specify an electron app for tracking spice production
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
#### 2. Spec Review
|
|
34
|
+
|
|
35
|
+
Use `/spec-review` for agent-assisted review. Multiple analysis tasks will run in parallel and output `Reviews`
|
|
36
|
+
with `Findings` and suggested fixes.
|
|
37
|
+
|
|
38
|
+
```
|
|
39
|
+
> /spec-review review the specs for the spice production tracker.
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
#### 3. Convert to plans
|
|
43
|
+
|
|
44
|
+
Build the test `traceability matrix` and `plan`. These skills will break the work down into a `plan`
|
|
45
|
+
with multiple `tasks`.
|
|
46
|
+
|
|
47
|
+
```
|
|
48
|
+
> /spec-matrix /spec-to-plan prep the spice tracking app for coding
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
#### 4. Implement!
|
|
52
|
+
|
|
53
|
+
Call `/implement-plan` to trigger your coding agent to begin work on the plan.
|
|
54
|
+
|
|
55
|
+
```
|
|
56
|
+
> /implement-plan build the spice tracking app
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
#### 5. Gap review
|
|
60
|
+
|
|
61
|
+
`/gap-analysis` validates that the `UserStory` and `Functional Requirements` are implemented and tested using the `traceability matrix`
|
|
62
|
+
as the guide. `/gap-analysis` will optionally perform a _semantic_ comparison of `spec`, `code`, and `tests` to ensure the
|
|
63
|
+
`plan` is faithfully implemented.
|
|
64
|
+
|
|
65
|
+
```
|
|
66
|
+
> /gap-analysis
|
|
67
|
+
```
|
|
68
|
+
|
|
18
69
|
## What's included
|
|
19
70
|
|
|
20
71
|
The default module set defines the spec archetypes and domain-object vocabulary.
|
|
@@ -65,7 +116,7 @@ Multi-agent workflows that fan out, run lenses in parallel, and synthesize resul
|
|
|
65
116
|
## Install
|
|
66
117
|
|
|
67
118
|
Installing quoin into Claude is **two steps**: the CLI (from public npm) and the plugin
|
|
68
|
-
that adds the [skills](#skills) and [workflows](#workflows) to Claude Code. No Anthropic API
|
|
119
|
+
that adds the [skills](#agent-skills) and [workflows](#agent-workflows) to Claude Code. No Anthropic API
|
|
69
120
|
key is required — your Claude subscription is used.
|
|
70
121
|
|
|
71
122
|
**1. Install the CLIs** (`quoin` plus `ix-flow`, which runs the workflow lifecycle commands):
|
|
@@ -89,9 +140,9 @@ the agent.
|
|
|
89
140
|
### skills & workflows
|
|
90
141
|
|
|
91
142
|
The primary way users author specs is by asking an agent, which invokes the bundled
|
|
92
|
-
[skills](#skills) and [workflows](#workflows).
|
|
143
|
+
[skills](#agent-skills) and [workflows](#agent-workflows).
|
|
93
144
|
|
|
94
|
-
###
|
|
145
|
+
### CLI commands
|
|
95
146
|
|
|
96
147
|
Inspect the spec vocabulary and manage installed modules:
|
|
97
148
|
|
package/default-modules.yaml
CHANGED
|
@@ -28,13 +28,13 @@ entries:
|
|
|
28
28
|
ref: v0.2.0
|
|
29
29
|
|
|
30
30
|
- name: spec-artifacts-process
|
|
31
|
-
version: "0.
|
|
31
|
+
version: "0.4.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.4.0
|
|
38
38
|
|
|
39
39
|
- name: spec-objects-business
|
|
40
40
|
version: "0.3.0"
|
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
import { existsSync as e, readFileSync as t, readdirSync as n, rmSync as r, statSync as i } from "node:fs";
|
|
2
2
|
import { basename as a, dirname as o, join as s, resolve as c } from "node:path";
|
|
3
3
|
import { fileURLToPath as l } from "node:url";
|
|
4
|
-
import { configureRuntimeContext as u } from "@agent-ix/ix-cli-core";
|
|
5
|
-
import { homedir as
|
|
6
|
-
import { parse as
|
|
7
|
-
import { installEntry as
|
|
4
|
+
import { configureRuntimeContext as u, runSelfUpdate as d } from "@agent-ix/ix-cli-core";
|
|
5
|
+
import { homedir as f } from "node:os";
|
|
6
|
+
import { parse as p } from "yaml";
|
|
7
|
+
import { installEntry as ee, readRegistry as m, reconcile as h, validateMarketplaceManifest as te, writeRegistry as g } from "@agent-ix/ts-plugin-kit";
|
|
8
8
|
import { spawn as _ } from "node:child_process";
|
|
9
9
|
//#region src/catalog.ts
|
|
10
10
|
function v() {
|
|
11
|
-
return process.env.IX_HOME && process.env.IX_HOME.length > 0 ? process.env.IX_HOME : s(
|
|
11
|
+
return process.env.IX_HOME && process.env.IX_HOME.length > 0 ? process.env.IX_HOME : s(f(), ".ix");
|
|
12
12
|
}
|
|
13
13
|
function y(e = v()) {
|
|
14
14
|
return s(e, "filament", "modules");
|
|
@@ -23,22 +23,22 @@ function b(t = v()) {
|
|
|
23
23
|
function x(e = b()) {
|
|
24
24
|
let n = [], r = [], i = /* @__PURE__ */ new Set(), o = /* @__PURE__ */ new Set();
|
|
25
25
|
for (let c of e) {
|
|
26
|
-
let e =
|
|
26
|
+
let e = ne(c);
|
|
27
27
|
if (!e || i.has(e)) continue;
|
|
28
28
|
i.add(e);
|
|
29
|
-
let l =
|
|
29
|
+
let l = p(t(s(e, "manifest.yaml"), "utf8")), u = E(l.name) ?? a(e);
|
|
30
30
|
if (o.has(u)) continue;
|
|
31
31
|
o.add(u);
|
|
32
|
-
let d =
|
|
32
|
+
let d = T(l.artifact_types), f = T(l.object_types);
|
|
33
33
|
n.push({
|
|
34
34
|
name: u,
|
|
35
|
-
version:
|
|
35
|
+
version: E(l.version),
|
|
36
36
|
root: e,
|
|
37
37
|
artifactTypes: d.map((e) => String(e.name)),
|
|
38
|
-
objectTypes:
|
|
38
|
+
objectTypes: f.map((e) => String(e.name))
|
|
39
39
|
});
|
|
40
40
|
for (let t of d) {
|
|
41
|
-
let n = String(t.name), i =
|
|
41
|
+
let n = String(t.name), i = E(t.frontmatter_schema_ref);
|
|
42
42
|
r.push({
|
|
43
43
|
name: n,
|
|
44
44
|
kind: "artifact",
|
|
@@ -46,24 +46,24 @@ function x(e = b()) {
|
|
|
46
46
|
moduleRoot: e,
|
|
47
47
|
schemaRef: i,
|
|
48
48
|
schemaPath: i ? s(e, i) : void 0,
|
|
49
|
-
skeletonPath:
|
|
49
|
+
skeletonPath: w(e, n)
|
|
50
50
|
});
|
|
51
51
|
}
|
|
52
|
-
for (let t of
|
|
52
|
+
for (let t of f) {
|
|
53
53
|
let n = String(t.name);
|
|
54
54
|
r.push({
|
|
55
55
|
name: n,
|
|
56
56
|
kind: "object",
|
|
57
57
|
moduleName: u,
|
|
58
58
|
moduleRoot: e,
|
|
59
|
-
skeletonPath:
|
|
59
|
+
skeletonPath: w(e, n)
|
|
60
60
|
});
|
|
61
61
|
}
|
|
62
62
|
}
|
|
63
63
|
return {
|
|
64
64
|
modules: n,
|
|
65
65
|
entries: r,
|
|
66
|
-
duplicates:
|
|
66
|
+
duplicates: D(r)
|
|
67
67
|
};
|
|
68
68
|
}
|
|
69
69
|
function S(e, t) {
|
|
@@ -73,7 +73,7 @@ function S(e, t) {
|
|
|
73
73
|
function C(e) {
|
|
74
74
|
return e.toLowerCase();
|
|
75
75
|
}
|
|
76
|
-
function
|
|
76
|
+
function ne(t) {
|
|
77
77
|
let r = c(t);
|
|
78
78
|
if (e(r)) {
|
|
79
79
|
if (e(s(r, "manifest.yaml"))) return r;
|
|
@@ -83,16 +83,16 @@ function w(t) {
|
|
|
83
83
|
}
|
|
84
84
|
}
|
|
85
85
|
}
|
|
86
|
-
function
|
|
86
|
+
function w(t, n) {
|
|
87
87
|
return [s(t, "skeletons", `${n}.md`), s(t, "skeletons", `${n.toLowerCase()}.md`)].find((t) => e(t));
|
|
88
88
|
}
|
|
89
|
-
function
|
|
89
|
+
function T(e) {
|
|
90
90
|
return Array.isArray(e) ? e.filter((e) => !!e && typeof e == "object" && "name" in e) : [];
|
|
91
91
|
}
|
|
92
|
-
function
|
|
92
|
+
function E(e) {
|
|
93
93
|
return typeof e == "string" ? e : void 0;
|
|
94
94
|
}
|
|
95
|
-
function
|
|
95
|
+
function D(e) {
|
|
96
96
|
let t = /* @__PURE__ */ new Map();
|
|
97
97
|
for (let n of e) {
|
|
98
98
|
let e = `${n.kind}:${n.name}`, r = t.get(e) ?? /* @__PURE__ */ new Set();
|
|
@@ -156,7 +156,7 @@ function A(e) {
|
|
|
156
156
|
};
|
|
157
157
|
}
|
|
158
158
|
function j(e, t = v()) {
|
|
159
|
-
return
|
|
159
|
+
return ee({ source: A(e) }, k(t));
|
|
160
160
|
}
|
|
161
161
|
function M(e = v()) {
|
|
162
162
|
return m(O(e)).plugins;
|
|
@@ -174,7 +174,7 @@ function N(e, t = v()) {
|
|
|
174
174
|
function P(n) {
|
|
175
175
|
let r = e(s(n, "manifest.yaml")) ? s(n, "manifest.yaml") : s(n, a(n), "manifest.yaml");
|
|
176
176
|
if (!e(r)) throw Error(`no manifest.yaml found under ${n}`);
|
|
177
|
-
let i =
|
|
177
|
+
let i = p(t(r, "utf8"));
|
|
178
178
|
if (typeof i.name != "string" || i.name.length === 0) throw Error(`manifest ${r} has no name`);
|
|
179
179
|
return i.name;
|
|
180
180
|
}
|
|
@@ -184,10 +184,10 @@ function F() {
|
|
|
184
184
|
return o(o(l(import.meta.url)));
|
|
185
185
|
}
|
|
186
186
|
function I() {
|
|
187
|
-
return
|
|
187
|
+
return te(p(t(s(F(), "default-modules.yaml"), "utf8")));
|
|
188
188
|
}
|
|
189
189
|
function L(e = v(), t = I()) {
|
|
190
|
-
|
|
190
|
+
h(t, {
|
|
191
191
|
...k(e),
|
|
192
192
|
mode: "lazy"
|
|
193
193
|
});
|
|
@@ -211,8 +211,8 @@ var R = {
|
|
|
211
211
|
function z() {
|
|
212
212
|
return Object.keys(R);
|
|
213
213
|
}
|
|
214
|
-
async function
|
|
215
|
-
let n =
|
|
214
|
+
async function B(e, t = {}) {
|
|
215
|
+
let n = V(e), r = v(), i = [
|
|
216
216
|
"run",
|
|
217
217
|
e,
|
|
218
218
|
"--path",
|
|
@@ -224,16 +224,16 @@ async function ne(e, t = {}) {
|
|
|
224
224
|
];
|
|
225
225
|
t.id && i.push("--id", t.id), t.json && i.push("--json");
|
|
226
226
|
for (let e of t.target ?? []) i.push("--target", e);
|
|
227
|
-
await
|
|
227
|
+
await U(i);
|
|
228
228
|
}
|
|
229
|
-
function
|
|
229
|
+
function V(t) {
|
|
230
230
|
let n = R[t];
|
|
231
231
|
if (!n) throw Error(`unknown spec flow ${t}`);
|
|
232
232
|
let r = [
|
|
233
233
|
process.env.IX_SPEC_WORKFLOWS_ROOT,
|
|
234
|
-
|
|
234
|
+
H(),
|
|
235
235
|
s(o(c(process.cwd())), "ix-spec-workflows"),
|
|
236
|
-
s(
|
|
236
|
+
s(f(), ".ix", "plugins", "ix-spec-workflows")
|
|
237
237
|
].filter((e) => !!e);
|
|
238
238
|
for (let t of r) {
|
|
239
239
|
let r = s(t, n.packageSkill, "workflow-assets", "skills", n.runtimeSkill);
|
|
@@ -241,10 +241,10 @@ function B(t) {
|
|
|
241
241
|
}
|
|
242
242
|
throw Error(`could not find ix-spec workflow skill ${n.runtimeSkill}; set IX_SPEC_WORKFLOWS_ROOT`);
|
|
243
243
|
}
|
|
244
|
-
function
|
|
244
|
+
function H() {
|
|
245
245
|
return s(o(o(l(import.meta.url))), "skills");
|
|
246
246
|
}
|
|
247
|
-
async function
|
|
247
|
+
async function U(e) {
|
|
248
248
|
await new Promise((t, n) => {
|
|
249
249
|
let r = _("ix-flow", e, { stdio: "inherit" });
|
|
250
250
|
r.on("error", n), r.on("close", (e) => {
|
|
@@ -258,10 +258,10 @@ async function H(e) {
|
|
|
258
258
|
}
|
|
259
259
|
//#endregion
|
|
260
260
|
//#region src/write.ts
|
|
261
|
-
function
|
|
261
|
+
function W(e) {
|
|
262
262
|
return (Array.isArray(e) ? e : e ? [e] : []).flatMap((e) => e.split(",")).map((e) => e.trim()).filter(Boolean);
|
|
263
263
|
}
|
|
264
|
-
function
|
|
264
|
+
function G(t, n, r) {
|
|
265
265
|
if (r.length === 0) throw Error("write requires --types <type[,type...]>");
|
|
266
266
|
let a = c(n);
|
|
267
267
|
if (!e(a) || !i(a).isDirectory()) throw Error(`write repo_dir is not a directory: ${n}`);
|
|
@@ -270,16 +270,16 @@ function W(t, n, r) {
|
|
|
270
270
|
types: r.map((e) => {
|
|
271
271
|
let n = S(t, e);
|
|
272
272
|
if (!n) throw Error(`catalog type not found: ${e}\nAvailable types: ${t.entries.map((e) => e.name).sort((e, t) => e.localeCompare(t)).join(", ")}`);
|
|
273
|
-
return
|
|
273
|
+
return q(n);
|
|
274
274
|
}),
|
|
275
275
|
validation: {
|
|
276
|
-
command: `quire validate --scope ${
|
|
276
|
+
command: `quire validate --scope ${J(a)} "spec/**/*.md"`,
|
|
277
277
|
scope: a,
|
|
278
278
|
globs: ["spec/**/*.md"]
|
|
279
279
|
}
|
|
280
280
|
};
|
|
281
281
|
}
|
|
282
|
-
function
|
|
282
|
+
function K(e) {
|
|
283
283
|
let t = [
|
|
284
284
|
"quoin write",
|
|
285
285
|
"",
|
|
@@ -290,7 +290,7 @@ function G(e) {
|
|
|
290
290
|
for (let n of e.types) t.push(`- ${n.name} (${n.kind})`), t.push(` module: ${n.moduleName}`), t.push(` module_root: ${n.moduleRoot}`), n.skeletonPath && t.push(` skeleton: ${n.skeletonPath}`), n.schemaPath && t.push(` schema: ${n.schemaPath}`), !n.skeletonPath && !n.schemaPath && t.push(" contract: manifest only");
|
|
291
291
|
return t.push(""), t.push("Author files directly in the repo, then validate changed spec files."), t.push(`Validate scope: ${e.validation.scope}`), t.push(`Validate command: ${e.validation.command}`), t.join("\n");
|
|
292
292
|
}
|
|
293
|
-
function
|
|
293
|
+
function q(e) {
|
|
294
294
|
return {
|
|
295
295
|
name: e.name,
|
|
296
296
|
kind: e.kind,
|
|
@@ -300,24 +300,24 @@ function K(e) {
|
|
|
300
300
|
...e.skeletonPath ? { skeletonPath: e.skeletonPath } : {}
|
|
301
301
|
};
|
|
302
302
|
}
|
|
303
|
-
function
|
|
303
|
+
function J(e) {
|
|
304
304
|
return /^[A-Za-z0-9_./:-]+$/.test(e) ? e : `'${e.replaceAll("'", "'\\''")}'`;
|
|
305
305
|
}
|
|
306
306
|
//#endregion
|
|
307
307
|
//#region src/cli.ts
|
|
308
|
-
var
|
|
309
|
-
async function
|
|
310
|
-
let t =
|
|
308
|
+
var Y = "quoin\n\nSpec workflow and catalog CLI for Agent IX.\n\nquoin starts spec-domain work. ix-flow resumes, advances, acknowledges gates,\nand inspects workflow runs created by quoin.\n\nDefault modules (installed on first use into ~/.ix/filament/modules):\n Artifact modules: spec-artifacts-iso, spec-artifacts-app, spec-artifacts-process\n Object modules: spec-objects-business, spec-objects-architecture,\n spec-objects-enterprise, spec-objects-operational,\n spec-objects-security\n Workflows: review, matrix, to-plan\n\nUsage:\n quoin write <repo_dir> --types <type[,type...]>\n quoin catalog list|validate\n quoin catalog show <type>\n quoin plugin install <path:...|github:...>\n quoin plugin list\n quoin plugin remove <name>\n quoin review|matrix|to-plan [--target <ref>...]\n quoin update [--check] [--registry <url>]\n\nGlobal flags:\n --json\n --config-root <dir> Defaults to ~/.ix\n\nExamples:\n quoin catalog list\n quoin catalog show FR\n quoin plugin install github:agent-ix/spec-objects-custom\n quoin write . --types FR,domain\n ix-flow status <run-id>\n", X = "quoin write\n\nBuild an authoring pack for spec files an agent is about to create or edit.\n\nPass the target repository and the artifact/object types involved in the work.\nquoin resolves those types from the active catalog and returns the local\nskeletons, schemas, module roots, and Quire validation command for the repo.\n\nUsage:\n quoin write <repo_dir> --types <type[,type...]>\n\nExamples:\n quoin write . --types FR\n quoin write . --types FR,domain,entity\n quoin write ../my-service --types fr,DOMAIN --json\n\nNotes:\n - Type lookup is case-insensitive; FR and fr are the same type.\n - Types can be artifacts or objects from the default module set or plugins.\n - Use the returned skeletons and schemas as the authoring contract.\n - Run the returned Quire command after editing spec files.\n", re = "quoin catalog\n\nInspect the active artifact/object catalog.\n\nThe catalog is assembled from, in order:\n 1. QUOIN_MODULE_PATHS\n 2. modules installed under ~/.ix/filament/modules\n\nThe default module set is installed there automatically on first catalog access,\nand updated by \"quoin plugin install\". The same directory is read by quire-rs.\n\nDefault artifact modules:\n spec-artifacts-iso FR, NFR, StR, US, IT, TC, AC, CON, Spec\n spec-artifacts-app app-level artifacts\n spec-artifacts-process plans, reviews, matrices, ADRs, tasks, findings\n\nDefault object modules:\n spec-objects-business\n spec-objects-architecture\n spec-objects-enterprise\n spec-objects-operational\n spec-objects-security\n\nUsage:\n quoin catalog list\n quoin catalog show <type>\n quoin catalog validate\n\nExamples:\n quoin catalog show FR\n quoin catalog show entity\n quoin catalog validate --json\n", ie = "quoin plugin\n\nInstall and manage user/community spec modules.\n\nPlugins add or override artifact/object modules under ~/.ix/filament/modules.\nUse \"catalog list\" to see the full active catalog, including default modules and\nplugins.\n\nSupported install sources:\n path:<dir> Use a local directory containing manifest.yaml\n github:<owner>/<repo> Clone a GitHub repository (manifest at root)\n github:<owner>/<repo>@<ref> Pin to a tag, branch, or sha\n github:<owner>/<repo>//<subdir> Manifest in a monorepo subdirectory (@<ref> ok)\n\nUsage:\n quoin plugin install <path:...|github:...>\n quoin plugin list\n quoin plugin remove <name>\n quoin plugin ensure-defaults\n\nExamples:\n quoin plugin install path:../spec-objects-custom\n quoin plugin install github:agent-ix/spec-objects-custom\n quoin plugin install github:agent-ix/spec-objects-security//spec_objects_security@v0.1.1\n quoin plugin list\n quoin plugin ensure-defaults\n", ae = "quoin update\n\nCheck for and install the latest published quoin.\n\nquoin is distributed on the public npm registry as @agent-ix/quoin. This command\nqueries the registry for the latest version, compares it to the running version,\nand (unless --check) runs npm install -g to upgrade in place.\n\nUsage:\n quoin update [--check] [--registry <url>]\n\nFlags:\n --check Report whether an update is available; do not install.\n --registry <url> Force an npm registry to query/install from. Defaults\n to your npm config (the registry @agent-ix resolves to,\n i.e. however quoin was installed). Pass\n https://registry.npmjs.org/ for public npm, or\n http://npm.ix/ for local dev snapshots.\n\nExamples:\n quoin update\n quoin update --check\n quoin update --registry http://npm.ix/\n", oe = "quoin workflows\n\nStart bundled spec review/planning workflows. quoin creates the workflow run in ~/.ix/flows.\nUse ix-flow to inspect, resume, advance phases, and acknowledge human gates.\n\nAvailable workflow launchers:\n review Run a composite spec review\n matrix Build or update a requirements test matrix\n to-plan Convert accepted requirements into an implementation plan\n\nUsage:\n quoin review|matrix|to-plan [--target <ref>...]\n\nExamples:\n quoin review --target spec/\n quoin matrix --target spec/\n ix-flow status <run-id>\n ix-flow resume <run-id>\n";
|
|
309
|
+
async function se(e) {
|
|
310
|
+
let t = pe(e);
|
|
311
311
|
if (t.flags.version || t.flags.v || t.command === "version") {
|
|
312
312
|
console.log(Z());
|
|
313
313
|
return;
|
|
314
314
|
}
|
|
315
315
|
if (!t.command) {
|
|
316
|
-
console.log(
|
|
316
|
+
console.log(Y);
|
|
317
317
|
return;
|
|
318
318
|
}
|
|
319
319
|
if (t.flags.help || t.flags.h) {
|
|
320
|
-
console.log(
|
|
320
|
+
console.log(ce(t));
|
|
321
321
|
return;
|
|
322
322
|
}
|
|
323
323
|
let n = Q(t, "config-root") ?? v();
|
|
@@ -326,32 +326,42 @@ async function ae(e) {
|
|
|
326
326
|
configNamespace: "ix",
|
|
327
327
|
projectConfigRoot: `${process.cwd()}/.ix`,
|
|
328
328
|
projectConfigEnabled: t.flags["no-project-config"] !== !0
|
|
329
|
-
}), t.command === "
|
|
330
|
-
if (t.command === "
|
|
331
|
-
if (t.command === "
|
|
332
|
-
if (
|
|
329
|
+
}), t.command === "update") return ue(t);
|
|
330
|
+
if (t.command === "catalog") return de(t);
|
|
331
|
+
if (t.command === "plugin") return fe(t);
|
|
332
|
+
if (t.command === "write") return le(t);
|
|
333
|
+
if (z().includes(t.command)) return B(t.command, {
|
|
333
334
|
json: t.flags.json === !0,
|
|
334
335
|
id: Q(t, "id"),
|
|
335
336
|
target: $(t, "target")
|
|
336
337
|
});
|
|
337
|
-
throw Error(`unknown command ${t.command}\n\n${
|
|
338
|
+
throw Error(`unknown command ${t.command}\n\n${Y}`);
|
|
338
339
|
}
|
|
339
340
|
function Z() {
|
|
340
341
|
let e = o(o(l(import.meta.url))), n = JSON.parse(t(s(e, "package.json"), "utf8"));
|
|
341
342
|
if (typeof n.version != "string") throw Error("package.json version is missing");
|
|
342
343
|
return n.version;
|
|
343
344
|
}
|
|
344
|
-
function
|
|
345
|
-
return e.command === "write" ?
|
|
345
|
+
function ce(e) {
|
|
346
|
+
return e.command === "update" ? ae : e.command === "write" ? X : e.command === "catalog" ? re : e.command === "plugin" ? ie : z().includes(e.command) ? oe : Y;
|
|
346
347
|
}
|
|
347
|
-
function
|
|
348
|
+
function le(e) {
|
|
348
349
|
let [t] = e.positionals;
|
|
349
|
-
if (!t) throw Error(`write requires <repo_dir>\n\n${
|
|
350
|
+
if (!t) throw Error(`write requires <repo_dir>\n\n${X}`);
|
|
350
351
|
L();
|
|
351
|
-
let n =
|
|
352
|
-
console.log(e.flags.json ? JSON.stringify(n, null, 2) :
|
|
352
|
+
let n = G(x(), t, W($(e, "types")));
|
|
353
|
+
console.log(e.flags.json ? JSON.stringify(n, null, 2) : K(n));
|
|
354
|
+
}
|
|
355
|
+
async function ue(e) {
|
|
356
|
+
await d({
|
|
357
|
+
packageName: "@agent-ix/quoin",
|
|
358
|
+
currentVersion: Z(),
|
|
359
|
+
header: "quoin update",
|
|
360
|
+
registry: Q(e, "registry"),
|
|
361
|
+
check: e.flags.check === !0
|
|
362
|
+
});
|
|
353
363
|
}
|
|
354
|
-
function
|
|
364
|
+
function de(e) {
|
|
355
365
|
L();
|
|
356
366
|
let t = x();
|
|
357
367
|
switch (e.subcommand) {
|
|
@@ -387,7 +397,7 @@ function ce(e) {
|
|
|
387
397
|
default: throw Error(`unknown catalog command ${e.subcommand}`);
|
|
388
398
|
}
|
|
389
399
|
}
|
|
390
|
-
function
|
|
400
|
+
function fe(e) {
|
|
391
401
|
switch (e.subcommand) {
|
|
392
402
|
case "list":
|
|
393
403
|
case void 0:
|
|
@@ -414,7 +424,7 @@ function le(e) {
|
|
|
414
424
|
default: throw Error(`unknown plugin command ${e.subcommand}`);
|
|
415
425
|
}
|
|
416
426
|
}
|
|
417
|
-
function
|
|
427
|
+
function pe(e) {
|
|
418
428
|
let t = {}, n = [], r, i;
|
|
419
429
|
for (let a = 0; a < e.length; a++) {
|
|
420
430
|
let o = e[a];
|
|
@@ -439,4 +449,4 @@ function $(e, t) {
|
|
|
439
449
|
return Array.isArray(n) ? n : [];
|
|
440
450
|
}
|
|
441
451
|
//#endregion
|
|
442
|
-
export {
|
|
452
|
+
export { W as a, j as c, N as d, b as f, x as h, K as i, M as l, S as m, Z as n, I as o, y as p, G as r, L as s, se as t, A as u };
|
package/dist/cli.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AA6LA,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAoCxD;AAED,wBAAgB,cAAc,IAAI,MAAM,CASvC"}
|
package/dist/cli.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
import { n as e, t } from "./cli-
|
|
1
|
+
import { n as e, t } from "./cli-CQCkDA9J.js";
|
|
2
2
|
export { t as main, e as packageVersion };
|
package/dist/index.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
import { a as e, c as t, d as n, f as r, h as i, i as a, l as o, m as s, o as c, p as l, r as u, s as d, t as f, u as p } from "./cli-
|
|
1
|
+
import { a as e, c as t, d as n, f as r, h as i, i as a, l as o, m as s, o as c, p as l, r as u, s as d, t as f, u as p } from "./cli-CQCkDA9J.js";
|
|
2
2
|
export { u as createAuthoringPack, r as defaultModuleRoots, c as defaultModulesManifest, d as ensureDefaultModules, l as filamentModulesDir, s as findCatalogEntry, a as formatAuthoringPack, t as installPlugin, o as listPlugins, i as loadCatalog, f as main, p as parseSourceArg, e as parseTypeList, n as removePlugin };
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@agent-ix/quoin",
|
|
3
|
-
"description": "Spec
|
|
4
|
-
"version": "0.
|
|
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.0",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"files": [
|
|
@@ -54,7 +54,7 @@
|
|
|
54
54
|
"test-results:warnings": "./node_modules/.bin/jest-results warnings"
|
|
55
55
|
},
|
|
56
56
|
"dependencies": {
|
|
57
|
-
"@agent-ix/ix-cli-core": ">=0.10.
|
|
57
|
+
"@agent-ix/ix-cli-core": ">=0.10.5",
|
|
58
58
|
"@agent-ix/ts-plugin-kit": ">=0.1.3",
|
|
59
59
|
"yaml": "^2.9.0"
|
|
60
60
|
},
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: gap-analysis
|
|
3
|
+
description: Verify a targeted plan is complete and validated — every task done, the Test
|
|
4
|
+
Matrix backed by real tracking tags in tests, and code fully traced to spec (flagging
|
|
5
|
+
underspecified code with no owning requirement). Optional semantic review checks that
|
|
6
|
+
intent↔test↔code actually agree. Emits a quire-validated SpecReview artifact to
|
|
7
|
+
reviews/YY-MM-DD-<slug>.md.
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Gap Analysis
|
|
11
|
+
|
|
12
|
+
Use this skill as a **post-implementation verification gate** for one targeted plan.
|
|
13
|
+
It answers three questions and, on request, a fourth:
|
|
14
|
+
|
|
15
|
+
1. **Is the plan done?** Every `Task` in the targeted plan bundle is `status: done`.
|
|
16
|
+
2. **Is the Test Matrix real?** Every Test Case in the matrix is backed by an actual test
|
|
17
|
+
carrying a matching **tracking tag** (`TC-xxx`, `FR-xxx-AC-x`) in the test code.
|
|
18
|
+
3. **Is anything unspecified?** Code/behavior exists with **no owning** StR/US/FR/NFR
|
|
19
|
+
(the reverse, code→spec gap).
|
|
20
|
+
4. **(optional) Does intent match reality?** For each requirement↔test↔code triple — does
|
|
21
|
+
the test validate the requirement's *intent*, does the test actually exercise the code,
|
|
22
|
+
and does the code match the requirement's intent.
|
|
23
|
+
|
|
24
|
+
The result is a single **quire-validated `SpecReview`** document (`analysis: gap-analysis`)
|
|
25
|
+
written to `reviews/YY-MM-DD-<slug>.md`, with a **Verdict** (PASS / CONDITIONAL / FAIL)
|
|
26
|
+
and a validated **Findings** table.
|
|
27
|
+
|
|
28
|
+
## When to use
|
|
29
|
+
|
|
30
|
+
- After `implement-plan` (or any implementation effort) to confirm a plan is genuinely
|
|
31
|
+
complete and verified before closing it.
|
|
32
|
+
- To audit drift between spec, tests, and code for an existing component.
|
|
33
|
+
- As a release/merge gate that produces a durable, traceable review artifact.
|
|
34
|
+
|
|
35
|
+
This skill is **read-only over the codebase** — it inspects and reports; it does not fix
|
|
36
|
+
code, edit the plan, or change the matrix. Its only write is the SpecReview artifact.
|
|
37
|
+
|
|
38
|
+
## Inputs
|
|
39
|
+
|
|
40
|
+
- A target **plan bundle** `plan/<Plan-id>-<slug>/` (the user may name it; otherwise pick).
|
|
41
|
+
- The component **spec** (`spec/spec.md` for `org`/`name`) and **Test Matrix**
|
|
42
|
+
(`spec/matrix.md` or `spec/tests.md`).
|
|
43
|
+
- The **source** and **test** trees of the component.
|
|
44
|
+
|
|
45
|
+
## Steps
|
|
46
|
+
|
|
47
|
+
0. **[Target selection](references/step-1-target-selection.md)**: Resolve the plan bundle,
|
|
48
|
+
spec root, Test Matrix, and `org`/`component` for `ix://` URIs.
|
|
49
|
+
1. **[Plan completion](references/step-2-plan-completion.md)**: Assert every `Task` is
|
|
50
|
+
`done`; report incomplete/blocked tasks and stale `plan.md` checkboxes.
|
|
51
|
+
2. **[Matrix verification](references/step-3-matrix-verification.md)**: For every matrix
|
|
52
|
+
Test Case, confirm a backing test with a matching tracking tag exists; flag unbacked
|
|
53
|
+
rows, untracked tests, and inconsistent status markers.
|
|
54
|
+
3. **[Underspecified code](references/step-4-underspecified-code.md)**: Find code/behavior
|
|
55
|
+
with no owning requirement (reverse gap), plus stubs masquerading as complete.
|
|
56
|
+
4. **[Semantic review](references/step-5-semantic-review.md)** *(OPTIONAL — ask first)*:
|
|
57
|
+
Judge intent↔test↔code agreement per requirement. Skip unless the user opts in.
|
|
58
|
+
5. **[SpecReview artifact](references/step-6-specreview-artifact.md)**: Write and validate
|
|
59
|
+
the `SpecReview` to `reviews/YY-MM-DD-<slug>.md`.
|
|
60
|
+
|
|
61
|
+
All steps required except Step 4, which is gated on user choice.
|
|
62
|
+
|
|
63
|
+
## The optional semantic review
|
|
64
|
+
|
|
65
|
+
Steps 1–3 are mechanical and cheap. Step 4 is an expensive, judgment-heavy LLM pass.
|
|
66
|
+
**Before running it**, ask the user explicitly (e.g. with a yes/no choice):
|
|
67
|
+
|
|
68
|
+
> Run the optional semantic review (intent↔test↔code)? It's slower but verifies that tests
|
|
69
|
+
> actually validate requirement intent and exercise real code.
|
|
70
|
+
|
|
71
|
+
If yes, fan the work out (one subagent per FR or per area) for thoroughness. If no, note in
|
|
72
|
+
the SpecReview's Coverage section that semantic review was skipped.
|
|
73
|
+
|
|
74
|
+
## Output
|
|
75
|
+
|
|
76
|
+
A `SpecReview` (`spec-artifacts-process` archetype) at `<project_root>/reviews/YY-MM-DD-<slug>.md`:
|
|
77
|
+
|
|
78
|
+
- Frontmatter `type: SpecReview`, `analysis: gap-analysis`, `id: SR-NNN`, `scope`,
|
|
79
|
+
`review_set: subset`, and `relationships:` (`reviews` → the plan, `references` → the matrix).
|
|
80
|
+
- Body: `## Summary`, `## Verdict` (PASS/CONDITIONAL/FAIL), `## Findings`
|
|
81
|
+
(validated table `ID | Severity | Summary | Refs`), `## Coverage` (rollup).
|
|
82
|
+
|
|
83
|
+
> **Note:** `reviews/` is at the **repo root** by deliberate choice for this skill, not
|
|
84
|
+
> `spec/reviews/`. quire validation is path-agnostic, so this is fine.
|
|
85
|
+
|
|
86
|
+
Validate before finishing:
|
|
87
|
+
|
|
88
|
+
```
|
|
89
|
+
quire validate --scope <project_root> "reviews/**/*.md"
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## Verdict rule
|
|
93
|
+
|
|
94
|
+
- **FAIL** — any incomplete/blocked task, any matrix Test Case with no backing tagged test,
|
|
95
|
+
or any `high`-severity finding.
|
|
96
|
+
- **CONDITIONAL** — only `medium`/`low` findings (e.g. untracked tests, minor drift).
|
|
97
|
+
- **PASS** — no gaps; record the single `FND-001 | low | No gaps found | -` row.
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# Step 1: Target Selection
|
|
2
|
+
|
|
3
|
+
**Goal**: Resolve exactly what this run audits — one plan bundle, its spec, its Test
|
|
4
|
+
Matrix — and the `ix://` identity used in the output artifact.
|
|
5
|
+
|
|
6
|
+
## Process
|
|
7
|
+
|
|
8
|
+
### 1. Resolve the target plan
|
|
9
|
+
|
|
10
|
+
Mirror `spec-to-plan/references/step-0-plan-selection.md`:
|
|
11
|
+
|
|
12
|
+
1. **Named in context?** If the user passed a plan id (`Plan-002`) or one was established
|
|
13
|
+
earlier this session, use it.
|
|
14
|
+
2. **Otherwise discover.** Glob `plan/*/plan.md`, read each frontmatter `id`/`title`/`status`,
|
|
15
|
+
and present the list:
|
|
16
|
+
|
|
17
|
+
```
|
|
18
|
+
Plans available to gap-analyze:
|
|
19
|
+
- Plan-001 electron-hello core app (active)
|
|
20
|
+
- Plan-002 packaging & distribution (active)
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Ask which one. One run targets **one** bundle.
|
|
24
|
+
|
|
25
|
+
### 2. Locate the spec and Test Matrix
|
|
26
|
+
|
|
27
|
+
- **Spec root.** Single-repo: `spec/`. Multi-repo: `specs/<category>/<component>/spec/`.
|
|
28
|
+
- **`org` / `component`.** Read from `spec/spec.md` frontmatter (`org`, `name`). These build
|
|
29
|
+
the `ix://<org>/<component>/<id>` URIs used in the SpecReview `relationships:`.
|
|
30
|
+
- **Test Matrix.** Look for `spec/matrix.md` first, then `spec/tests.md` (both names are in
|
|
31
|
+
use across the ecosystem). Note its frontmatter `id` (e.g. `TestMatrix-001` / `TM-001`)
|
|
32
|
+
for the `references` edge.
|
|
33
|
+
- **Requirements.** Note the requirement files under `spec/functional/`,
|
|
34
|
+
`spec/non-functional/`, `spec/usecase/`, `spec/stakeholder/` — Steps 3 and 4 trace against
|
|
35
|
+
these ids.
|
|
36
|
+
- **Source / test trees.** Identify where implementation and tests live (e.g. `src/` +
|
|
37
|
+
`tests/`, or language-specific layout). Used in Steps 2–4.
|
|
38
|
+
|
|
39
|
+
### 3. Hand off
|
|
40
|
+
|
|
41
|
+
State explicitly, so later steps and the artifact agree:
|
|
42
|
+
|
|
43
|
+
- target bundle path (e.g. `plan/Plan-002-packaging-distribution/`)
|
|
44
|
+
- spec root, matrix path + id
|
|
45
|
+
- `ix://<org>/<component>` prefix
|
|
46
|
+
- where source and tests live
|
|
47
|
+
|
|
48
|
+
## Notes
|
|
49
|
+
|
|
50
|
+
- If there is **no** plan bundle, stop and tell the user — gap-analysis audits a plan; it
|
|
51
|
+
does not invent one (use `spec-to-plan` first).
|
|
52
|
+
- If there is **no** Test Matrix, Step 2 a/Plan checks still run, but record a `high`
|
|
53
|
+
finding that the matrix is missing and Step 3 cannot verify coverage.
|