@agent-ix/quoin 0.2.1 → 0.3.6
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/.claude-plugin/marketplace.json +16 -0
- package/{plugin.json → .claude-plugin/plugin.json} +3 -1
- package/README.md +19 -8
- package/dist/{cli-ClS52_Fm.js → cli-CNlT2O2s.js} +56 -50
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +1 -1
- package/dist/index.js +1 -1
- package/package.json +4 -4
- package/skills/spec-object-review/references/object-type-guide.md +5 -0
- package/skills/specify/SKILL.md +86 -33
- package/skills/specify/references/integration-tests.md +72 -0
- package/skills/specify/references/us-to-fr.md +40 -0
- package/skills/spec-matrix/workflow-assets/dist/index.d.ts +0 -146
- package/skills/spec-matrix/workflow-assets/dist/index.d.ts.map +0 -1
- package/skills/spec-matrix/workflow-assets/dist/index.js +0 -7655
- package/skills/spec-matrix/workflow-assets/dist/invariants.d.ts +0 -6
- package/skills/spec-matrix/workflow-assets/dist/invariants.d.ts.map +0 -1
- package/skills/spec-review/workflow-assets/dist/index.d.ts +0 -146
- package/skills/spec-review/workflow-assets/dist/index.d.ts.map +0 -1
- package/skills/spec-review/workflow-assets/dist/index.js +0 -7655
- package/skills/spec-review/workflow-assets/dist/invariants.d.ts +0 -6
- package/skills/spec-review/workflow-assets/dist/invariants.d.ts.map +0 -1
- package/skills/spec-to-plan/workflow-assets/dist/index.d.ts +0 -146
- package/skills/spec-to-plan/workflow-assets/dist/index.d.ts.map +0 -1
- package/skills/spec-to-plan/workflow-assets/dist/index.js +0 -7655
- package/skills/spec-to-plan/workflow-assets/dist/invariants.d.ts +0 -6
- package/skills/spec-to-plan/workflow-assets/dist/invariants.d.ts.map +0 -1
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# Authoring Integration Tests (IT)
|
|
2
|
+
|
|
3
|
+
Load this when a request involves integration tests — i.e. the system talks to
|
|
4
|
+
external services (HTTP APIs, event buses, databases, third-party/cloud APIs).
|
|
5
|
+
The per-section shape comes from the `IT` template (`quoin write --types IT`);
|
|
6
|
+
this file carries the *reasoning and reality rules* that the template can't
|
|
7
|
+
enforce.
|
|
8
|
+
|
|
9
|
+
## Scope
|
|
10
|
+
|
|
11
|
+
HTTP client integrations, event bus connections (Kafka, RabbitMQ), database
|
|
12
|
+
connections (Postgres, Redis), and external APIs. One test case per file,
|
|
13
|
+
sequentially numbered (`IT-XXX`), saved to `spec/integration/IT-XXX-*.md`.
|
|
14
|
+
|
|
15
|
+
## Reality rules — REAL by default
|
|
16
|
+
|
|
17
|
+
> Integration tests are **ALWAYS REAL** by default. Nothing is mocked unless the
|
|
18
|
+
> spec explicitly says so. An IT that only checks imports or constructs models
|
|
19
|
+
> without exercising real behavior is a **GAP**.
|
|
20
|
+
|
|
21
|
+
Every IT MUST include acceptance criteria from **both** categories:
|
|
22
|
+
|
|
23
|
+
- **Real Setup ACs** — the non-mocked environment is established: service running
|
|
24
|
+
and healthy (real health endpoint), real dependencies available (DB, bus,
|
|
25
|
+
external service), fixtures loaded into real stores, config applied through real
|
|
26
|
+
loading paths.
|
|
27
|
+
- **Real Output ACs** — real output from real services: HTTP responses
|
|
28
|
+
(status/headers/body), DB state changes (rows inserted/updated/deleted), events
|
|
29
|
+
published to and consumed from a real bus, file-system state, SSE/WebSocket
|
|
30
|
+
streams, LLM responses through real provider chains.
|
|
31
|
+
|
|
32
|
+
| Real (required) | Not real (GAP) |
|
|
33
|
+
| ------------------------------------------------- | ------------------------------ |
|
|
34
|
+
| POST to endpoint, assert response body | `assert MyModel is not None` |
|
|
35
|
+
| Query DB after a write, verify rows changed | `MyModel(field="value")` |
|
|
36
|
+
| Publish event, consume from real bus, verify load | `assert EventSchema is not None` |
|
|
37
|
+
| GET /health, verify HTTP 200 + status body | `assert app is not None` |
|
|
38
|
+
|
|
39
|
+
### Mocking policy
|
|
40
|
+
|
|
41
|
+
- **Default: NO MOCKS.** ITs exercise real service boundaries.
|
|
42
|
+
- **Approved mock targets** only when the spec explicitly requires it: external
|
|
43
|
+
third-party APIs (payment, auth, cloud) via test doubles over real HTTP;
|
|
44
|
+
external services outside the test boundary via contract-faithful stubs.
|
|
45
|
+
- **Never mock**: HTTP transport, config loading, DB connections, file I/O,
|
|
46
|
+
session storage, event publishing, health endpoints, WebSocket/SSE connections.
|
|
47
|
+
- When a mock IS used, the IT must state WHY the real service can't be used, WHAT
|
|
48
|
+
boundary the mock replaces, and HOW the mock is verified faithful.
|
|
49
|
+
|
|
50
|
+
## Process
|
|
51
|
+
|
|
52
|
+
1. List the external dependencies from the codebase (the integration points).
|
|
53
|
+
2. Take the next `IT-XXX`; get the contract with `quoin write --types IT`.
|
|
54
|
+
3. Fill the template: Target Integration (service + protocol), Preconditions
|
|
55
|
+
(environment + data state), Test Data (`TD-XXX` fixtures with rationale),
|
|
56
|
+
Execution Plan (atomic steps, each with a timeout and `IT-XXX-SC-XX` success
|
|
57
|
+
criterion), Expected Outcome (success condition + failure modes).
|
|
58
|
+
4. **Traceability is required**: every IT links to ≥1 FR/StR/NFR via frontmatter
|
|
59
|
+
`relationships:` (`type: verifies`). Cross-component references are fine
|
|
60
|
+
(e.g. `ix://org/other-service/FR-001`) per ISO 29148 bidirectional traceability.
|
|
61
|
+
|
|
62
|
+
## Patterns by service type
|
|
63
|
+
|
|
64
|
+
- **API (FastAPI/REST)**: CRUD to real endpoints (verify codes/body/DB state);
|
|
65
|
+
invalid payloads → real 4xx; auth with/without creds → real 401/403.
|
|
66
|
+
- **Database**: real Alembic migrations → schema state; insert/query/update/delete
|
|
67
|
+
→ row state; constraint violations → real DB errors.
|
|
68
|
+
- **Event-driven (FastStream)**: publish to a real topic, consume, verify payload;
|
|
69
|
+
produce an event, verify processing + side effects.
|
|
70
|
+
- **Worker**: submit a real job → completion state; slow job → timeout + cleanup.
|
|
71
|
+
- **Agent (LLM)**: deterministic scripted LLM via real API → verify tool calls;
|
|
72
|
+
real tool execution → file/process state; real SSE/WS → event sequence.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Deriving Functional Requirements from a User Story
|
|
2
|
+
|
|
3
|
+
Load this when a request involves turning user stories into functional
|
|
4
|
+
requirements. It carries the *reasoning* for the derivation; the per-FR section
|
|
5
|
+
rules come from the `FR` template (`quoin write --types FR`).
|
|
6
|
+
|
|
7
|
+
## Rules
|
|
8
|
+
|
|
9
|
+
- **Atomic**: decompose the story into specific, single-behavior FRs.
|
|
10
|
+
- **Normative**: FRs use `SHALL` / `SHALL NOT` (a US never does).
|
|
11
|
+
- **No copying**: translate intent into a technical specification — do not paste
|
|
12
|
+
the story text.
|
|
13
|
+
- **Verifiable**: every FR carries its own Acceptance Criteria table.
|
|
14
|
+
|
|
15
|
+
## Process
|
|
16
|
+
|
|
17
|
+
1. **Analyze** the `US-XXX`: list the system responsibilities it implies.
|
|
18
|
+
2. **Decompose** into typed FRs. A behavioral FR (no `object:`) captures logic
|
|
19
|
+
and business rules. A domain-typed FR carries `object: <type>` and is purely
|
|
20
|
+
structural:
|
|
21
|
+
- `entity` — data model with typed fields
|
|
22
|
+
- `event` — a domain event emitted
|
|
23
|
+
- `api_endpoint` — a REST/HTTP endpoint
|
|
24
|
+
- `queue` — a message contract
|
|
25
|
+
- `process` — an end-to-end workflow
|
|
26
|
+
- `state_machine` — an entity lifecycle
|
|
27
|
+
- `configuration` — a configuration schema
|
|
28
|
+
- Full list + relationship verbs: `spec-object-review`'s
|
|
29
|
+
`references/object-type-guide.md`; inspect any type with
|
|
30
|
+
`quoin catalog show <type>`.
|
|
31
|
+
3. **Author** each FR as its own file (`quoin write --types FR` for the contract),
|
|
32
|
+
and link it back to the story via frontmatter `relationships:`
|
|
33
|
+
(`type: implements`, target the `US-XXX`).
|
|
34
|
+
4. **Specify** inputs/outputs (typed and validated), error handling (failure
|
|
35
|
+
modes), and constraints (technical limits, not options).
|
|
36
|
+
5. **Separation of concerns**: keep behavioral triggers/validation in behavioral
|
|
37
|
+
FRs; domain-typed FR acceptance criteria test **structure** only (schema/field
|
|
38
|
+
presence), never behavior. Do not duplicate behavioral ACs into a domain FR.
|
|
39
|
+
6. **Save** to `spec/functional/FR-XXX-description.md` (single repo) or
|
|
40
|
+
`specs/<category>/<component>/spec/functional/FR-XXX-description.md` (multi-repo).
|
|
@@ -1,146 +0,0 @@
|
|
|
1
|
-
export interface SpecSkill {
|
|
2
|
-
readonly id: string;
|
|
3
|
-
readonly path: string;
|
|
4
|
-
readonly workflows: readonly string[];
|
|
5
|
-
readonly category: "create-edit" | "write" | "derive" | "review" | "analysis" | "planning" | "graph";
|
|
6
|
-
}
|
|
7
|
-
export declare const specSkills: readonly [{
|
|
8
|
-
readonly id: "spec-create";
|
|
9
|
-
readonly path: "skills/create";
|
|
10
|
-
readonly workflows: readonly ["spec-create", "spec-edit", "spec-batch"];
|
|
11
|
-
readonly category: "create-edit";
|
|
12
|
-
}, {
|
|
13
|
-
readonly id: "spec-write-str";
|
|
14
|
-
readonly path: "skills/write-str";
|
|
15
|
-
readonly workflows: readonly ["write-str"];
|
|
16
|
-
readonly category: "write";
|
|
17
|
-
}, {
|
|
18
|
-
readonly id: "spec-write-us";
|
|
19
|
-
readonly path: "skills/write-us";
|
|
20
|
-
readonly workflows: readonly ["write-us"];
|
|
21
|
-
readonly category: "write";
|
|
22
|
-
}, {
|
|
23
|
-
readonly id: "spec-write-fr";
|
|
24
|
-
readonly path: "skills/write-fr";
|
|
25
|
-
readonly workflows: readonly ["write-fr"];
|
|
26
|
-
readonly category: "write";
|
|
27
|
-
}, {
|
|
28
|
-
readonly id: "spec-write-nfr";
|
|
29
|
-
readonly path: "skills/write-nfr";
|
|
30
|
-
readonly workflows: readonly ["write-nfr"];
|
|
31
|
-
readonly category: "write";
|
|
32
|
-
}, {
|
|
33
|
-
readonly id: "spec-write-it";
|
|
34
|
-
readonly path: "skills/write-it";
|
|
35
|
-
readonly workflows: readonly ["write-it"];
|
|
36
|
-
readonly category: "write";
|
|
37
|
-
}, {
|
|
38
|
-
readonly id: "spec-us-to-fr";
|
|
39
|
-
readonly path: "skills/us-to-fr";
|
|
40
|
-
readonly workflows: readonly ["us-to-fr"];
|
|
41
|
-
readonly category: "derive";
|
|
42
|
-
}, {
|
|
43
|
-
readonly id: "spec-convert-objects";
|
|
44
|
-
readonly path: "skills/convert-objects";
|
|
45
|
-
readonly workflows: readonly ["convert-objects"];
|
|
46
|
-
readonly category: "derive";
|
|
47
|
-
}, {
|
|
48
|
-
readonly id: "spec-matrix";
|
|
49
|
-
readonly path: "skills/matrix";
|
|
50
|
-
readonly workflows: readonly ["matrix"];
|
|
51
|
-
readonly category: "review";
|
|
52
|
-
}, {
|
|
53
|
-
readonly id: "spec-review";
|
|
54
|
-
readonly path: "skills/review";
|
|
55
|
-
readonly workflows: readonly ["review"];
|
|
56
|
-
readonly category: "review";
|
|
57
|
-
}, {
|
|
58
|
-
readonly id: "spec-analysis-integrity";
|
|
59
|
-
readonly path: "skills/analysis-integrity";
|
|
60
|
-
readonly workflows: readonly ["analysis-integrity"];
|
|
61
|
-
readonly category: "analysis";
|
|
62
|
-
}, {
|
|
63
|
-
readonly id: "spec-analysis-failure-domain";
|
|
64
|
-
readonly path: "skills/analysis-failure-domain";
|
|
65
|
-
readonly workflows: readonly ["analysis-failure-domain"];
|
|
66
|
-
readonly category: "analysis";
|
|
67
|
-
}, {
|
|
68
|
-
readonly id: "spec-analysis-dependency";
|
|
69
|
-
readonly path: "skills/analysis-dependency";
|
|
70
|
-
readonly workflows: readonly ["analysis-dependency"];
|
|
71
|
-
readonly category: "analysis";
|
|
72
|
-
}, {
|
|
73
|
-
readonly id: "spec-analysis-evidence";
|
|
74
|
-
readonly path: "skills/analysis-evidence";
|
|
75
|
-
readonly workflows: readonly ["analysis-evidence"];
|
|
76
|
-
readonly category: "analysis";
|
|
77
|
-
}, {
|
|
78
|
-
readonly id: "spec-analysis-risk-complexity";
|
|
79
|
-
readonly path: "skills/analysis-risk-complexity";
|
|
80
|
-
readonly workflows: readonly ["analysis-risk-complexity"];
|
|
81
|
-
readonly category: "analysis";
|
|
82
|
-
}, {
|
|
83
|
-
readonly id: "spec-analysis-scope-boundary";
|
|
84
|
-
readonly path: "skills/analysis-scope-boundary";
|
|
85
|
-
readonly workflows: readonly ["analysis-scope-boundary"];
|
|
86
|
-
readonly category: "analysis";
|
|
87
|
-
}, {
|
|
88
|
-
readonly id: "spec-object-review";
|
|
89
|
-
readonly path: "skills/object-review";
|
|
90
|
-
readonly workflows: readonly ["object-review"];
|
|
91
|
-
readonly category: "review";
|
|
92
|
-
}, {
|
|
93
|
-
readonly id: "spec-app-review";
|
|
94
|
-
readonly path: "skills/app-review";
|
|
95
|
-
readonly workflows: readonly ["app-review"];
|
|
96
|
-
readonly category: "review";
|
|
97
|
-
}, {
|
|
98
|
-
readonly id: "spec-security-analysis";
|
|
99
|
-
readonly path: "skills/security-analysis";
|
|
100
|
-
readonly workflows: readonly ["security-analysis"];
|
|
101
|
-
readonly category: "analysis";
|
|
102
|
-
}, {
|
|
103
|
-
readonly id: "spec-blueprint";
|
|
104
|
-
readonly path: "skills/blueprint";
|
|
105
|
-
readonly workflows: readonly ["blueprint"];
|
|
106
|
-
readonly category: "planning";
|
|
107
|
-
}, {
|
|
108
|
-
readonly id: "spec-task-generation-readiness";
|
|
109
|
-
readonly path: "skills/task-generation-readiness";
|
|
110
|
-
readonly workflows: readonly ["task-generation-readiness"];
|
|
111
|
-
readonly category: "planning";
|
|
112
|
-
}, {
|
|
113
|
-
readonly id: "spec-to-plan";
|
|
114
|
-
readonly path: "skills/to-plan";
|
|
115
|
-
readonly workflows: readonly ["to-plan"];
|
|
116
|
-
readonly category: "planning";
|
|
117
|
-
}, {
|
|
118
|
-
readonly id: "spec-implementation-gap-analysis";
|
|
119
|
-
readonly path: "skills/implementation-gap-analysis";
|
|
120
|
-
readonly workflows: readonly ["implementation-gap-analysis"];
|
|
121
|
-
readonly category: "analysis";
|
|
122
|
-
}, {
|
|
123
|
-
readonly id: "spec-core-search";
|
|
124
|
-
readonly path: "skills/core-search";
|
|
125
|
-
readonly workflows: readonly ["core-search"];
|
|
126
|
-
readonly category: "graph";
|
|
127
|
-
}, {
|
|
128
|
-
readonly id: "spec-core-explore-objects";
|
|
129
|
-
readonly path: "skills/core-explore-objects";
|
|
130
|
-
readonly workflows: readonly ["core-explore-objects"];
|
|
131
|
-
readonly category: "graph";
|
|
132
|
-
}, {
|
|
133
|
-
readonly id: "spec-core-trace-analysis";
|
|
134
|
-
readonly path: "skills/core-trace-analysis";
|
|
135
|
-
readonly workflows: readonly ["core-trace-analysis"];
|
|
136
|
-
readonly category: "graph";
|
|
137
|
-
}, {
|
|
138
|
-
readonly id: "spec-core-review";
|
|
139
|
-
readonly path: "skills/core-review";
|
|
140
|
-
readonly workflows: readonly ["core-review"];
|
|
141
|
-
readonly category: "graph";
|
|
142
|
-
}];
|
|
143
|
-
export declare function skillById(id: string): SpecSkill | undefined;
|
|
144
|
-
export declare function workflowSkillPath(workflowName: string): string | undefined;
|
|
145
|
-
export { artifactFrontmatterValid, artifactRelationshipsResolve, clearProjectRegistryCache, specInvariants, } from './invariants.js';
|
|
146
|
-
//# sourceMappingURL=index.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,QAAQ,EACb,aAAa,GACb,OAAO,GACP,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,UAAU,GACV,OAAO,CAAC;CACb;AAED,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmKkB,CAAC;AAE1C,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAE3D;AAED,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAI1E;AAED,OAAO,EACL,wBAAwB,EACxB,4BAA4B,EAC5B,yBAAyB,EACzB,cAAc,GACf,MAAM,iBAAiB,CAAC"}
|