@agent-ix/quoin 0.2.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.
Files changed (124) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +122 -0
  3. package/bin/quoin.js +8 -0
  4. package/default-modules.yaml +82 -0
  5. package/dist/catalog.d.ts +32 -0
  6. package/dist/catalog.d.ts.map +1 -0
  7. package/dist/cli-ClS52_Fm.js +436 -0
  8. package/dist/cli.d.ts +3 -0
  9. package/dist/cli.d.ts.map +1 -0
  10. package/dist/cli.js +2 -0
  11. package/dist/flows.d.ts +7 -0
  12. package/dist/flows.d.ts.map +1 -0
  13. package/dist/index.d.ts +6 -0
  14. package/dist/index.d.ts.map +1 -0
  15. package/dist/index.js +2 -0
  16. package/dist/modules.d.ts +10 -0
  17. package/dist/modules.d.ts.map +1 -0
  18. package/dist/plugins.d.ts +13 -0
  19. package/dist/plugins.d.ts.map +1 -0
  20. package/dist/write.d.ts +22 -0
  21. package/dist/write.d.ts.map +1 -0
  22. package/package.json +85 -0
  23. package/plugin.json +6 -0
  24. package/skills/spec-app-review/SKILL.md +51 -0
  25. package/skills/spec-app-review/references/checklist.md +194 -0
  26. package/skills/spec-dependency-analysis/SKILL.md +75 -0
  27. package/skills/spec-evidence-analysis/SKILL.md +78 -0
  28. package/skills/spec-failure-domain-analysis/SKILL.md +44 -0
  29. package/skills/spec-ideation/SKILL.md +46 -0
  30. package/skills/spec-integrity-analysis/SKILL.md +47 -0
  31. package/skills/spec-matrix/SKILL.md +79 -0
  32. package/skills/spec-matrix/assets/test-cases/TC-001.md +35 -0
  33. package/skills/spec-matrix/assets/test-cases/TC-002.md +37 -0
  34. package/skills/spec-matrix/assets/test-cases/TC-006.md +50 -0
  35. package/skills/spec-matrix/assets/test-matrix-example.md +97 -0
  36. package/skills/spec-matrix/assets/test-matrix-template.md +117 -0
  37. package/skills/spec-matrix/workflow-assets/dist/index.d.ts +146 -0
  38. package/skills/spec-matrix/workflow-assets/dist/index.d.ts.map +1 -0
  39. package/skills/spec-matrix/workflow-assets/dist/index.js +7655 -0
  40. package/skills/spec-matrix/workflow-assets/dist/invariants.d.ts +6 -0
  41. package/skills/spec-matrix/workflow-assets/dist/invariants.d.ts.map +1 -0
  42. package/skills/spec-matrix/workflow-assets/skills/matrix/SKILL.md +35 -0
  43. package/skills/spec-matrix/workflow-assets/skills/matrix/scripts/invariants.js +1 -0
  44. package/skills/spec-matrix/workflow-assets/skills/matrix/templates/report/default.md +30 -0
  45. package/skills/spec-matrix/workflow-assets/skills/matrix/workflows/matrix/def.yaml +82 -0
  46. package/skills/spec-object-review/SKILL.md +125 -0
  47. package/skills/spec-object-review/references/object-type-guide.md +113 -0
  48. package/skills/spec-review/SKILL.md +41 -0
  49. package/skills/spec-review/references/checklist.md +50 -0
  50. package/skills/spec-review/workflow-assets/dist/index.d.ts +146 -0
  51. package/skills/spec-review/workflow-assets/dist/index.d.ts.map +1 -0
  52. package/skills/spec-review/workflow-assets/dist/index.js +7655 -0
  53. package/skills/spec-review/workflow-assets/dist/invariants.d.ts +6 -0
  54. package/skills/spec-review/workflow-assets/dist/invariants.d.ts.map +1 -0
  55. package/skills/spec-review/workflow-assets/skills/review/SKILL.md +35 -0
  56. package/skills/spec-review/workflow-assets/skills/review/scripts/invariants.js +1 -0
  57. package/skills/spec-review/workflow-assets/skills/review/templates/report/default.md +30 -0
  58. package/skills/spec-review/workflow-assets/skills/review/workflows/review/def.yaml +82 -0
  59. package/skills/spec-risk-complexity-analysis/SKILL.md +77 -0
  60. package/skills/spec-scope-boundary-analysis/SKILL.md +86 -0
  61. package/skills/spec-security-analysis/SKILL.md +84 -0
  62. package/skills/spec-security-analysis/assets/security-analysis-example.md +89 -0
  63. package/skills/spec-security-analysis/assets/security-analysis-template.md +73 -0
  64. package/skills/spec-security-analysis/references/component-type-mapping.md +161 -0
  65. package/skills/spec-security-analysis/references/gdpr/ChII-Principles.md +58 -0
  66. package/skills/spec-security-analysis/references/gdpr/ChIII-DataSubjectRights.md +84 -0
  67. package/skills/spec-security-analysis/references/gdpr/ChIV-ControllerProcessor.md +83 -0
  68. package/skills/spec-security-analysis/references/gdpr/ChV-DataTransfers.md +62 -0
  69. package/skills/spec-security-analysis/references/gdpr/index.md +54 -0
  70. package/skills/spec-security-analysis/references/iso27001/A5-OrganizationalControls.md +64 -0
  71. package/skills/spec-security-analysis/references/iso27001/A6-PeopleControls.md +30 -0
  72. package/skills/spec-security-analysis/references/iso27001/A7-PhysicalControls.md +35 -0
  73. package/skills/spec-security-analysis/references/iso27001/A8-TechnologicalControls.md +66 -0
  74. package/skills/spec-security-analysis/references/iso27001/index.md +43 -0
  75. package/skills/spec-security-analysis/references/nist-800-53/AC-AccessControl.md +57 -0
  76. package/skills/spec-security-analysis/references/nist-800-53/AU-AuditAccountability.md +49 -0
  77. package/skills/spec-security-analysis/references/nist-800-53/CM-ConfigurationManagement.md +36 -0
  78. package/skills/spec-security-analysis/references/nist-800-53/IA-IdentificationAuthentication.md +44 -0
  79. package/skills/spec-security-analysis/references/nist-800-53/SA-SystemServicesAcquisition.md +50 -0
  80. package/skills/spec-security-analysis/references/nist-800-53/SC-SystemCommunications.md +53 -0
  81. package/skills/spec-security-analysis/references/nist-800-53/SI-SystemInformationIntegrity.md +52 -0
  82. package/skills/spec-security-analysis/references/nist-800-53/index.md +58 -0
  83. package/skills/spec-security-analysis/references/owasp-asvs/V1-Architecture.md +33 -0
  84. package/skills/spec-security-analysis/references/owasp-asvs/V10-MaliciousCode.md +33 -0
  85. package/skills/spec-security-analysis/references/owasp-asvs/V11-BusinessLogic.md +32 -0
  86. package/skills/spec-security-analysis/references/owasp-asvs/V12-Files.md +34 -0
  87. package/skills/spec-security-analysis/references/owasp-asvs/V13-API.md +34 -0
  88. package/skills/spec-security-analysis/references/owasp-asvs/V14-Configuration.md +35 -0
  89. package/skills/spec-security-analysis/references/owasp-asvs/V2-Authentication.md +36 -0
  90. package/skills/spec-security-analysis/references/owasp-asvs/V3-SessionManagement.md +35 -0
  91. package/skills/spec-security-analysis/references/owasp-asvs/V4-AccessControl.md +39 -0
  92. package/skills/spec-security-analysis/references/owasp-asvs/V5-Validation.md +37 -0
  93. package/skills/spec-security-analysis/references/owasp-asvs/V6-Cryptography.md +34 -0
  94. package/skills/spec-security-analysis/references/owasp-asvs/V7-ErrorLogging.md +37 -0
  95. package/skills/spec-security-analysis/references/owasp-asvs/V8-DataProtection.md +34 -0
  96. package/skills/spec-security-analysis/references/owasp-asvs/V9-Communication.md +32 -0
  97. package/skills/spec-security-analysis/references/owasp-asvs/index.md +59 -0
  98. package/skills/spec-security-analysis/references/soc2/CC1-ControlEnvironment.md +31 -0
  99. package/skills/spec-security-analysis/references/soc2/CC2-CommunicationInformation.md +27 -0
  100. package/skills/spec-security-analysis/references/soc2/CC3-RiskAssessment.md +29 -0
  101. package/skills/spec-security-analysis/references/soc2/CC4-MonitoringActivities.md +27 -0
  102. package/skills/spec-security-analysis/references/soc2/CC5-ControlActivities.md +28 -0
  103. package/skills/spec-security-analysis/references/soc2/CC6-LogicalPhysicalAccess.md +45 -0
  104. package/skills/spec-security-analysis/references/soc2/CC7-SystemOperations.md +42 -0
  105. package/skills/spec-security-analysis/references/soc2/CC8-ChangeManagement.md +32 -0
  106. package/skills/spec-security-analysis/references/soc2/CC9-RiskMitigation.md +34 -0
  107. package/skills/spec-security-analysis/references/soc2/index.md +46 -0
  108. package/skills/spec-security-analysis/references/standards-index.md +46 -0
  109. package/skills/spec-to-plan/SKILL.md +44 -0
  110. package/skills/spec-to-plan/references/step-1-analysis.md +58 -0
  111. package/skills/spec-to-plan/references/step-2-test-plan.md +37 -0
  112. package/skills/spec-to-plan/references/step-3-execution-plan.md +178 -0
  113. package/skills/spec-to-plan/workflow-assets/dist/index.d.ts +146 -0
  114. package/skills/spec-to-plan/workflow-assets/dist/index.d.ts.map +1 -0
  115. package/skills/spec-to-plan/workflow-assets/dist/index.js +7655 -0
  116. package/skills/spec-to-plan/workflow-assets/dist/invariants.d.ts +6 -0
  117. package/skills/spec-to-plan/workflow-assets/dist/invariants.d.ts.map +1 -0
  118. package/skills/spec-to-plan/workflow-assets/skills/to-plan/SKILL.md +35 -0
  119. package/skills/spec-to-plan/workflow-assets/skills/to-plan/scripts/invariants.js +1 -0
  120. package/skills/spec-to-plan/workflow-assets/skills/to-plan/templates/implementation-plan/default.md +43 -0
  121. package/skills/spec-to-plan/workflow-assets/skills/to-plan/workflows/to-plan/def.yaml +82 -0
  122. package/skills/specify/SKILL.md +69 -0
  123. package/skills/specify/assets/app-spec-template.md +143 -0
  124. package/skills/specify/assets/spec-template.md +299 -0
@@ -0,0 +1,51 @@
1
+ ---
2
+ name: spec-app-review
3
+ description: Review an application-type spec for completeness against UI rendering requirements and golden-path structure.
4
+ ---
5
+
6
+ # Review Application Specification
7
+
8
+ Validate a `component_type: application` spec against what the spec-editor-ui **actually renders** and the structural requirements from `specify`.
9
+
10
+ ## When to Use
11
+
12
+ - After creating or updating an application spec
13
+ - Before submitting a spec for formal review
14
+ - When debugging why sections appear empty in the spec-editor-ui Application Detail view
15
+
16
+ ## Process
17
+
18
+ 1. **Locate spec**: Read `spec/spec.md` in the target repo. Verify `component_type: application` in frontmatter.
19
+ 2. **Run checklist**: Evaluate every item in [references/checklist.md](references/checklist.md).
20
+ 3. **Report findings**: Group issues by severity (FAIL = will break UI, WARN = degraded display, INFO = quality improvement).
21
+ 4. **Fix or flag**: If instructed to fix, apply corrections. Otherwise, output the report.
22
+
23
+ ## Quick Reference
24
+
25
+ The spec-editor-ui `ApplicationDetailPage` has 7 tabs. Each tab extracts data from specific sections/artifacts:
26
+
27
+ | Tab | Data Source |
28
+ |-----|------------|
29
+ | Overview | Purpose, In Scope, Out of Scope, Operational Boundaries, API Endpoints, Components (catalog), Standards (frontmatter) |
30
+ | Architecture | Mermaid diagrams (tagged `logical`/`deployment`), FR diagrams, Aggregated Objects (catalog) |
31
+ | Integration | Artifacts with `tags: [integration]` in frontmatter |
32
+ | Security | Trust Boundaries table, artifacts with `tags: [security]`, Standards |
33
+ | Requirements | StR/US/FR/NFR tables parsed from spec.md |
34
+ | Decisions | ADR artifacts (`type: ADR`) or inline ADR sections |
35
+ | Spec | Raw markdown rendering |
36
+
37
+ ## Key Parsing Rules (Quire Library)
38
+
39
+ These are the **exact** parser behaviors that determine whether content renders:
40
+
41
+ - **Out of Scope**: `parseDelegations()` only recognizes `(Handled by X)` or `(Delegated to X)` patterns. Other parentheticals won't extract delegation targets.
42
+ - **In Scope**: `parseBulletList()` default pattern is `bold-description` (`**Title** — Description`). Plain bullets fall back to title-only.
43
+ - **Operational Boundaries**: `parseBulletList({ pattern: 'bold-colon' })` requires `**Name**: detail` format.
44
+ - **Trust Boundaries**: `parseTable()` on section "Trust Boundaries" — expects 3 columns: Role, Capabilities, Restrictions.
45
+ - **Mermaid tags**: `findDiagramByTag()` matches `%% @type: logical` and `%% @type: deployment` comments in mermaid blocks.
46
+ - **Integration tab**: Filters artifacts by `tags: [integration]` in YAML frontmatter (case-insensitive).
47
+ - **Security tab**: Filters artifacts by `tags: [security]` in YAML frontmatter.
48
+
49
+ ## Golden Reference
50
+
51
+ Use a known well-formed application spec in your org as a comparison reference when reviewing.
@@ -0,0 +1,194 @@
1
+ # Application Spec Review Checklist
2
+
3
+ Evaluate each item. Report as FAIL (breaks UI), WARN (degraded display), or INFO (quality).
4
+
5
+ ---
6
+
7
+ ## 1. Frontmatter (spec.md)
8
+
9
+ - [ ] `type: master-requirements` is set
10
+ - [ ] `component_type: application` is set
11
+ - [ ] `name` matches repo name
12
+ - [ ] `org: <your-org>` is set
13
+ - [ ] `depends_on` lists all component repos
14
+ - [ ] `standards_alignment` includes at least `iso-iec-ieee-29148`
15
+ - [ ] `tags` is a non-empty array (renders in MasterRequirementsViewer)
16
+ - [ ] `security_critical` is set (boolean)
17
+
18
+ **Severity**: FAIL if `type` or `component_type` wrong (UI won't route to app view). WARN for missing tags.
19
+
20
+ ---
21
+
22
+ ## 2. Required Sections (spec.md)
23
+
24
+ The `parseSpec()` function in `ApplicationDetailPage.tsx` extracts these by heading name. Section names must match exactly (case-insensitive heading search via Quire `section()`).
25
+
26
+ ### 2.1 Purpose
27
+ - [ ] Section titled `Purpose` exists
28
+ - [ ] Contains 2-3 sentences describing what the app solves
29
+
30
+ **Severity**: WARN if missing (falls back to `repo.description`)
31
+
32
+ ### 2.2 Scope Boundaries
33
+ - [ ] Section titled `Scope Boundaries` exists
34
+
35
+ **Severity**: WARN (card hidden if missing)
36
+
37
+ ### 2.3 In Scope
38
+ - [ ] Subsection titled `In Scope` exists
39
+ - [ ] Content is a bullet list (`- Item`)
40
+ - [ ] For rich display: use `**Title** — Description` format per bullet
41
+
42
+ **Severity**: WARN (shows "Not defined in spec")
43
+
44
+ ### 2.4 Out of Scope
45
+ - [ ] Subsection titled `Out of Scope` exists
46
+ - [ ] Each bullet uses `(Handled by X)` or `(Delegated to X)` parenthetical
47
+ - [ ] Do NOT use `(deferred to ...)`, `(future work)`, or other patterns — `parseDelegations()` regex: `/\((?:handled by|delegated to)\s+(.+?)\)/i`
48
+
49
+ **Severity**: WARN if section missing. INFO if delegation format wrong (items render but without arrow delegation labels).
50
+
51
+ ### 2.5 Operational Boundaries
52
+ - [ ] Subsection titled `Operational Boundaries` exists
53
+ - [ ] Each bullet uses `**Name**: description` format (bold-colon pattern)
54
+
55
+ **Severity**: WARN (shows "Not defined" in Design Principles card)
56
+
57
+ ### 2.6 Architecture Rationale
58
+ - [ ] Section titled `Architecture Rationale` exists
59
+ - [ ] Contains at least ADR-001
60
+
61
+ **Severity**: WARN (Decisions tab empty)
62
+
63
+ ---
64
+
65
+ ## 3. Mermaid Diagrams
66
+
67
+ ### 3.1 Logical View
68
+ - [ ] At least one mermaid code block exists in spec.md
69
+ - [ ] The primary dependency graph has `%% @type: logical` comment on line 1 (inside the fence)
70
+ - [ ] Falls back to first diagram if no tag — but tag is recommended
71
+
72
+ **Severity**: WARN (Architecture tab shows no logical view)
73
+
74
+ ### 3.2 Deployment View
75
+ - [ ] A second mermaid code block with `%% @type: deployment` exists
76
+ - [ ] Shows namespace, pods, ingress, secrets, databases
77
+
78
+ **Severity**: WARN (Architecture tab deployment toggle hidden)
79
+
80
+ ---
81
+
82
+ ## 4. Requirement Tables (spec.md)
83
+
84
+ These tables are parsed by `parseTable()` on the section content. Column order matters (positional extraction).
85
+
86
+ ### 4.1 Stakeholder Requirements
87
+ - [ ] Section `Stakeholder Requirements` exists with table
88
+ - [ ] Table columns: `ID | Title | Artifact`
89
+ - [ ] At least 1 StR row
90
+
91
+ ### 4.2 User Stories
92
+ - [ ] Section `User Stories` exists with table
93
+ - [ ] Table columns: `ID | Title | Role | Artifact`
94
+ - [ ] Multiple US covering different roles
95
+
96
+ ### 4.3 Functional Requirements
97
+ - [ ] Section `Functional Requirements` exists with table
98
+ - [ ] Table columns: `ID | Title | Object Type | Artifact`
99
+ - [ ] Required object types present:
100
+ - [ ] `domain` (FR-001: bounded context + ER diagram)
101
+ - [ ] `process` (at least 1 cross-service workflow)
102
+ - [ ] `configuration` (shared config across services)
103
+ - [ ] `integration` (consumer contract)
104
+
105
+ ### 4.4 Non-Functional Requirements
106
+ - [ ] Section `Non-Functional Requirements` exists with table
107
+ - [ ] Table columns: `ID | Title | Artifact`
108
+ - [ ] Required NFRs:
109
+ - [ ] Security Constraints (NFR-001)
110
+ - [ ] System Reliability (NFR-002)
111
+ - [ ] Deployment Topology (NFR-003)
112
+
113
+ **Severity**: FAIL if tables missing (Requirements tab empty). WARN if required object types absent.
114
+
115
+ ---
116
+
117
+ ## 5. Security Model (spec.md)
118
+
119
+ ### 5.1 Trust Boundaries
120
+ - [ ] Section titled `Trust Boundaries` exists (under Security Model)
121
+ - [ ] Contains a table with 3 columns: Role | Capabilities | Restrictions
122
+ - [ ] Includes at minimum: anonymous, user, admin, operator roles
123
+
124
+ **Severity**: WARN (Security tab shows "No security trust boundaries defined")
125
+
126
+ ---
127
+
128
+ ## 6. Artifact Frontmatter Tags
129
+
130
+ The Integration and Security tabs discover artifacts via `tags` in individual artifact YAML frontmatter, not from spec.md.
131
+
132
+ ### 6.1 Integration Artifacts
133
+ - [ ] FR with `object: integration` also has `tags: [integration]` in frontmatter
134
+ - [ ] Without this tag, Integration tab shows "No integration contracts found"
135
+
136
+ ### 6.2 Security Artifacts
137
+ - [ ] NFR-001 (Security) has `tags: [security]` in frontmatter
138
+ - [ ] Without this tag, Security tab falls back to parsed NFR table only (no full content rendering)
139
+
140
+ **Severity**: WARN (tabs show empty/fallback states)
141
+
142
+ ---
143
+
144
+ ## 7. Individual Artifact Quality
145
+
146
+ For each artifact file (StR, US, FR, NFR):
147
+
148
+ ### 7.1 Frontmatter
149
+ - [ ] `id` matches filename pattern (e.g., `FR-001`)
150
+ - [ ] `title` is present and descriptive
151
+ - [ ] `type` matches the directory (StR, US, FR, NFR)
152
+
153
+ ### 7.2 Heading
154
+ - [ ] H1 follows pattern: `# [ID] Title`
155
+ - [ ] ID in brackets matches frontmatter `id`
156
+
157
+ ### 7.3 Acceptance Criteria (FR, NFR)
158
+ - [ ] AC table exists with columns: `ID | Criteria | Verification Method`
159
+ - [ ] AC IDs follow pattern: `{artifact-id}-AC-{n}` (e.g., `FR-001-AC-1`)
160
+
161
+ ### 7.4 Constraints (FR, NFR)
162
+ - [ ] Constraint table with columns: `ID | Constraint | Type | Rationale | Validation`
163
+ - [ ] Constraint IDs follow pattern: `{artifact-id}-CON-{n}`
164
+
165
+ ### 7.5 Traceability
166
+ - [ ] `From:` and `Drives:` links present (or Traceability table)
167
+ - [ ] References are bidirectional (if FR-001 drives FR-002, FR-002 traces from FR-001)
168
+
169
+ ### 7.6 User Stories
170
+ - [ ] AC use H3 headings with IDs: `### US-001-AC-1: Title`
171
+ - [ ] `From:` traces to StR, `Drives:` traces to FR
172
+
173
+ **Severity**: INFO for most. WARN if AC IDs missing (test matrix can't trace).
174
+
175
+ ---
176
+
177
+ ## 8. Test Matrix (tests.md)
178
+
179
+ - [ ] File `spec/tests.md` exists
180
+ - [ ] Coverage table maps every AC to at least one TC
181
+ - [ ] TC entries include Type (Unit/Integration/E2E/Security) and Priority
182
+ - [ ] Component ownership note explains which repo runs each TC
183
+ - [ ] Constraint boundary tests section maps CON IDs to TCs
184
+
185
+ **Severity**: WARN if missing (no test traceability)
186
+
187
+ ---
188
+
189
+ ## 9. Cross-Reference Integrity
190
+
191
+ - [ ] Every artifact linked in spec.md tables exists as a file
192
+ - [ ] Every `From:` / `Drives:` reference resolves to a real artifact ID
193
+ - [ ] `depends_on` in frontmatter matches Component Registry table
194
+ - [ ] FR relationship targets (e.g., `ix://<your-org>/...`) use valid repo names
@@ -0,0 +1,75 @@
1
+ ---
2
+ name: spec-dependency-analysis
3
+ description: Analyze dependencies and separate enablement from feature work.
4
+ ---
5
+
6
+ # Dependency & Ordering Analysis
7
+
8
+ Identify prerequisite relationships between requirements so work can be sequenced. The deliverable is a directed acyclic graph (DAG) of FRs/StRs/NFRs in **logical order**, not a schedule.
9
+
10
+ ## When to use
11
+
12
+ - Before `spec-to-plan` — `spec-to-plan` consumes the DAG.
13
+ - After all FRs have been written and reviewed.
14
+ - Whenever new FRs are added that may unblock or block existing work.
15
+
16
+ ## Process
17
+
18
+ 1. **Identify prerequisite edges.** For each FR/StR/NFR, list every other requirement that MUST be satisfied before this one can be implemented. Express each as `A → B` (A is prerequisite to B).
19
+
20
+ 2. **Classify each requirement.**
21
+ - **Enablement** — frameworks, abstractions, scaffolding, schema/migration, shared libs. Has no business-visible behavior on its own.
22
+ - **Feature** — business or user-visible behavior.
23
+
24
+ **Rule**: Enablement requirements MUST be tasked before any feature that depends on them.
25
+
26
+ 3. **Verify acyclicity.** If any cycle is found, the spec is malformed — break the cycle by introducing a separation FR or merging the cyclic requirements.
27
+
28
+ 4. **Produce the deliverable.** Use the template below.
29
+
30
+ ## Deliverable template
31
+
32
+ Record output in `spec/analysis/dependency.md` (or as a section in `spec/spec.md` § 7 if your project keeps analysis inline).
33
+
34
+ ```markdown
35
+ # Dependency Analysis
36
+
37
+ ## Classification
38
+
39
+ | Requirement | Class | Rationale |
40
+ |-------------|-------|-----------|
41
+ | FR-001 | Enablement | Defines the auth middleware all feature FRs use |
42
+ | FR-002 | Enablement | Database schema for user records |
43
+ | FR-003 | Feature | Login flow — depends on FR-001, FR-002 |
44
+ | FR-004 | Feature | Password reset — depends on FR-001, FR-002 |
45
+
46
+ ## Dependency Graph
47
+
48
+ ​```mermaid
49
+ graph TD
50
+ FR-001[FR-001: Auth middleware]
51
+ FR-002[FR-002: User schema]
52
+ FR-003[FR-003: Login flow]
53
+ FR-004[FR-004: Password reset]
54
+ FR-001 --> FR-003
55
+ FR-002 --> FR-003
56
+ FR-001 --> FR-004
57
+ FR-002 --> FR-004
58
+ ​```
59
+
60
+ ## Topological Order (suggested implementation sequence)
61
+
62
+ 1. FR-001, FR-002 (enablement, parallelizable)
63
+ 2. FR-003, FR-004 (features, parallelizable after enablement)
64
+
65
+ ## Cycles
66
+
67
+ None detected.
68
+ ```
69
+
70
+ ## Acceptance Criteria
71
+
72
+ - Every FR/StR/NFR appears in the classification table exactly once.
73
+ - Every edge in the graph corresponds to an explicit prerequisite — no "soft" dependencies.
74
+ - No cycles.
75
+ - Topological order respects: all enablement before any feature that depends on it.
@@ -0,0 +1,78 @@
1
+ ---
2
+ name: spec-evidence-analysis
3
+ description: Define verification methods and evidence artifacts for requirements.
4
+ ---
5
+
6
+ # Verification & Evidence Strategy
7
+
8
+ Make sure every requirement has a defined verification method and a concrete artifact that proves it was verified.
9
+
10
+ ## When to use
11
+
12
+ - After requirements are written but before `spec-matrix` builds the test matrix.
13
+ - During `spec-review` when "how do we know this is satisfied?" is unclear.
14
+ - Whenever a new NFR is added (NFRs are most prone to missing evidence).
15
+
16
+ ## Verification methods (ISO/IEC/IEEE 29148)
17
+
18
+ | Method | Use when |
19
+ |--------|----------|
20
+ | `test` | The requirement is exercisable by automated or manual test execution. Default. |
21
+ | `analysis` | The requirement is proven by calculation, modeling, or static reasoning (e.g. complexity bound, cryptographic argument). |
22
+ | `inspection` | The requirement is satisfied by visual or structural review of the artifact (e.g. license headers, doc presence). |
23
+ | `demonstration` | The requirement is satisfied by observing operation in a realistic environment without instrumentation (e.g. UX flow walkthrough). |
24
+
25
+ ## Evidence artifacts
26
+
27
+ | Artifact | Pairs with |
28
+ |----------|------------|
29
+ | `test_case` | `test` — points to a TC-XXX file or test path |
30
+ | `analysis_report` | `analysis` — points to a doc/notebook |
31
+ | `inspection_checklist` | `inspection` — points to a checklist file |
32
+ | `demo_recording` | `demonstration` — points to a recording or scripted walkthrough |
33
+ | `metric` | any — observability metric that proves runtime behavior |
34
+ | `log` | any — log event proving the path executed |
35
+
36
+ **Rule**: Every implementation task MUST cite at least one evidence artifact. A task with no evidence is unfinishable.
37
+
38
+ ## Process
39
+
40
+ 1. **Tag every FR/StR/NFR** with `verification_method` and `evidence` fields in its frontmatter.
41
+ 2. **Resolve "test" defaults**: if an FR is tagged `test`, the matching test case must already exist or be queued in `spec-matrix`.
42
+ 3. **Resolve non-test methods**: for `analysis`/`inspection`/`demonstration`, name the artifact path explicitly. No "TBD".
43
+
44
+ ## Deliverable template
45
+
46
+ Per-requirement frontmatter (add to existing FR/StR/NFR files):
47
+
48
+ ```yaml
49
+ verification_method: test # test | analysis | inspection | demonstration
50
+ evidence:
51
+ - kind: test_case
52
+ ref: tests/integration/test_login.py::test_invalid_credentials
53
+ - kind: metric
54
+ ref: auth_failure_total
55
+ ```
56
+
57
+ Summary deliverable in `spec/analysis/evidence.md`:
58
+
59
+ ```markdown
60
+ # Verification & Evidence Summary
61
+
62
+ | Req | Method | Artifact |
63
+ |-----|--------|----------|
64
+ | FR-003 | test | tests/integration/test_login.py::test_login_happy_path |
65
+ | FR-010 | analysis | docs/analysis/storage-bound.md |
66
+ | NFR-002 | demonstration | docs/demos/uptime-walkthrough.md |
67
+ | NFR-005 | test + metric | tests/perf/test_p99_latency.py, metric `http_request_duration_seconds` |
68
+
69
+ ## Open gaps
70
+
71
+ None.
72
+ ```
73
+
74
+ ## Acceptance Criteria
75
+
76
+ - Every FR/StR/NFR has both `verification_method` and at least one `evidence` entry.
77
+ - No `evidence: TBD`, no missing refs.
78
+ - The summary table has zero open gaps before `spec-to-plan` is invoked.
@@ -0,0 +1,44 @@
1
+ ---
2
+ name: spec-failure-domain-analysis
3
+ description: Identify unstated failure modes, identity confusion, purity gaps, and topological edge cases in ISO-style specifications.
4
+ ---
5
+
6
+ # Spec Failure Domain Analysis
7
+
8
+ Run this skill during spec review to catch common omissions before implementation.
9
+
10
+ ## When to Use
11
+ - After drafting FR/NFR/StR requirements
12
+ - Before `spec-to-plan` (part of its readiness gate)
13
+ - During peer review of specifications
14
+
15
+ ## Checklist
16
+
17
+ ### 1. Extension Points (Trust Boundaries)
18
+ For each callback, hook, observer, or plugin interface:
19
+ - [ ] Is failure behavior defined? Options:
20
+ - **Strict**: Failure aborts operation (data integrity)
21
+ - **Resilient**: Failure is logged/suppressed (availability)
22
+ - **Configurable**: User chooses policy
23
+
24
+ ### 2. Entity Identity
25
+ For each core domain entity (State, Event, User, etc.):
26
+ - [ ] Is the uniqueness key explicit?
27
+ - Bad: "A set of states"
28
+ - Good: "States unique by `name` property"
29
+
30
+ ### 3. Evaluation Purity
31
+ For each user-supplied logic (guards, filters, validators):
32
+ - [ ] Are side-effects constrained?
33
+ - Document if read-only is required for simulation/reasoning
34
+
35
+ ### 4. Topological Robustness
36
+ For each graph/tree algorithm (search, path-finding):
37
+ - [ ] Is termination guaranteed on cycles?
38
+ - [ ] Are worst-case structures considered? (deep nesting, disconnected nodes)
39
+
40
+ ## Output
41
+ Document any missing constraints as proposed additions:
42
+ - **NFR**: Non-functional (resilience, performance)
43
+ - **StR**: Structural (integrity, purity)
44
+ - **FR**: Functional (if behavior is undefined)
@@ -0,0 +1,46 @@
1
+ ---
2
+ name: spec-ideation
3
+ description: Use for loose, exploratory specification drafting before formal authoring, review, matrix, or planning work.
4
+ ---
5
+
6
+ # Spec Ideation
7
+
8
+ ## Mode
9
+
10
+ This is a config-only skill. Do not create workflow state, call workflow
11
+ commands, or enforce phase gates while using it.
12
+
13
+ ## Framing Moves
14
+
15
+ - State the problem in concrete user-facing terms.
16
+ - Separate users, operators, and system actors.
17
+ - Draft candidate features as options, not commitments.
18
+ - Name non-goals early when they protect scope.
19
+ - Convert uncertainty into open questions instead of blocking progress.
20
+ - Define success criteria that can later become evidence targets.
21
+
22
+ ## Draft Outline
23
+
24
+ ```markdown
25
+ # Draft Spec
26
+
27
+ ## Problem
28
+
29
+ ## Users And Actors
30
+
31
+ ## Goals
32
+
33
+ ## Non-Goals
34
+
35
+ ## Candidate Features
36
+
37
+ ## Open Questions
38
+
39
+ ## Success Criteria
40
+ ```
41
+
42
+ ## Promotion Signal
43
+
44
+ Recommend promotion to `specify` when the draft has a clear problem, named
45
+ users or actors, scoped goals and non-goals, and at least one success criterion
46
+ that can be verified.
@@ -0,0 +1,47 @@
1
+ ---
2
+ name: spec-integrity-analysis
3
+ description: Perform quality gate analysis on ISO-style specifications to ensure completeness, consistency, and atomicity.
4
+ ---
5
+
6
+ # Specification Integrity Analysis
7
+
8
+ This skill performs a quality gate analysis on specifications (User Stories, FR/SR, StR, NFR) before task generation.
9
+
10
+ ## Process
11
+
12
+ 1. **Completeness Analysis**:
13
+ - Verify every User Story (US) maps to >= 1 Functional/System Requirement (FR/SR).
14
+ - Verify every FR/SR maps to >= 1 Stakeholder Requirement (StR).
15
+ - Verify every FR/SR maps to >= 1 verification method.
16
+ - Verify every NFR is explicitly scoped and referenced by affected FR/SR.
17
+ - **Deliverable**: Traceability matrix (US -> FR/SR -> StR -> Verification).
18
+
19
+ 2. **Consistency & Conflict Analysis**:
20
+ - Identify contradictory constraints (e.g., latency vs security).
21
+ - Identify duplicated requirements with different wording.
22
+ - Identify hidden assumptions embedded in prose.
23
+ - **Rule**: No requirement may have more than one valid interpretation.
24
+
25
+ ### Hidden Assumption Probes
26
+
27
+ For every FR, explicitly check for these patterns:
28
+
29
+ | Pattern | Probe Question |
30
+ |---------|---------------|
31
+ | FR delegates to an external CLI (git, gh, cookiecutter, etc.) | Is there an NFR declaring the tool's minimum version, detection method, and user-facing error when absent? |
32
+ | FR performs a lookup over multiple sources (registries, plugins, taps) | Is there an explicit tie-breaking policy when two sources return the same key? (first-wins, last-wins, error, merge — must be a stated decision) |
33
+ | FR calls an external API that returns paginated results | Does an NFR state whether full enumeration is required? If a cap is acceptable, is it documented as a known limitation? |
34
+ | FR calls an external API in a loop or concurrently | Does an NFR declare max concurrency, rate limit awareness, retry policy, and that errors must surface (not be silently swallowed)? |
35
+ | FR involves a scaffolding or generation command | Are both an interactive mode (human at terminal) and a scripted/CI mode explicitly specified with their flags? |
36
+ | FR calls an authenticated external API | Does an NFR declare the required auth scopes and mandate a clear user-facing error when scope is insufficient (not silent empty results)? |
37
+ | FR depends on a package or service not yet implemented | Is the interim fallback and eventual resolution chain documented? Is the hardcoded default traceable to a known stub? |
38
+
39
+ 3. **Atomicity & Testability Analysis**:
40
+ - Ensure each FR/SR/StR defines a *single* behavior/obligation.
41
+ - Ensure behavior is externally observable.
42
+ - Ensure behavior is verifiable by test, inspection, analysis, or demonstration.
43
+ - **Action**: Flag non-testable requirements for rewriting or splitting.
44
+
45
+ ## Failure Domain Check
46
+ Before finalizing, verify against `spec-failure-domain-analysis`:
47
+ - Extension failures, Identity keys, Evaluation purity, Topological robustness.
@@ -0,0 +1,79 @@
1
+ ---
2
+ name: spec-matrix
3
+ description: Build and maintain the requirements Test Matrix ensuring 100% coverage.
4
+ ---
5
+
6
+ # Build Test Matrix
7
+
8
+ Use this skill to create the requirements Test Matrix and ensure comprehensive coverage.
9
+
10
+ ## Rules (The Six Requirements)
11
+
12
+ 1. Coverage: Every Acceptance Criterion (AC) must have ≥1 Test Case (TC).
13
+ 2. Option Permutation: Test all valid option combinations.
14
+ 3. Constraint Boundary: Test min, max, below-min (fail), above-max (fail).
15
+ 4. Error Path: Test all documented error conditions.
16
+ 5. State Transition: Test all valid state transitions (if applicable).
17
+ 6. Edge Case: Identify and test extreme/unusual scenarios.
18
+
19
+ ## Process
20
+
21
+ 1. Initialize:
22
+ - Use template `assets/test-matrix-template.md`.
23
+ - Target: Correct location.
24
+ - Single Repo: `spec/tests.md`
25
+ - Multi-Repo: `specs/<category>/<component>/spec/tests.md`
26
+ 2. Traceability:
27
+ - Map `StR` -> `TC`.
28
+ - Map `US` -> `TC`.
29
+ - Map `FR` -> `TC`.
30
+ - Map `NFR` -> `TC`.
31
+ - Map `C` (Constraints) -> `TC`.
32
+ 3. Enumerate: List all Test Cases with ID, Title, Type, Priority, Status.
33
+ 4. Define Detailed TCs (Optional):
34
+ - For complex tests, create at:
35
+ - Single Repo: `spec/test-cases/TC-XXX.md`
36
+ - Multi-Repo: `specs/<category>/<component>/spec/test-cases/TC-XXX.md`
37
+ 5. Verify: Ensure all 6 rules are satisfied.
38
+ 6. Status: Mark as ✅ Complete only when all rules are met.
39
+
40
+ ## React Components (Conditional)
41
+
42
+ For React projects, add a Storybook Test Matrix section.
43
+
44
+ See `skills/review-react/SKILL.md` for:
45
+ - Story file requirements per component
46
+ - AC trace code format in story JSDoc
47
+ - Coverage matrix template (FR → AC → Story)
48
+
49
+ ## Integration Test Matrix (Conditional)
50
+
51
+ If ANY requirement specifies integration testing, include this section.
52
+
53
+ ### When Required
54
+
55
+ - FR/NFR annotation: `integration_test: true` or mentions integration verification
56
+ - Cross-project interactions (other services in your org)
57
+ - Interactions with local-provided services (Redis, Postgres, message bus)
58
+ - UI component browser testing (React → Storybook)
59
+
60
+ ### Section Contents
61
+
62
+ Use template section `## Integration Test Matrix` with:
63
+ 1. **Purpose column**: What integration is being tested
64
+ 2. **Target column**: External system/service/project
65
+ 3. **Type column**: `service` | `browser` | `event` | `database`
66
+ 4. **Test Cases**: Extensive functional coverage, not just smoke tests
67
+
68
+ ### Coverage Expectations
69
+
70
+ - Extensively test functionality (multiple scenarios per integration)
71
+ - Include happy path + error conditions + edge cases
72
+ - For browser tests: visual verification + interaction flows
73
+
74
+ ## Markers
75
+
76
+ - ✅ Complete
77
+ - ⚠️ Partial
78
+ - ❌ Missing
79
+ - 🚧 In Progress
@@ -0,0 +1,35 @@
1
+ # [TC-001] Clone Public GitHub Repository Successfully
2
+
3
+ ## Test Information
4
+ - **Type**: Integration
5
+ - **Traces To**: US-001-AC-1, FR-001-AC-1
6
+ - **Priority**: P0
7
+ - **Status**: ✅ Pass
8
+
9
+ ## Preconditions
10
+ - Public GitHub repository exists with valid Kubernetes configs
11
+ - Test data: `https://github.com/example/sample-k8s-project`
12
+
13
+ ## Test Steps
14
+ 1. Submit ingestion request with public repository URL
15
+ 2. Wait for ingestion to complete
16
+ 3. Query catalog for project components
17
+
18
+ ## Expected Result
19
+ Project is ingested with all components discovered
20
+
21
+ ## Verification
22
+ - **Options Tested**: FR-001-OPT-A (shallow clone)
23
+ - **Constraints Verified**: FR-001-CON-1 (size limit), FR-001-CON-3 (read-only)
24
+
25
+ ## Test Data
26
+ ```json
27
+ {
28
+ "repository_url": "https://github.com/example/sample-k8s-project",
29
+ "branch": "main"
30
+ }
31
+ ```
32
+
33
+ ## Notes
34
+ - Verifies basic public repository ingestion flow
35
+ - Tests the most common use case