@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.
- package/.agents/plugins/marketplace.json +14 -0
- package/.codex-plugin/plugin.json +10 -0
- package/.github/plugin/marketplace.json +16 -0
- package/README.md +56 -6
- package/package.json +4 -1
- package/skills/spec-to-plan/SKILL.md +7 -0
- package/skills/specify/SKILL.md +30 -3
- package/skills/specify/references/writing-good-requirements.md +61 -0
|
@@ -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,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
|
|
111
|
-
|
|
112
|
-
|
|
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
|
|
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
|
-
|
|
128
|
-
|
|
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
|
+
"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.
|
package/skills/specify/SKILL.md
CHANGED
|
@@ -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)
|
|
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
|
|
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. **
|
|
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."
|