@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,32 @@
1
+ # CC8 - Change Management
2
+
3
+ **Category**: Common Criteria
4
+ **Focus**: Authorization and control of changes
5
+
6
+ ## When to Apply
7
+
8
+ Apply CC8 when your component:
9
+ - Has code or configuration changes
10
+ - Impacts production systems
11
+ - Requires testing before deployment
12
+
13
+ ## Controls
14
+
15
+ | Control | Name | Description |
16
+ |---------|------|-------------|
17
+ | CC8.1 | Change Authorization | Entity authorizes, designs, develops, configures, documents, tests, approves, and implements changes |
18
+
19
+ ## Mapping Guidance
20
+
21
+ CC8.1 is comprehensive and maps to:
22
+ - **Code review requirements** → NFR-XXX
23
+ - **CI/CD pipeline** → NFR-XXX
24
+ - **Testing requirements** → NFR-XXX
25
+ - **Approval workflows** → Process documentation
26
+ - **Rollback capability** → NFR-XXX
27
+
28
+ For software components, CC8 is typically satisfied by:
29
+ - Git-based version control
30
+ - Pull request reviews
31
+ - Automated testing
32
+ - Deployment pipelines
@@ -0,0 +1,34 @@
1
+ # CC9 - Risk Mitigation
2
+
3
+ **Category**: Common Criteria
4
+ **Focus**: Risk mitigation and vendor management
5
+
6
+ ## When to Apply
7
+
8
+ Apply CC9 when your component:
9
+ - Uses third-party libraries or services
10
+ - Integrates with external vendors
11
+ - Depends on other services
12
+
13
+ ## Controls
14
+
15
+ | Control | Name | Description |
16
+ |---------|------|-------------|
17
+ | CC9.1 | Risk Mitigation | Entity identifies, selects, and develops risk mitigation activities |
18
+ | CC9.2 | Vendor Risk | Entity assesses and manages risks associated with vendors and business partners |
19
+
20
+ ## Mapping Guidance
21
+
22
+ For software components:
23
+ - **Dependency scanning** → CC9.1, CC9.2
24
+ - **Vendor security reviews** → CC9.2
25
+ - **Fallback mechanisms** → CC9.1
26
+ - **Circuit breakers** → CC9.1
27
+ - **Supply chain verification** → CC9.2
28
+
29
+ ### Example Mappings
30
+
31
+ | Control | Typical NFR |
32
+ |---------|-------------|
33
+ | CC9.1 | NFR-XXX (fail-safe), NFR-XXX (graceful degradation) |
34
+ | CC9.2 | NFR-XXX (dependency policy), NFR-XXX (vendout security) |
@@ -0,0 +1,46 @@
1
+ # SOC 2 Trust Services Criteria
2
+
3
+ **Version**: 2017 TSC
4
+ **Scope**: Service organization controls
5
+ **Region**: Global (primarily US-focused)
6
+
7
+ ## When to Apply
8
+
9
+ Apply SOC 2 when your component:
10
+ - Provides services to other businesses (B2B)
11
+ - Handles customer data on behalf of others
12
+ - Is part of a service organization's control environment
13
+ - Needs to demonstrate security controls to customers/auditors
14
+
15
+ ## Category Selection Guide
16
+
17
+ **Use this to decide which category to investigate:**
18
+
19
+ | If your component... | Read Category |
20
+ |---------------------|---------------|
21
+ | Implements authentication | [CC6-LogicalPhysicalAccess](CC6-LogicalPhysicalAccess.md) |
22
+ | Implements authorization/RBAC/ABAC | [CC6-LogicalPhysicalAccess](CC6-LogicalPhysicalAccess.md) |
23
+ | Uses encryption or TLS | [CC6-LogicalPhysicalAccess](CC6-LogicalPhysicalAccess.md) |
24
+ | Produces audit logs or metrics | [CC7-SystemOperations](CC7-SystemOperations.md) |
25
+ | Has configuration changes | [CC8-ChangeManagement](CC8-ChangeManagement.md) |
26
+ | Uses third-party dependencies | [CC9-RiskMitigation](CC9-RiskMitigation.md) |
27
+ | Communicates with external systems | [CC2-CommunicationInformation](CC2-CommunicationInformation.md) |
28
+
29
+ ## Criteria Categories
30
+
31
+ | Category | Primary For | Skip If |
32
+ |----------|-------------|---------|
33
+ | [CC1-ControlEnvironment](CC1-ControlEnvironment.md) | Governance | Always organizational |
34
+ | [CC2-CommunicationInformation](CC2-CommunicationInformation.md) | External APIs, docs | Internal-only |
35
+ | [CC3-RiskAssessment](CC3-RiskAssessment.md) | Threat modeling | Already documented |
36
+ | [CC4-MonitoringActivities](CC4-MonitoringActivities.md) | Health checks | Pre-production only |
37
+ | [CC5-ControlActivities](CC5-ControlActivities.md) | Control implementation | Covered in CC6 |
38
+ | [CC6-LogicalPhysicalAccess](CC6-LogicalPhysicalAccess.md) | **Auth, authz, crypto** | No access control |
39
+ | [CC7-SystemOperations](CC7-SystemOperations.md) | Logging, monitoring | No security events |
40
+ | [CC8-ChangeManagement](CC8-ChangeManagement.md) | Version control, CI/CD | All software |
41
+ | [CC9-RiskMitigation](CC9-RiskMitigation.md) | Dependencies, vendors | No external deps |
42
+
43
+ ## Quick Reference
44
+
45
+ **Most software components**: Focus on CC6, CC7, CC8
46
+ **Physical controls (CC6.4-6.5)**: Assign to Infrastructure
@@ -0,0 +1,46 @@
1
+ # Security Standards Reference
2
+
3
+ Index of security standards for compliance analysis. Each standard has its own directory with chapter-level detail.
4
+
5
+ ## When to Apply
6
+
7
+ **ALL standards apply to ALL components.** Apply comprehensive coverage, then scope based on component function.
8
+
9
+ | Standard | Primary Application | Key Indicator |
10
+ |----------|---------------------|---------------|
11
+ | [SOC 2](soc2/index.md) | Service organization controls | Any B2B SaaS or service provider |
12
+ | [ISO 27001](iso27001/index.md) | Information security management | Enterprise, international, or certified requirements |
13
+ | [NIST 800-53](nist-800-53/index.md) | Federal information systems | US government, federal contractors |
14
+ | [OWASP ASVS](owasp-asvs/index.md) | Application security verification | Web applications, APIs, mobile |
15
+ | [GDPR](gdpr/index.md) | EU data protection | Any EU user data processing |
16
+
17
+ ## Standard Summaries
18
+
19
+ ### SOC 2 (2017 TSC)
20
+ Trust Services Criteria for service organizations. Focuses on Security (mandatory), plus optional Availability, Processing Integrity, Confidentiality, and Privacy.
21
+
22
+ **Apply when**: Building B2B services, cloud services, or handling customer data for other organizations.
23
+
24
+ ### ISO/IEC 27001:2022
25
+ International standard for Information Security Management Systems (ISMS). Annex A provides 93 controls across 4 themes.
26
+
27
+ **Apply when**: International operations, enterprise customers, or seeking certification.
28
+
29
+ ### NIST SP 800-53 Rev 5.2.0
30
+ Comprehensive security and privacy controls for federal information systems. 20 control families covering all aspects of security.
31
+
32
+ **Apply when**: US federal systems, government contractors, or as comprehensive baseline.
33
+
34
+ ### OWASP ASVS 5.0.0
35
+ Application Security Verification Standard. 14 verification areas for testing application security.
36
+
37
+ **Apply when**: Web applications, APIs, any user-facing software.
38
+
39
+ ### EU GDPR 2016/679
40
+ General Data Protection Regulation for EU data protection and privacy.
41
+
42
+ **Apply when**: Processing personal data of EU residents.
43
+
44
+ ## Quick Reference
45
+
46
+ For component-type specific guidance, see [component-type-mapping.md](component-type-mapping.md).
@@ -0,0 +1,44 @@
1
+ ---
2
+ name: spec-to-plan
3
+ description: Convert ISO spec requirements (StR, FR, NFR) into a TDD-based project plan with dependency analysis, parallel execution tracks, quality gates, and task decomposition. Creates /plan/plan.md and /plan/tasks/.
4
+ ---
5
+
6
+ # Spec to Plan
7
+
8
+ This skill provides a structured workflow for converting ISO/IEC/IEEE 29148 compliant specifications into an executable, dependency-aware project plan with parallel execution tracks and quality gates.
9
+
10
+ ## Purpose
11
+
12
+ Use this skill when:
13
+ - You are starting a new implementation task based on an existing Spec.
14
+ - You need to generate a Test Plan before writing code (TDD).
15
+ - You want to ensure full traceability from Requirements (StR/FR/NFR) to Tests.
16
+ - You need to identify what can be parallelized vs what must be serial.
17
+ - You want quality gates to catch fundamental problems before downstream work is wasted.
18
+
19
+ ## Pre-conditions (Readiness Gate)
20
+
21
+ Task generation MAY begin only when ALL of the following are true:
22
+
23
+ - All requirements are atomic and testable.
24
+ - Ownership is assigned (see `spec-scope-boundary-analysis`).
25
+ - Dependencies are known (see `spec-dependency-analysis`).
26
+ - Risks are classified (see `spec-risk-complexity-analysis`).
27
+ - Verification strategy is defined (see `spec-evidence-analysis`).
28
+ - Failure-domain analysis is complete (see `spec-failure-domain-analysis`).
29
+
30
+ Failure to meet these conditions WILL result in unstable tasking. If any condition is unmet, stop and complete the corresponding analysis skill first.
31
+
32
+ ## Steps
33
+ All steps required!
34
+
35
+ 1. **[Analysis](references/step-1-analysis.md)**: Analyze the spec structure and map dependencies.
36
+ 2. **[Test Plan](references/step-2-test-plan.md)**: Generate the list of required tests.
37
+ 3. **[Execution Plan](references/step-3-execution-plan.md)**: Derive dependency graph, critical path, parallel tracks, quality gates, and task decomposition.
38
+
39
+ ## Output
40
+
41
+ This skill produces or updates:
42
+ - `<project_root>/plan/plan.md`: The central living document containing requirements summary, dependency graph, execution tracks, quality gates, and test plan.
43
+ - `<project_root>/plan/tasks/`: Individual task files for distribution and tracking, with status, dependencies, and subtask breakdowns.
44
+ - `<project_root>/plan/tasks/README.md`: Task index showing completed work, active tracks, and coordination rules.
@@ -0,0 +1,58 @@
1
+ # Step 1: Requirements Analysis
2
+
3
+ **Goal**: Analyze the ISO specification to understand what needs to be built, map dependencies, and identify the requirement dependency graph that drives execution planning.
4
+
5
+ ## Process
6
+
7
+ 1. **Locate References**:
8
+ - Find the component specification (usually `spec.md` or `specs/`).
9
+ - Identify `stakeholder/*.md`, `functional/*.md`, and `non-functional/*.md`.
10
+
11
+ 2. **Order of Analysis**:
12
+ - **Stakeholder Requirements (StR)**: Understand the "Why" and "Who". Identify normative constraints.
13
+ - **Functional Requirements (FR)**: Understand the "What". These map directly to logic and Unit/Integration tests.
14
+ - **Non-Functional Requirements (NFR)**: Understand the "How" (Quality). These map to performance/security constraints and Verification tests.
15
+
16
+ 3. **Dependency Extraction**:
17
+ - **Primary source**: YAML `traces:` and `relationships:` frontmatter arrays in each spec file.
18
+ - **Secondary source**: Normative references in requirement text (e.g., "SHALL use GenericXLog" implies a dependency on the WAL requirement).
19
+ - **Shared algorithms**: If two FRs describe the same underlying algorithm (e.g., graph traversal used by both scan and insert), note this as a shared dependency even if not explicitly linked in frontmatter.
20
+ - **Build a DAG**: Express dependencies as directed edges with reasons. This graph drives Step 3 execution planning.
21
+
22
+ 4. **Traceability Mapping**:
23
+ - Create or update `/plan/plan.md` with a requirements checklist.
24
+ - Include the full dependency graph with edge labels.
25
+
26
+ ## Output Format (/plan/plan.md)
27
+
28
+ ```markdown
29
+ # Implementation Plan: [Component Name]
30
+
31
+ ## Requirements Summary
32
+
33
+ ### Stakeholder Requirements
34
+ - [ ] **StR-001**: [Summary]
35
+
36
+ ### Functional Requirements
37
+ - [ ] **FR-001**: [Summary]
38
+ - [ ] **FR-002**: [Summary]
39
+
40
+ ### Non-Functional Requirements
41
+ - [ ] **NFR-001**: [Summary]
42
+
43
+ ## Dependency Graph
44
+
45
+ ### Core dependency edges
46
+ - `FR-001 -> FR-002, FR-003`
47
+ Reason: [why FR-002 and FR-003 depend on FR-001]
48
+ - `FR-004 + FR-005 -> FR-006`
49
+ Reason: [why FR-006 needs both]
50
+
51
+ ### Shared dependencies
52
+ - [Algorithm/component X] is needed by FR-007, FR-008, and FR-009.
53
+ Extract as a discrete deliverable before any of them start.
54
+
55
+ ### Cross-cutting constraints
56
+ - `NFR-001` applies to [which code paths].
57
+ - `NFR-002` applies to [which merge points].
58
+ ```
@@ -0,0 +1,37 @@
1
+ # Step 2: Test Plan Creation
2
+
3
+ **Goal**: Define a comprehensive list of tests *before* writing any code (TDD).
4
+
5
+ ## Process
6
+
7
+ 1. **Derive Tests from FRs**:
8
+ - For each Functional Requirement (FR), identify the necessary **Unit Tests** (pure logic) and **Integration Tests** (component interaction).
9
+ - Define the *Entrance Criteria* (Setup) and *Exit Criteria* (Assertions).
10
+
11
+ 2. **Enumerate Acceptance Criteria**:
12
+ - For each FR and NFR, explicitly list all Acceptance Criteria (AC IDs) from the spec.
13
+ - If no formal ACs exist in the spec, derive them and document in the plan for traceability.
14
+ - This ensures implementation progress is trackable per-criterion, not just per-requirement.
15
+
16
+ 3. **Derive Verification from NFRs**:
17
+ - For each Non-Functional Requirement (NFR), define the **Verification Method** (e.g., Load Test script, Static Analysis check, Manual Inspection).
18
+
19
+ 4. **Structure the Plan**:
20
+ - Append a "Test Plan" section to `/plan/plan.md`.
21
+ - Group tests by the component/module they target.
22
+
23
+ ## Output Format (/plan/plan.md)
24
+
25
+ ```markdown
26
+ ## Test Plan
27
+
28
+ ### Unit Tests
29
+ - [ ] **test_valid_input_processing** (FR-001): Verify X returns Y given Z.
30
+ - [ ] **test_error_handling_invalid_id** (FR-001): Verify System raises ValueError on invalid ID.
31
+
32
+ ### Integration Tests
33
+ - [ ] **test_database_persistence** (FR-002): Verify data is strictly committed to DB.
34
+
35
+ ### Verification (NFRs)
36
+ - [ ] **verify_response_time** (NFR-001): Run load test to ensure p95 < 200ms.
37
+ ```
@@ -0,0 +1,178 @@
1
+ # Step 3: Execution Plan
2
+
3
+ **Goal**: Derive an actionable execution plan with dependency-aware sequencing, parallel tracks, task decomposition, and quality gates from the requirements and test plan.
4
+
5
+ ## Why This Step Exists
6
+
7
+ A requirements checklist and test plan tell you *what* to build and *how to verify it*. They don't tell you *in what order*, *what can run in parallel*, or *where to stop and validate before proceeding*. Without execution planning:
8
+ - Serial work blocks unnecessarily when items could be parallelized
9
+ - Shared dependencies are discovered late, causing rework or duplication
10
+ - There are no gates to catch fundamental problems before downstream work is wasted
11
+ - Task tracking doesn't reflect actual progress
12
+
13
+ ## Process
14
+
15
+ ### 1. Build the Dependency Graph
16
+
17
+ For each incomplete FR and NFR, determine what it depends on and what it unblocks.
18
+
19
+ **Sources of dependency information:**
20
+ - `traces:` frontmatter in spec files (explicit upstream requirements)
21
+ - `relationships:` arrays (explicit component dependencies)
22
+ - Normative references in requirement text (e.g., "SHALL use GenericXLog" implies WAL dependency)
23
+ - Shared algorithms or data structures (e.g., two FRs that both need graph traversal)
24
+
25
+ **Key output:** A directed acyclic graph (DAG) of requirements, with edges labeled by the reason for the dependency. Write this as a text list of edges with reasons:
26
+
27
+ ```markdown
28
+ ## Dependency Graph
29
+ - `FR-007 -> FR-008, FR-009, FR-010, FR-016`
30
+ Reason: build/scan/vacuum/insert all depend on stable page and tuple layout.
31
+ - `FR-009 (graph traversal) -> FR-016 (insert), FR-010 (vacuum)`
32
+ Reason: insert and vacuum reuse the scan traversal algorithm for neighbor search.
33
+ ```
34
+
35
+ ### 2. Identify the Critical Path
36
+
37
+ The critical path is the longest serial chain through the dependency graph. Everything not on the critical path is a candidate for parallel execution.
38
+
39
+ **Method:**
40
+ 1. Topologically sort the dependency graph
41
+ 2. Identify the longest chain (by estimated effort, not just count)
42
+ 3. Mark items on this chain — these determine minimum completion time
43
+ 4. Everything else is parallelizable
44
+
45
+ **Key output:** The critical path as an ordered list, with effort estimates per step.
46
+
47
+ ### 3. Identify Shared Dependencies
48
+
49
+ Look for requirements or algorithms that appear as dependencies of multiple downstream items. These are high-value deliverables that should be extracted as explicit, testable units.
50
+
51
+ **Common patterns:**
52
+ - A traversal algorithm used by both scan and insert
53
+ - A serialization format used by both build and vacuum
54
+ - A scoring function used by both query path and maintenance path
55
+
56
+ **Key output:** List shared dependencies explicitly and mark them as discrete deliverables in the task breakdown.
57
+
58
+ ### 4. Define Quality Gates
59
+
60
+ A gate is a checkpoint where you validate a fundamental assumption before investing in downstream work. Gates prevent wasted effort.
61
+
62
+ **When to add a gate:**
63
+ - After implementing a core algorithm whose correctness determines whether the whole system works (e.g., recall measurement after implementing search)
64
+ - Before starting optimization work (confirm correctness first)
65
+ - Before starting dependent work that would need rework if the gate fails
66
+
67
+ **Gate format:**
68
+ ```markdown
69
+ #### Gate: [Name]
70
+ - **Measures:** [What you're validating]
71
+ - **Pass criteria:** [Specific threshold]
72
+ - **If fails:** [What to investigate before proceeding]
73
+ ```
74
+
75
+ ### 5. Decompose into Parallel Tracks
76
+
77
+ Group remaining work into tracks based on dependency relationships:
78
+
79
+ - **Track A (Critical Path):** Items that must be serial because each depends on the previous. This is the primary agent's work.
80
+ - **Track B (Parallel):** Items with no dependency on the critical path. These can start immediately on a separate agent.
81
+ - **Track C (Post-Gate):** Items that depend on a gate passing. These should not start until the gate is confirmed.
82
+
83
+ For each track, state:
84
+ - What items it contains
85
+ - What it depends on (if anything)
86
+ - Whether it can run on an independent agent
87
+
88
+ ### 6. Create Task Files
89
+
90
+ Break each track into task files under `plan/tasks/`. Each task file should contain:
91
+
92
+ ```markdown
93
+ # Task NN: [Title]
94
+
95
+ Status: [not started | in progress | blocked on Task XX | complete]
96
+
97
+ ## Scope
98
+ [What this task delivers]
99
+
100
+ ## Subtasks
101
+ - [ ] **[Subtask name].** [Description with key concerns.]
102
+
103
+ ## Owns
104
+ - [FR/NFR IDs]
105
+
106
+ ## Dependencies
107
+ - [Task IDs this depends on]
108
+
109
+ ## Unblocks
110
+ - [Task IDs or capabilities this enables]
111
+
112
+ ## Deliverables
113
+ - [Concrete outputs]
114
+
115
+ ## Primary Tests
116
+ - [TC/BC IDs from the test plan]
117
+
118
+ ## Notes
119
+ - [Implementation guidance, references, risk callouts]
120
+ ```
121
+
122
+ **Task decomposition rules:**
123
+ - Tasks should be scoped to 1-3 agent sessions of work
124
+ - If a task bundles items with different dependencies, split it (e.g., don't bundle "build + scan" if build is done and scan is blocked)
125
+ - Mark blocked tasks with what they're blocked on
126
+ - Mark parallel-ready tasks explicitly so agents know they can start
127
+
128
+ ### 7. Write the Task README
129
+
130
+ Create `plan/tasks/README.md` as an index showing:
131
+ - Completed tasks
132
+ - Each track (critical path, parallel, post-gate)
133
+ - Coordination rules (what to freeze, what not to start early, merge sequencing)
134
+
135
+ ## Output Format (appended to /plan/plan.md)
136
+
137
+ ```markdown
138
+ ## Remaining Work
139
+
140
+ ### Remaining Dependency Graph
141
+ [Text DAG or ASCII diagram showing what depends on what]
142
+
143
+ ### Track A: Critical Path (serial)
144
+ #### A1: [First step]
145
+ - **Scope:** ...
146
+ - **Difficulty:** Easy | Medium | Hard
147
+ - **Estimated new code:** ~NNN lines
148
+ - **Exit criteria:** ...
149
+
150
+ #### A2: [Second step]
151
+ ...
152
+
153
+ #### Gate: [Quality checkpoint]
154
+ - **Measures:** ...
155
+ - **Pass criteria:** ...
156
+
157
+ ### Track B: Parallel (independent agent, can start now)
158
+ #### B1: [Parallel item]
159
+ ...
160
+
161
+ ### Track C: Post-Gate
162
+ #### C1: [Gated item]
163
+ ...
164
+
165
+ ## Parallel Execution Summary
166
+ [ASCII timeline showing tracks running concurrently]
167
+
168
+ ## Task File Mapping
169
+ [Table mapping task files to track items and status]
170
+ ```
171
+
172
+ ## Common Mistakes to Avoid
173
+
174
+ - **Bundling done + remaining work in one task.** If build is done but scan isn't, they're separate tasks even if they were originally planned together.
175
+ - **Missing shared dependencies.** If two items need the same algorithm, extract it as a deliverable — don't let two parallel workers implement it independently.
176
+ - **No gates.** If the whole system's value depends on one unproven property (e.g., recall quality), measure it before building everything around it.
177
+ - **Stale plans.** The execution plan should be updated as work progresses. Completed phases should be collapsed, not left as active planning noise.
178
+ - **Optimistic parallelism.** Don't mark items as parallel if they share mutable state (same files, same data structures). Merge conflicts erase the time savings.
@@ -0,0 +1,146 @@
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
@@ -0,0 +1 @@
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"}