@agent-ix/quoin 0.4.1 → 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.
@@ -0,0 +1,14 @@
1
+ {
2
+ "name": "quoin",
3
+ "interface": {
4
+ "displayName": "Quoin"
5
+ },
6
+ "plugins": [
7
+ {
8
+ "name": "quoin",
9
+ "source": { "source": "local", "path": "./" },
10
+ "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
11
+ "category": "Productivity"
12
+ }
13
+ ]
14
+ }
@@ -0,0 +1,10 @@
1
+ {
2
+ "name": "quoin",
3
+ "version": "0.1.0",
4
+ "description": "Spec authoring, review, matrix, and planning skills for Agent IX.",
5
+ "skills": "./skills/",
6
+ "interface": {
7
+ "displayName": "Quoin",
8
+ "category": "Productivity"
9
+ }
10
+ }
@@ -0,0 +1,16 @@
1
+ {
2
+ "name": "quoin",
3
+ "owner": {
4
+ "name": "Agent IX"
5
+ },
6
+ "metadata": {
7
+ "description": "Spec authoring, review, matrix, and planning skills + workflows for Agent IX."
8
+ },
9
+ "plugins": [
10
+ {
11
+ "name": "quoin",
12
+ "source": "./",
13
+ "description": "Spec authoring, review, matrix, and planning skills for Agent IX."
14
+ }
15
+ ]
16
+ }
package/README.md CHANGED
@@ -107,9 +107,10 @@ The default module set defines the spec archetypes and domain-object vocabulary.
107
107
 
108
108
  ## Install
109
109
 
110
- Installing quoin into Claude is **two steps**: the CLI (from public npm) and the plugin
111
- that adds the [skills](#agent-skills) and [workflows](#agent-workflows) to Claude Code. No Anthropic API
112
- key is required — your Claude subscription is used.
110
+ Installing quoin is **two steps**: the CLI (from public npm) and a plugin that adds the
111
+ [skills](#agent-skills) and workflows to your coding agent. The same skill bundle installs
112
+ into **Claude Code, OpenAI Codex, opencode, and GitHub Copilot** — pick your agent below. No
113
+ Anthropic API key is required — your existing agent subscription is used.
113
114
 
114
115
  **1. Install the CLIs** (`quoin` plus `ix-flow`, which runs the workflow lifecycle commands):
115
116
 
@@ -117,15 +118,64 @@ key is required — your Claude subscription is used.
117
118
  npm install -g @agent-ix/quoin@latest @agent-ix/ix-flow@latest
118
119
  ```
119
120
 
120
- **2. Add the plugin to Claude Code** (run these inside Claude Code):
121
+ **2. Add the plugin to your coding agent:**
122
+
123
+ <details>
124
+ <summary><b>Claude Code</b></summary>
125
+
126
+ Run these inside Claude Code:
121
127
 
122
128
  ```text
123
129
  /plugin marketplace add agent-ix/quoin
124
130
  /plugin install quoin@quoin
125
131
  ```
126
132
 
127
- That registers quoin's spec-authoring skills and workflows so you can drive them by asking
128
- the agent.
133
+ </details>
134
+
135
+ <details>
136
+ <summary><b>OpenAI Codex</b></summary>
137
+
138
+ ```bash
139
+ codex plugin marketplace add agent-ix/quoin
140
+ codex plugin add quoin
141
+ ```
142
+
143
+ Or browse and install quoin from the `/plugins` menu inside the Codex TUI.
144
+
145
+ </details>
146
+
147
+ <details>
148
+ <summary><b>opencode</b></summary>
149
+
150
+ Install the skills with the GitHub CLI (requires `gh` ≥ 2.90.0). `--all` installs
151
+ the whole bundle; `--scope user` makes it available in every repo:
152
+
153
+ ```bash
154
+ gh skill install agent-ix/quoin --all --scope user --agent opencode
155
+ ```
156
+
157
+ </details>
158
+
159
+ <details>
160
+ <summary><b>GitHub Copilot</b></summary>
161
+
162
+ With the Copilot CLI:
163
+
164
+ ```bash
165
+ copilot plugin marketplace add agent-ix/quoin
166
+ copilot plugin install quoin@quoin
167
+ ```
168
+
169
+ Or install the skills with the GitHub CLI (requires `gh` ≥ 2.90.0):
170
+
171
+ ```bash
172
+ gh skill install agent-ix/quoin --all --scope user --agent github-copilot
173
+ ```
174
+
175
+ </details>
176
+
177
+ Either way, that registers quoin's spec-authoring skills and workflows so you can drive them
178
+ by asking the agent.
129
179
 
130
180
  ## Usage
131
181
 
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.1",
4
+ "version": "0.5.1",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "files": [
@@ -10,6 +10,9 @@
10
10
  "skills/",
11
11
  "bin/",
12
12
  ".claude-plugin/",
13
+ ".codex-plugin/",
14
+ ".agents/",
15
+ ".github/plugin/",
13
16
  "LICENSE",
14
17
  "README.md"
15
18
  ],
@@ -63,3 +63,10 @@ This skill produces or updates a **plan bundle** at `<project_root>/plan/<Plan-i
63
63
 
64
64
  Validate the bundle with:
65
65
  `quire validate --scope <project_root> "plan/**/*.md"`
66
+
67
+ ## Open in the review cockpit
68
+
69
+ After the bundle validates, run `filament open <plan-bundle>/plan.md` to open the
70
+ plan in the running filament-ide cockpit (it fires the `filament-ide://` deep link
71
+ and prints a clickable link as a fallback). Skip silently if the `filament`
72
+ command is not installed.
@@ -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,14 +71,23 @@ 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
65
83
  every error before continuing.
66
- 6. **Stop at IT.** Then ask the user whether to build the test matrix
84
+ 6. **Open in the review cockpit.** After validation passes, run
85
+ `filament open <primary-artifact>` to open the authored artifact in the running
86
+ filament-ide cockpit (it fires the `filament-ide://` deep link and prints a
87
+ clickable link as a fallback). Use the main artifact you created — the
88
+ new/edited `FR-XXX.md`, or `spec/spec.md` when starting a spec. Skip silently if
89
+ the `filament` command is not installed.
90
+ 7. **Stop at IT.** Then ask the user whether to build the test matrix
67
91
  (`spec-matrix`) and run review (`spec-review`) — unless they already requested
68
92
  them. Only run those on confirmation.
69
93
 
@@ -74,6 +98,9 @@ each with an Acceptance Criteria table (the `fr.md` skeleton enforces the shape)
74
98
 
75
99
  - Derive FRs from the driving user story — see
76
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).
77
104
  - A behavioral FR has no `object:` field. A **domain-typed** FR carries
78
105
  `object: <type>` (e.g. `entity`, `event`, `api_endpoint`, `process`,
79
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."