@agent-ix/quoin 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 (215) hide show
  1. package/.agents/plugins/marketplace.json +14 -0
  2. package/.claude-plugin/marketplace.json +16 -0
  3. package/.claude-plugin/plugin.json +8 -0
  4. package/.codex-plugin/plugin.json +27 -0
  5. package/.github/plugin/marketplace.json +16 -0
  6. package/LICENSE +21 -0
  7. package/README.md +266 -0
  8. package/bin/quoin.js +14 -0
  9. package/default-modules.yaml +82 -0
  10. package/dist/base-DrUMkAh1.js +137 -0
  11. package/dist/base.d.ts +23 -0
  12. package/dist/base.d.ts.map +1 -0
  13. package/dist/catalog.d.ts +32 -0
  14. package/dist/catalog.d.ts.map +1 -0
  15. package/dist/cli.d.ts +18 -0
  16. package/dist/cli.d.ts.map +1 -0
  17. package/dist/cli.js +20 -0
  18. package/dist/commands/catalog/index.d.ts +2 -0
  19. package/dist/commands/catalog/index.d.ts.map +1 -0
  20. package/dist/commands/catalog/index.js +2 -0
  21. package/dist/commands/catalog/list.d.ts +11 -0
  22. package/dist/commands/catalog/list.d.ts.map +1 -0
  23. package/dist/commands/catalog/list.js +22 -0
  24. package/dist/commands/catalog/show.d.ts +13 -0
  25. package/dist/commands/catalog/show.d.ts.map +1 -0
  26. package/dist/commands/catalog/show.js +25 -0
  27. package/dist/commands/catalog/validate.d.ts +10 -0
  28. package/dist/commands/catalog/validate.d.ts.map +1 -0
  29. package/dist/commands/catalog/validate.js +27 -0
  30. package/dist/commands/config/doctor.d.ts +7 -0
  31. package/dist/commands/config/doctor.d.ts.map +1 -0
  32. package/dist/commands/config/doctor.js +15 -0
  33. package/dist/commands/config/edit.d.ts +7 -0
  34. package/dist/commands/config/edit.d.ts.map +1 -0
  35. package/dist/commands/config/edit.js +13 -0
  36. package/dist/commands/config/get.d.ts +11 -0
  37. package/dist/commands/config/get.d.ts.map +1 -0
  38. package/dist/commands/config/get.js +20 -0
  39. package/dist/commands/config/index.d.ts +2 -0
  40. package/dist/commands/config/index.d.ts.map +1 -0
  41. package/dist/commands/config/index.js +2 -0
  42. package/dist/commands/config/set.d.ts +12 -0
  43. package/dist/commands/config/set.d.ts.map +1 -0
  44. package/dist/commands/config/set.js +26 -0
  45. package/dist/commands/matrix.d.ts +14 -0
  46. package/dist/commands/matrix.d.ts.map +1 -0
  47. package/dist/commands/matrix.js +15 -0
  48. package/dist/commands/module/ensure-defaults.d.ts +8 -0
  49. package/dist/commands/module/ensure-defaults.d.ts.map +1 -0
  50. package/dist/commands/module/ensure-defaults.js +17 -0
  51. package/dist/commands/module/index.d.ts +2 -0
  52. package/dist/commands/module/index.d.ts.map +1 -0
  53. package/dist/commands/module/index.js +2 -0
  54. package/dist/commands/module/install.d.ts +11 -0
  55. package/dist/commands/module/install.d.ts.map +1 -0
  56. package/dist/commands/module/install.js +22 -0
  57. package/dist/commands/module/list.d.ts +8 -0
  58. package/dist/commands/module/list.d.ts.map +1 -0
  59. package/dist/commands/module/list.js +13 -0
  60. package/dist/commands/module/remove.d.ts +10 -0
  61. package/dist/commands/module/remove.d.ts.map +1 -0
  62. package/dist/commands/module/remove.js +16 -0
  63. package/dist/commands/plugin/deprecation.d.ts +10 -0
  64. package/dist/commands/plugin/deprecation.d.ts.map +1 -0
  65. package/dist/commands/plugin/ensure-defaults.d.ts +8 -0
  66. package/dist/commands/plugin/ensure-defaults.d.ts.map +1 -0
  67. package/dist/commands/plugin/ensure-defaults.js +12 -0
  68. package/dist/commands/plugin/index.d.ts +2 -0
  69. package/dist/commands/plugin/index.d.ts.map +1 -0
  70. package/dist/commands/plugin/index.js +2 -0
  71. package/dist/commands/plugin/install.d.ts +8 -0
  72. package/dist/commands/plugin/install.d.ts.map +1 -0
  73. package/dist/commands/plugin/install.js +12 -0
  74. package/dist/commands/plugin/list.d.ts +8 -0
  75. package/dist/commands/plugin/list.d.ts.map +1 -0
  76. package/dist/commands/plugin/list.js +12 -0
  77. package/dist/commands/plugin/remove.d.ts +8 -0
  78. package/dist/commands/plugin/remove.d.ts.map +1 -0
  79. package/dist/commands/plugin/remove.js +12 -0
  80. package/dist/commands/review.d.ts +14 -0
  81. package/dist/commands/review.d.ts.map +1 -0
  82. package/dist/commands/review.js +15 -0
  83. package/dist/commands/to-plan.d.ts +14 -0
  84. package/dist/commands/to-plan.d.ts.map +1 -0
  85. package/dist/commands/to-plan.js +15 -0
  86. package/dist/commands/update.d.ts +13 -0
  87. package/dist/commands/update.d.ts.map +1 -0
  88. package/dist/commands/update.js +34 -0
  89. package/dist/commands/write.d.ts +16 -0
  90. package/dist/commands/write.d.ts.map +1 -0
  91. package/dist/commands/write.js +33 -0
  92. package/dist/config-schema-Dp-vlxuR.js +13 -0
  93. package/dist/config-schema.d.ts +52 -0
  94. package/dist/config-schema.d.ts.map +1 -0
  95. package/dist/deprecation-fRxUHoxv.js +4 -0
  96. package/dist/flow-command-SMjCSOFg.js +88 -0
  97. package/dist/flow-command.d.ts +25 -0
  98. package/dist/flow-command.d.ts.map +1 -0
  99. package/dist/flows.d.ts +7 -0
  100. package/dist/flows.d.ts.map +1 -0
  101. package/dist/index.d.ts +11 -0
  102. package/dist/index.d.ts.map +1 -0
  103. package/dist/index.js +9 -0
  104. package/dist/modules-CW8pBK41.js +22 -0
  105. package/dist/modules.d.ts +10 -0
  106. package/dist/modules.d.ts.map +1 -0
  107. package/dist/org.d.ts +61 -0
  108. package/dist/org.d.ts.map +1 -0
  109. package/dist/plugins-GSxafyD3.js +77 -0
  110. package/dist/plugins.d.ts +13 -0
  111. package/dist/plugins.d.ts.map +1 -0
  112. package/dist/version-_1nY4KyJ.js +17 -0
  113. package/dist/version.d.ts +3 -0
  114. package/dist/version.d.ts.map +1 -0
  115. package/dist/write-CQAitcI5.js +156 -0
  116. package/dist/write.d.ts +28 -0
  117. package/dist/write.d.ts.map +1 -0
  118. package/package.json +119 -0
  119. package/skills/gap-analysis/SKILL.md +97 -0
  120. package/skills/gap-analysis/references/step-1-target-selection.md +53 -0
  121. package/skills/gap-analysis/references/step-2-plan-completion.md +49 -0
  122. package/skills/gap-analysis/references/step-3-matrix-verification.md +54 -0
  123. package/skills/gap-analysis/references/step-4-underspecified-code.md +63 -0
  124. package/skills/gap-analysis/references/step-5-semantic-review.md +51 -0
  125. package/skills/gap-analysis/references/step-6-specreview-artifact.md +95 -0
  126. package/skills/spec-app-review/SKILL.md +51 -0
  127. package/skills/spec-app-review/references/checklist.md +197 -0
  128. package/skills/spec-dependency-analysis/SKILL.md +75 -0
  129. package/skills/spec-ears-analysis/SKILL.md +89 -0
  130. package/skills/spec-evidence-analysis/SKILL.md +78 -0
  131. package/skills/spec-failure-domain-analysis/SKILL.md +44 -0
  132. package/skills/spec-ideation/SKILL.md +46 -0
  133. package/skills/spec-integrity-analysis/SKILL.md +47 -0
  134. package/skills/spec-matrix/SKILL.md +168 -0
  135. package/skills/spec-matrix/assets/test-cases/TC-001.md +35 -0
  136. package/skills/spec-matrix/assets/test-cases/TC-002.md +37 -0
  137. package/skills/spec-matrix/assets/test-cases/TC-006.md +50 -0
  138. package/skills/spec-matrix/assets/test-matrix-example.md +104 -0
  139. package/skills/spec-matrix/assets/test-matrix-template.md +123 -0
  140. package/skills/spec-matrix/workflow-assets/skills/matrix/SKILL.md +35 -0
  141. package/skills/spec-matrix/workflow-assets/skills/matrix/scripts/invariants.js +1 -0
  142. package/skills/spec-matrix/workflow-assets/skills/matrix/templates/report/default.md +30 -0
  143. package/skills/spec-matrix/workflow-assets/skills/matrix/workflows/matrix/def.yaml +82 -0
  144. package/skills/spec-object-review/SKILL.md +125 -0
  145. package/skills/spec-object-review/references/object-type-guide.md +118 -0
  146. package/skills/spec-review/SKILL.md +71 -0
  147. package/skills/spec-review/references/checklist.md +50 -0
  148. package/skills/spec-review/workflow-assets/skills/review/SKILL.md +96 -0
  149. package/skills/spec-review/workflow-assets/skills/review/scripts/invariants.js +60 -0
  150. package/skills/spec-review/workflow-assets/skills/review/workflows/review/def.yaml +68 -0
  151. package/skills/spec-risk-complexity-analysis/SKILL.md +77 -0
  152. package/skills/spec-scope-boundary-analysis/SKILL.md +86 -0
  153. package/skills/spec-security-analysis/SKILL.md +84 -0
  154. package/skills/spec-security-analysis/assets/security-analysis-example.md +89 -0
  155. package/skills/spec-security-analysis/assets/security-analysis-template.md +73 -0
  156. package/skills/spec-security-analysis/references/component-type-mapping.md +161 -0
  157. package/skills/spec-security-analysis/references/gdpr/ChII-Principles.md +58 -0
  158. package/skills/spec-security-analysis/references/gdpr/ChIII-DataSubjectRights.md +84 -0
  159. package/skills/spec-security-analysis/references/gdpr/ChIV-ControllerProcessor.md +83 -0
  160. package/skills/spec-security-analysis/references/gdpr/ChV-DataTransfers.md +62 -0
  161. package/skills/spec-security-analysis/references/gdpr/index.md +54 -0
  162. package/skills/spec-security-analysis/references/iso27001/A5-OrganizationalControls.md +64 -0
  163. package/skills/spec-security-analysis/references/iso27001/A6-PeopleControls.md +30 -0
  164. package/skills/spec-security-analysis/references/iso27001/A7-PhysicalControls.md +35 -0
  165. package/skills/spec-security-analysis/references/iso27001/A8-TechnologicalControls.md +66 -0
  166. package/skills/spec-security-analysis/references/iso27001/index.md +43 -0
  167. package/skills/spec-security-analysis/references/nist-800-53/AC-AccessControl.md +57 -0
  168. package/skills/spec-security-analysis/references/nist-800-53/AU-AuditAccountability.md +49 -0
  169. package/skills/spec-security-analysis/references/nist-800-53/CM-ConfigurationManagement.md +36 -0
  170. package/skills/spec-security-analysis/references/nist-800-53/IA-IdentificationAuthentication.md +44 -0
  171. package/skills/spec-security-analysis/references/nist-800-53/SA-SystemServicesAcquisition.md +50 -0
  172. package/skills/spec-security-analysis/references/nist-800-53/SC-SystemCommunications.md +53 -0
  173. package/skills/spec-security-analysis/references/nist-800-53/SI-SystemInformationIntegrity.md +52 -0
  174. package/skills/spec-security-analysis/references/nist-800-53/index.md +58 -0
  175. package/skills/spec-security-analysis/references/owasp-asvs/V1-Architecture.md +33 -0
  176. package/skills/spec-security-analysis/references/owasp-asvs/V10-MaliciousCode.md +33 -0
  177. package/skills/spec-security-analysis/references/owasp-asvs/V11-BusinessLogic.md +32 -0
  178. package/skills/spec-security-analysis/references/owasp-asvs/V12-Files.md +34 -0
  179. package/skills/spec-security-analysis/references/owasp-asvs/V13-API.md +34 -0
  180. package/skills/spec-security-analysis/references/owasp-asvs/V14-Configuration.md +35 -0
  181. package/skills/spec-security-analysis/references/owasp-asvs/V2-Authentication.md +36 -0
  182. package/skills/spec-security-analysis/references/owasp-asvs/V3-SessionManagement.md +35 -0
  183. package/skills/spec-security-analysis/references/owasp-asvs/V4-AccessControl.md +39 -0
  184. package/skills/spec-security-analysis/references/owasp-asvs/V5-Validation.md +37 -0
  185. package/skills/spec-security-analysis/references/owasp-asvs/V6-Cryptography.md +34 -0
  186. package/skills/spec-security-analysis/references/owasp-asvs/V7-ErrorLogging.md +37 -0
  187. package/skills/spec-security-analysis/references/owasp-asvs/V8-DataProtection.md +34 -0
  188. package/skills/spec-security-analysis/references/owasp-asvs/V9-Communication.md +32 -0
  189. package/skills/spec-security-analysis/references/owasp-asvs/index.md +59 -0
  190. package/skills/spec-security-analysis/references/soc2/CC1-ControlEnvironment.md +31 -0
  191. package/skills/spec-security-analysis/references/soc2/CC2-CommunicationInformation.md +27 -0
  192. package/skills/spec-security-analysis/references/soc2/CC3-RiskAssessment.md +29 -0
  193. package/skills/spec-security-analysis/references/soc2/CC4-MonitoringActivities.md +27 -0
  194. package/skills/spec-security-analysis/references/soc2/CC5-ControlActivities.md +28 -0
  195. package/skills/spec-security-analysis/references/soc2/CC6-LogicalPhysicalAccess.md +45 -0
  196. package/skills/spec-security-analysis/references/soc2/CC7-SystemOperations.md +42 -0
  197. package/skills/spec-security-analysis/references/soc2/CC8-ChangeManagement.md +32 -0
  198. package/skills/spec-security-analysis/references/soc2/CC9-RiskMitigation.md +34 -0
  199. package/skills/spec-security-analysis/references/soc2/index.md +46 -0
  200. package/skills/spec-security-analysis/references/standards-index.md +46 -0
  201. package/skills/spec-to-plan/SKILL.md +75 -0
  202. package/skills/spec-to-plan/references/step-0-plan-selection.md +121 -0
  203. package/skills/spec-to-plan/references/step-1-analysis.md +88 -0
  204. package/skills/spec-to-plan/references/step-2-test-plan.md +43 -0
  205. package/skills/spec-to-plan/references/step-3-execution-plan.md +218 -0
  206. package/skills/spec-to-plan/workflow-assets/skills/to-plan/SKILL.md +35 -0
  207. package/skills/spec-to-plan/workflow-assets/skills/to-plan/scripts/invariants.js +1 -0
  208. package/skills/spec-to-plan/workflow-assets/skills/to-plan/templates/implementation-plan/default.md +44 -0
  209. package/skills/spec-to-plan/workflow-assets/skills/to-plan/workflows/to-plan/def.yaml +85 -0
  210. package/skills/specify/SKILL.md +154 -0
  211. package/skills/specify/assets/app-spec-template.md +143 -0
  212. package/skills/specify/assets/spec-template.md +299 -0
  213. package/skills/specify/references/integration-tests.md +72 -0
  214. package/skills/specify/references/us-to-fr.md +40 -0
  215. package/skills/specify/references/writing-good-requirements.md +61 -0
@@ -0,0 +1,96 @@
1
+ ---
2
+ name: spec-review
3
+ description: Run a composite specification review.
4
+ contributes:
5
+ workflows: ./workflows
6
+ ---
7
+
8
+ # /spec-review
9
+
10
+ ## When To Use
11
+
12
+ Use this skill for a full or multi-artifact spec review before implementation, release, or migration.
13
+
14
+ ## What It Does
15
+
16
+ Run a composite specification review. The workflow definition is the source of truth for
17
+ phases, gates, item schemas, and recipes. The review produces **one validated `SpecReview`
18
+ document per analysis** under `spec/reviews/`, rather than a single freeform report.
19
+
20
+ ## Workflow Behavior
21
+
22
+ - Start from the workflow status and follow reported next actions.
23
+ - **intake — offer the review set.** Before advancing, present the choice to the user and
24
+ record it in the `request` interview as `review_set` plus `selected_analyses`:
25
+ - `base` — the skill checklist only (ID formats, US/FR/TC quality, the six coverage
26
+ rules). No analysis skills. `selected_analyses` is empty.
27
+ - `all` — `base` plus all six analyses: `failure-domain`, `integrity`, `dependency`,
28
+ `evidence`, `risk-complexity`, `scope-boundary`.
29
+ - `subset` — `base` plus the analyses the user picks from those six.
30
+ - **analyses_run — run the selected set, one SpecReview doc each.** Run each selected
31
+ analysis (the matching `spec-*-analysis` skill). Prefer running them **in parallel** —
32
+ each writes its own file, so there is no contention.
33
+ - **Guardrail — fetch the template from quoin (do not invent the format).** Once, run
34
+ `quoin write <repo> --types SpecReview` and use the emitted skeleton + schema as the
35
+ authoritative contract. Reuse that one contract for every analysis doc.
36
+ - **Direct-author** a `SpecReview` markdown document per analysis to
37
+ `spec/reviews/<analysis>.md` from that template. `base` renders a single
38
+ `spec/reviews/base.md` with `analysis: base`.
39
+ - **reviews_rendered — validate (guardrail).** Always run the quire validation command (the
40
+ calling tool emits it, e.g. `quire validate --scope <repo> "spec/**/*.md"`). Fix any finding-table / severity
41
+ / id errors it reports. Only once a SpecReview doc validates, record it:
42
+ `add-item review_doc --item '{"id":"RD-<analysis>","analysis":"<analysis>","path":"spec/reviews/<analysis>.md"}'`
43
+ (the item `id` must be non-empty). These items drive the coverage gate.
44
+ - Use recipes for deterministic command chains, but preserve the human gate for acceptance.
45
+
46
+ ## SpecReview document structure
47
+
48
+ The **authoritative** template comes from `quoin write --types SpecReview` (fetch it; do not
49
+ hand-copy). The structure below is a reference for what that skeleton contains — each
50
+ `spec/reviews/<analysis>.md` is a `SpecReview` artifact (archetype in
51
+ `spec-artifacts-process`):
52
+
53
+ ```markdown
54
+ ---
55
+ id: SR-001
56
+ title: "<analysis> review of <scope>"
57
+ type: SpecReview
58
+ analysis: <failure-domain|integrity|dependency|evidence|risk-complexity|scope-boundary|base>
59
+ scope: <spec paths / ids>
60
+ review_set: <base|all|subset>
61
+ ---
62
+
63
+ ## Summary
64
+
65
+ <one or two sentences on what this analysis found>
66
+
67
+ ## Findings
68
+
69
+ | ID | Severity | Summary | Refs |
70
+ | --- | --- | --- | --- |
71
+ | FND-001 | medium | <one-line finding> | FR-014 |
72
+ ```
73
+
74
+ The `## Findings` table is **validated by quire**: exact columns `[ID, Severity, Summary,
75
+ Refs]`, at least one row, `FND-NNN` ids, and `Severity` must be one of `low`/`medium`/`high`.
76
+ An analysis that found nothing still renders a doc; record that as a single
77
+ `FND-001 | low | No issues found | —` row (or state it in `## Summary`).
78
+
79
+ ## Coverage gate
80
+
81
+ The final `validated → accepted` transition enforces `selected_analyses_covered`: the run
82
+ cannot be accepted until every selected analysis has a recorded `review_doc`. If it reports
83
+ `selected_analyses_not_run` with a `missing` list, render + validate + record those analyses
84
+ before retrying acceptance. `base` passes with no analyses required.
85
+
86
+ ## Acceptance Criteria
87
+
88
+ - AC-1: Reviews structural integrity, traceability, coverage, and readiness across selected artifacts.
89
+ - AC-2: Produces one validated `SpecReview` doc per selected analysis before acceptance.
90
+ - AC-3: Stops at acceptance with findings and recommended next workflows rather than making broad edits.
91
+
92
+ ## Boundaries
93
+
94
+ - Do not silently overwrite existing human-authored requirements artifacts.
95
+ - Do not invent missing facts, links, or evidence; record assumptions and gaps.
96
+ - Do not expand to adjacent spec operations unless the user request requires it or the workflow directs it.
@@ -0,0 +1,60 @@
1
+ import { specInvariants } from "../../../dist/index.js";
2
+
3
+ // Canonical "all" set — the six analyses named in the spec-review skill.
4
+ const ALL_ANALYSES = [
5
+ "failure-domain",
6
+ "integrity",
7
+ "dependency",
8
+ "evidence",
9
+ "risk-complexity",
10
+ "scope-boundary",
11
+ ];
12
+
13
+ const norm = (value) =>
14
+ String(value ?? "")
15
+ .trim()
16
+ .toLowerCase()
17
+ .replace(/^spec-/, "")
18
+ .replace(/-analysis$/, "");
19
+
20
+ function findRequest(instance) {
21
+ const items = instance.items?.operation_request ?? [];
22
+ return (
23
+ items.find((item) => item && item.interviewId === "request") ?? items[0]
24
+ );
25
+ }
26
+
27
+ // Hard check (final gate): every selected analysis must have a recorded
28
+ // `review_doc` (a rendered + quire-validated SpecReview doc on disk) before
29
+ // the run can be accepted. 'base' selects nothing, so it passes trivially;
30
+ // 'all' expands to the canonical six when the agent did not echo the list.
31
+ const selectedAnalysesCovered = ({ instance }) => {
32
+ const request = findRequest(instance);
33
+ const reviewSet = norm(request?.review_set);
34
+ let selected = Array.isArray(request?.selected_analyses)
35
+ ? request.selected_analyses.map(norm).filter(Boolean)
36
+ : [];
37
+ if (reviewSet === "all" && selected.length === 0) {
38
+ selected = [...ALL_ANALYSES];
39
+ }
40
+ if (selected.length === 0) return true;
41
+
42
+ const ran = new Set(
43
+ (instance.items?.review_doc ?? [])
44
+ .map((doc) => norm(doc?.analysis))
45
+ .filter(Boolean),
46
+ );
47
+ const missing = selected.filter((analysis) => !ran.has(analysis));
48
+ return (
49
+ missing.length === 0 || {
50
+ ok: false,
51
+ code: "selected_analyses_not_run",
52
+ details: { reviewSet, selected, missing },
53
+ }
54
+ );
55
+ };
56
+
57
+ export const invariants = {
58
+ ...specInvariants,
59
+ selected_analyses_covered: selectedAnalysesCovered,
60
+ };
@@ -0,0 +1,68 @@
1
+ name: review
2
+ version: 0.2.0
3
+ description: Run a composite specification review producing validated SpecReview docs.
4
+ initialPhase: intake
5
+ phases:
6
+ - { name: intake }
7
+ - { name: analyses_run }
8
+ - { name: reviews_rendered }
9
+ - { name: validated }
10
+ - { name: accepted, terminal: true }
11
+ transitions:
12
+ - from: intake
13
+ to: analyses_run
14
+ invariants:
15
+ - "interview.complete:request"
16
+ defaultGate: auto
17
+ - from: analyses_run
18
+ to: reviews_rendered
19
+ invariants: []
20
+ defaultGate: auto
21
+ - from: reviews_rendered
22
+ to: validated
23
+ invariants: []
24
+ defaultGate: auto
25
+ - from: validated
26
+ to: accepted
27
+ invariants:
28
+ - "selected_analyses_covered"
29
+ defaultGate: hitl
30
+ itemSchemas:
31
+ operation_request: {}
32
+ # One per analysis the agent ran + validated: a SpecReview doc on disk.
33
+ review_doc:
34
+ required: [analysis, path]
35
+ properties:
36
+ analysis: { type: string }
37
+ path: { type: string }
38
+ linkSchemas: {}
39
+ interviews:
40
+ request:
41
+ itemType: operation_request
42
+ completenessRule: all_required
43
+ questions:
44
+ - key: scope
45
+ prompt: "Spec paths, requirement ids, or graph scope to review."
46
+ type: text
47
+ required: true
48
+ - key: review_set
49
+ prompt: "Review set: 'base' (skill checklist only), 'all' (the six analyses), or 'subset'."
50
+ type: enum
51
+ options: [base, all, subset]
52
+ required: true
53
+ - key: selected_analyses
54
+ prompt: "Analyses to run as a list, drawn from: failure-domain, integrity, dependency, evidence, risk-complexity, scope-boundary. Use all six for 'all'; the chosen ones for 'subset'; leave empty for 'base'."
55
+ type: list<text>
56
+ required: false
57
+ recipes:
58
+ run-to-review:
59
+ description: Record inputs, then advance through analyses, rendering, validation, to acceptance.
60
+ steps:
61
+ - command: advance
62
+ to: analyses_run
63
+ - command: advance
64
+ to: reviews_rendered
65
+ - command: advance
66
+ to: validated
67
+ - command: advance
68
+ to: accepted
@@ -0,0 +1,77 @@
1
+ ---
2
+ name: spec-risk-complexity-analysis
3
+ description: Identify technical risks and volatility in requirements before tasking.
4
+ ---
5
+
6
+ # Risk & Complexity Analysis
7
+
8
+ Surface the requirements that are most likely to fail, slip, or churn — so they can be sliced smaller, prototyped first, or hedged with extra verification.
9
+
10
+ ## When to use
11
+
12
+ - After dependency, scope, and evidence analysis but before `spec-to-plan` decomposes tasks.
13
+ - After any major external change (new compliance regime, new SLA, new vendor).
14
+
15
+ ## Risk dimensions
16
+
17
+ Each FR/StR/NFR is scored on two independent axes.
18
+
19
+ ### Technical risk
20
+
21
+ Flag a requirement as **high risk** if it involves any of:
22
+
23
+ - **Novel technology** — first time this team or system uses it (new database engine, new protocol, new language runtime).
24
+ - **Concurrency / distributed coordination** — multi-writer state, consensus, leader election, exactly-once semantics.
25
+ - **Security or compliance constraint** — regulated data, cryptographic primitives, auth boundary changes.
26
+ - **Hard performance guarantee** — quantified latency/throughput/availability bounds (p99, RPO/RTO).
27
+
28
+ Otherwise medium (one of the above is tangentially involved) or low.
29
+
30
+ ### Volatility
31
+
32
+ Flag a requirement as **high volatility** if it is likely to change due to:
33
+
34
+ - **Policy evolution** — regulatory or org policy not yet stable.
35
+ - **External contracts** — depends on a third-party API we don't control.
36
+ - **Product discovery** — UX or business rules expected to shift as users are observed.
37
+
38
+ Otherwise medium or low.
39
+
40
+ ## Process
41
+
42
+ 1. **Score** every FR/StR/NFR on both axes.
43
+ 2. **Mitigate high-risk, low-volatility** items by spiking/prototyping early and adding contract/property tests.
44
+ 3. **Mitigate high-volatility** items by slicing into smaller iterative tasks and avoiding deep dependencies on them.
45
+ 4. **Cross-check failure domains** — see `spec-failure-domain-analysis` for extension, identity, purity, and topology gaps that *also* increase risk.
46
+ 5. **Produce the risk register** below.
47
+
48
+ ## Deliverable template
49
+
50
+ Record output in `spec/analysis/risk-register.md`.
51
+
52
+ ```markdown
53
+ # Risk Register
54
+
55
+ | Req | Tech Risk | Volatility | Drivers | Mitigation |
56
+ |-----|-----------|------------|---------|------------|
57
+ | FR-018 | High | Low | Distributed lock, exactly-once payout | Spike + property tests + contract test against ledger |
58
+ | FR-022 | Medium | High | UX flow under product discovery | Slice into 3 iterative tasks; avoid downstream coupling |
59
+ | NFR-005 | High | Low | p99 < 50ms across 100rps | Load test as quality gate; budget allocated in FR-018 |
60
+ | FR-030 | Low | High | Tax rules change quarterly | Move rule table behind config; ship update path |
61
+
62
+ ## Top hazards
63
+
64
+ 1. FR-018 — distributed exactly-once payout (see mitigation above).
65
+ 2. NFR-005 — perf budget owns FR-018's success; if perf fails, payout slips.
66
+
67
+ ## Failure-domain gaps
68
+
69
+ See `spec-failure-domain-analysis` deliverable. Open gaps: none / list FR IDs.
70
+ ```
71
+
72
+ ## Acceptance Criteria
73
+
74
+ - Every FR/StR/NFR has both axes scored (no blanks).
75
+ - Every High on either axis has a named mitigation.
76
+ - The "Top hazards" section names the 3–5 items the team should review live before plan generation.
77
+ - Cross-reference to `spec-failure-domain-analysis` deliverable is present and current.
@@ -0,0 +1,86 @@
1
+ ---
2
+ name: spec-scope-boundary-analysis
3
+ description: Define system boundaries and allocate responsibilities for ISO-style specifications.
4
+ ---
5
+
6
+ # Scope & Boundary Analysis
7
+
8
+ Define what the system owns, what it consumes from outside, and which component owns each requirement.
9
+
10
+ ## When to use
11
+
12
+ - Once the StR/FR set is stable but before tasking.
13
+ - When a new external dependency or component is introduced.
14
+ - During `spec-app-review` for application-type specs that span multiple components.
15
+
16
+ ## Process
17
+
18
+ 1. **System Boundary Definition.**
19
+ - Enumerate in-scope responsibilities (what this system guarantees).
20
+ - Enumerate external dependencies (what it consumes and trusts).
21
+ - For each dependency, mark whether its behavior is **assumed** (we don't verify it) or **guaranteed** (we verify via contract test).
22
+
23
+ 2. **Responsibility Allocation.** For each FR/StR/NFR, assign:
24
+ - An **owning component or subsystem**.
25
+ - A **responsibility class**:
26
+ - `core` — domain logic specific to this system.
27
+ - `infrastructure` — persistence, transport, scheduling, storage.
28
+ - `cross-cutting` — auth, logging, metrics, error handling, audit.
29
+
30
+ This step defines *where* work belongs, not *how* it is done.
31
+
32
+ 3. **Produce the deliverable** using the template below.
33
+
34
+ ## Deliverable template
35
+
36
+ Record output in `spec/analysis/scope-boundary.md`.
37
+
38
+ ```markdown
39
+ # Scope & Boundary Analysis
40
+
41
+ ## System Context
42
+
43
+ ​```mermaid
44
+ flowchart LR
45
+ user([User])
46
+ ext1[(External: Identity Provider)]
47
+ ext2[(External: Audit Log Sink)]
48
+ subgraph SUT [System Under Spec]
49
+ api[API Gateway]
50
+ core[Core Service]
51
+ db[(Postgres)]
52
+ end
53
+ user --> api --> core --> db
54
+ core -->|assumed| ext1
55
+ core -->|guaranteed via contract test| ext2
56
+ ​```
57
+
58
+ ## In-Scope Responsibilities
59
+
60
+ - Authenticate and authorize all inbound API requests.
61
+ - Persist domain entities X, Y, Z with the schema defined in FR-010..FR-012.
62
+ - Emit audit events on every state transition.
63
+
64
+ ## External Dependencies
65
+
66
+ | Dependency | Type | Assumed or Guaranteed | Contract |
67
+ |------------|------|------------------------|----------|
68
+ | Identity Provider | OIDC | Assumed | Provider's published spec |
69
+ | Audit Log Sink | HTTP | Guaranteed | IT-005 contract test |
70
+
71
+ ## Responsibility Allocation
72
+
73
+ | Requirement | Owning Component | Class |
74
+ |-------------|------------------|-------|
75
+ | FR-001 (auth middleware) | API Gateway | cross-cutting |
76
+ | FR-010 (user entity) | Core Service | core |
77
+ | FR-020 (postgres migration) | Core Service | infrastructure |
78
+ | NFR-003 (request log) | API Gateway | cross-cutting |
79
+ ```
80
+
81
+ ## Acceptance Criteria
82
+
83
+ - Every FR/StR/NFR is assigned exactly one owning component and one responsibility class.
84
+ - Every external dependency is marked `assumed` or `guaranteed` with a named contract.
85
+ - The system context diagram shows every external actor named in the spec.
86
+ - No "TBD" entries in the allocation table.
@@ -0,0 +1,84 @@
1
+ ---
2
+ name: spec-security-analysis
3
+ description: Analyze specifications and implementations to identify applicable security standards and generate compliance traceability documentation.
4
+ ---
5
+
6
+ # Security Compliance Analysis
7
+
8
+ Analyze a component's specification and implementation to generate comprehensive security compliance traceability. Apply ALL security standards for maximum coverage - overlapping controls strengthen rather than conflict.
9
+
10
+ ## Mandatory Standards
11
+
12
+ Apply ALL of these standards to EVERY analysis (scope varies by component function):
13
+
14
+ | Standard | Version | Scope |
15
+ |----------|---------|-------|
16
+ | AICPA SOC 2 | 2017 TSC | Trust Services Criteria |
17
+ | ISO/IEC 27001 | 2022 | Annex A Controls |
18
+ | NIST SP 800-53 | Rev 5.2.0 | Security & Privacy Controls |
19
+ | OWASP ASVS | 5.0.0 | Application Security Verification |
20
+ | EU GDPR | 2016/679 | Data Protection Articles |
21
+
22
+ ## Process
23
+
24
+ 1. **Gather Context**
25
+ - Read `spec/spec.md` (if exists)
26
+ - Scan implementation for security-relevant patterns (auth, data, API, logging)
27
+ - Identify component type and function
28
+
29
+ 2. **Identify Applicable Controls**
30
+ - Read [references/standards-index.md](references/standards-index.md) for standard selection
31
+ - Select relevant chapters from each standard's index:
32
+ - [soc2/index.md](references/soc2/index.md) → CC1-CC9 categories
33
+ - [iso27001/index.md](references/iso27001/index.md) → A5-A8 themes
34
+ - [nist-800-53/index.md](references/nist-800-53/index.md) → Control families
35
+ - [owasp-asvs/index.md](references/owasp-asvs/index.md) → V1-V14 areas
36
+ - [gdpr/index.md](references/gdpr/index.md) → Chapters II-V
37
+ - Use index decision guides to choose specific chapters to investigate
38
+ - Reference [component-type-mapping.md](references/component-type-mapping.md) for scope guidance
39
+ - **[REQUIRED]** Verify identified controls against official FREE sources:
40
+ - NIST 800-53: https://csrc.nist.gov/pubs/sp/800/53/r5/upd1/final (US Gov - fully open)
41
+ - OWASP ASVS: https://github.com/OWASP/ASVS (CC BY-SA 4.0 - fully open)
42
+ - GDPR: https://eur-lex.europa.eu/eli/reg/2016/679/oj (EU Law - fully open)
43
+ - SOC 2 TSC: https://en.wikipedia.org/wiki/SOC_2 (reference summary - no login)
44
+ - ISO 27001: https://en.wikipedia.org/wiki/ISO/IEC_27001 (control list - no login)
45
+ - Local references are summaries; use web search for specific control details
46
+
47
+ 3. **Map Controls to Requirements**
48
+ - Link each applicable control to existing FR/NFR/StR requirements
49
+ - Identify gaps where controls lack requirement coverage
50
+ - Document requirement-to-control bidirectional traceability
51
+
52
+ 4. **Define Scope Boundaries**
53
+ - Identify controls outside component scope
54
+ - Assign responsible component for out-of-scope controls
55
+ - Document explicitly what is NOT covered and why
56
+
57
+ 5. **Generate Output**
58
+ - Use template: [assets/security-analysis-template.md](assets/security-analysis-template.md)
59
+ - Output as Section 19 "Compliance Standards Traceability" in `spec/spec.md`
60
+ - Example: [assets/security-analysis-example.md](assets/security-analysis-example.md)
61
+
62
+ ## Output Sections
63
+
64
+ - **19.1 Targeted Standards**: All 5 mandatory standards with version and scope
65
+ - **19.2 Control Mapping**: Control ID → Standard → Name → Component Requirement
66
+ - **19.3 GDPR Compliance**: Specific GDPR article coverage
67
+ - **19.4 Audit Support Controls**: Cross-standard audit and logging controls
68
+ - **19.5 Out of Scope**: Controls outside component boundary with responsible component
69
+
70
+ ## Rules
71
+
72
+ - Apply ALL standards - comprehensive coverage trumps minimal compliance
73
+ - Every control mapping MUST reference specific FR/NFR/StR identifiers
74
+ - Overlapping controls from multiple standards reinforce coverage
75
+ - Out-of-scope controls MUST identify the responsible component
76
+ - Gap identification is required - missing control coverage is a finding
77
+
78
+ ## References
79
+
80
+ - Template: [assets/security-analysis-template.md](assets/security-analysis-template.md)
81
+ - Example: [assets/security-analysis-example.md](assets/security-analysis-example.md)
82
+ - Standards Index: [references/standards-index.md](references/standards-index.md)
83
+ - Component Mapping: [references/component-type-mapping.md](references/component-type-mapping.md)
84
+
@@ -0,0 +1,89 @@
1
+ # Example: py-permissions Security Compliance Traceability
2
+
3
+ This example shows the complete Section 19 from the py-permissions library specification.
4
+
5
+ ---
6
+
7
+ ## 19. Compliance Standards Traceability
8
+
9
+ This specification targets alignment with the following industry security and privacy standards.
10
+
11
+ ### 19.1 Targeted Standards
12
+
13
+ | Standard | Version | Scope | Region |
14
+ |----------|---------|-------|--------|
15
+ | AICPA SOC 2 | 2017 TSC | CC6 (Logical Access Controls) | Global |
16
+ | ISO/IEC 27001 | 2022 | Annex A.9 (Access Control) | Global |
17
+ | NIST SP 800-53 | Rev 5 | AC Family (Access Control) | US Federal |
18
+ | OWASP ASVS | 4.0 | V4 (Access Control Verification) | Global |
19
+ | EU GDPR | 2016/679 | Articles 25, 32 (Security of Processing) | EU/EEA |
20
+
21
+ ### 19.2 Control Mapping
22
+
23
+ | Control ID | Standard | Control Name | py-permissions Requirement |
24
+ |------------|----------|--------------|---------------------------|
25
+ | CC6.1 | SOC2 | Logical Access Security | FR-001, FR-002, FR-008, FR-009 |
26
+ | CC6.2 | SOC2 | User Registration/Authorization | FR-014 (Role Schema) |
27
+ | CC6.3 | SOC2 | Access Modification/Removal | FR-008 (RBAC), FR-014 |
28
+ | CC6.6 | SOC2 | Boundary Protection | FR-007 (Org Tenancy) |
29
+ | CC7.2 | SOC2 | Security Event Monitoring | FR-013 (Audit Logging) |
30
+ | A.9.1.1 | ISO 27001 | Access Control Policy | StR-001 |
31
+ | A.9.2.3 | ISO 27001 | Privileged Access Management | FR-008, FR-010 |
32
+ | A.9.2.5 | ISO 27001 | Review of User Access Rights | FR-015 (Permission Query) |
33
+ | A.9.4.1 | ISO 27001 | Information Access Restriction | FR-005, FR-003 |
34
+ | A.12.4.1 | ISO 27001 | Event Logging | FR-013 |
35
+ | AC-2 | NIST | Account Management | FR-014 |
36
+ | AC-3 | NIST | Access Enforcement | FR-001, FR-002 |
37
+ | AC-5 | NIST | Separation of Duties | FR-008 (RBAC) |
38
+ | AC-6 | NIST | Least Privilege | FR-005, FR-008 |
39
+ | AU-2 | NIST | Audit Events | FR-013 |
40
+ | 4.1.1 | ASVS | Access Control Model | FR-008, FR-009 |
41
+ | 4.2.1 | ASVS | Sensitive Data Access Control | FR-005, FR-007 |
42
+
43
+ ### 19.3 GDPR Compliance
44
+
45
+ | GDPR Article | Requirement | py-permissions Coverage |
46
+ |--------------|-------------|------------------------|
47
+ | Art. 25(1) | Data Protection by Design | FR-008 (RBAC), FR-009 (ABAC), NFR-002 (Fail-Safe) |
48
+ | Art. 25(2) | Data Protection by Default | FR-005 (Resource-Level), FR-003 (List Filtering) |
49
+ | Art. 32(1)(b) | Confidentiality/Integrity | FR-007 (Org Tenancy), FR-002 (Enforcement) |
50
+ | Art. 32(1)(d) | Regular Testing | NFR-001, NFR-003, NFR-004 (Verification) |
51
+ | Art. 32(4) | Authorized Processing Only | FR-001, FR-002, FR-013 (Audit) |
52
+
53
+ Key GDPR principles addressed:
54
+ - **Least Privilege**: FR-005, FR-008 enforce minimum necessary access
55
+ - **Access Logging**: FR-013 provides audit trail for Art. 30 records
56
+ - **Multi-Tenancy**: FR-007 ensures organization isolation (data controller boundaries)
57
+
58
+ ### 19.4 Audit Support Controls
59
+
60
+ | Control Requirement | Standard Reference | py-permissions Coverage |
61
+ |--------------------|-------------------|------------------------|
62
+ | Audit Logging | SOC2 CC7.2, ISO A.12.4, NIST AU-2 | FR-013 |
63
+ | Log Integrity | NIST AU-9 | FR-013-CON-2 |
64
+ | Fail-Safe Access | NIST AC-7, ISO A.9.4.2, GDPR Art. 32 | NFR-002 |
65
+ | Retention Compatibility | SOC2 CC7.3, ISO A.12.4.1, GDPR Art. 30 | NFR-005 |
66
+
67
+ ### 19.5 Out of Scope
68
+
69
+ The following controls are outside py-permissions scope:
70
+
71
+ | Control | Description | Responsible Component |
72
+ |---------|-------------|----------------------|
73
+ | CC6.4, CC6.5 | Physical Access/Asset Disposal | Infrastructure |
74
+ | A.9.2.1, A.9.2.2 | User Registration/Provisioning | Auth Service |
75
+ | AC-17, AC-18 | Remote/Wireless Access | Network Layer |
76
+ | GDPR Art. 17 | Right to Erasure | Data Service Layer |
77
+ | GDPR Art. 20 | Data Portability | Data Service Layer |
78
+
79
+ ---
80
+
81
+ ## Key Observations
82
+
83
+ This example demonstrates:
84
+
85
+ 1. **Comprehensive Coverage**: All 5 mandatory standards included with specific scopes
86
+ 2. **Bidirectional Traceability**: Each control maps to specific FR/NFR/StR identifiers
87
+ 3. **Overlapping Controls**: Multiple standards covering same area (e.g., Audit Logging) strengthens coverage
88
+ 4. **Clear Boundaries**: Out-of-scope controls explicitly assigned to responsible components
89
+ 5. **GDPR Principles**: Extracted and documented for EU compliance visibility
@@ -0,0 +1,73 @@
1
+ # Section 19: Compliance Standards Traceability Template
2
+
3
+ Use this template to generate the security compliance traceability section for `spec/spec.md`.
4
+
5
+ ---
6
+
7
+ ## 19. Compliance Standards Traceability
8
+
9
+ This specification targets alignment with the following industry security and privacy standards.
10
+
11
+ ### 19.1 Targeted Standards
12
+
13
+ | Standard | Version | Scope | Region |
14
+ |----------|---------|-------|--------|
15
+ | AICPA SOC 2 | 2017 TSC (2024 updates) | [Applicable CC categories] | Global |
16
+ | ISO/IEC 27001 | 2022 (2024 amendment) | [Applicable Annex A sections] | Global |
17
+ | NIST SP 800-53 | Rev 5.2.0 | [Applicable control families] | US Federal |
18
+ | OWASP ASVS | 5.0.0 | [Applicable verification areas] | Global |
19
+ | EU GDPR | 2016/679 (2024 amendments) | [Applicable articles] | EU/EEA |
20
+
21
+ ### 19.2 Control Mapping
22
+
23
+ | Control ID | Standard | Control Name | Component Requirement |
24
+ |------------|----------|--------------|----------------------|
25
+ | CC6.1 | SOC2 | Logical Access Security | [FR-XXX, FR-XXX] |
26
+ | A.9.X.X | ISO 27001 | [Control Name] | [FR-XXX] |
27
+ | AC-X | NIST | [Control Name] | [FR-XXX, NFR-XXX] |
28
+ | X.X.X | ASVS | [Verification Requirement] | [FR-XXX] |
29
+
30
+ > [!TIP]
31
+ > Group controls by functional area (Access Control, Audit, Data Protection, etc.) for readability.
32
+
33
+ ### 19.3 GDPR Compliance
34
+
35
+ | GDPR Article | Requirement | Component Coverage |
36
+ |--------------|-------------|-------------------|
37
+ | Art. 25(1) | Data Protection by Design | [FR-XXX, NFR-XXX] |
38
+ | Art. 25(2) | Data Protection by Default | [FR-XXX] |
39
+ | Art. 32(1)(b) | Confidentiality/Integrity | [FR-XXX] |
40
+ | Art. 32(1)(d) | Regular Testing | [NFR-XXX] |
41
+ | Art. 32(4) | Authorized Processing Only | [FR-XXX] |
42
+
43
+ Key GDPR principles addressed:
44
+ - **Least Privilege**: [Requirement references]
45
+ - **Access Logging**: [Requirement references]
46
+ - **[Additional principles as applicable]**
47
+
48
+ ### 19.4 Audit Support Controls
49
+
50
+ | Control Requirement | Standard Reference | Component Coverage |
51
+ |--------------------|-------------------|-------------------|
52
+ | Audit Logging | SOC2 CC7.2, ISO A.12.4, NIST AU-2 | [FR-XXX] |
53
+ | Log Integrity | NIST AU-9 | [FR-XXX-CON-X or N/A] |
54
+ | Fail-Safe Access | NIST AC-7, ISO A.9.4.2, GDPR Art. 32 | [NFR-XXX] |
55
+ | Retention Compatibility | SOC2 CC7.3, ISO A.12.4.1, GDPR Art. 30 | [NFR-XXX or N/A] |
56
+
57
+ ### 19.5 Out of Scope
58
+
59
+ The following controls are outside [Component Name] scope:
60
+
61
+ | Control | Description | Responsible Component |
62
+ |---------|-------------|----------------------|
63
+ | [Control ID] | [Brief description] | [Component/Service Name] |
64
+
65
+ > [!NOTE]
66
+ > The table above is component-specific. Identify controls that are NOT applicable to this component and assign to the responsible component. Common examples include:
67
+ > - CC6.4, CC6.5 (Physical Access) → Infrastructure
68
+ > - A.9.2.1, A.9.2.2 (User Provisioning) → Auth Service
69
+ > - AC-17, AC-18 (Remote/Wireless) → Network Layer
70
+ > - GDPR Art. 17, 20 (Erasure/Portability) → Data Service
71
+
72
+ > [!IMPORTANT]
73
+ > Every out-of-scope control MUST identify the responsible component. Unassigned controls indicate a coverage gap.