@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.
- package/LICENSE +21 -0
- package/README.md +122 -0
- package/bin/quoin.js +8 -0
- package/default-modules.yaml +82 -0
- package/dist/catalog.d.ts +32 -0
- package/dist/catalog.d.ts.map +1 -0
- package/dist/cli-ClS52_Fm.js +436 -0
- package/dist/cli.d.ts +3 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/cli.js +2 -0
- package/dist/flows.d.ts +7 -0
- package/dist/flows.d.ts.map +1 -0
- package/dist/index.d.ts +6 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +2 -0
- package/dist/modules.d.ts +10 -0
- package/dist/modules.d.ts.map +1 -0
- package/dist/plugins.d.ts +13 -0
- package/dist/plugins.d.ts.map +1 -0
- package/dist/write.d.ts +22 -0
- package/dist/write.d.ts.map +1 -0
- package/package.json +85 -0
- package/plugin.json +6 -0
- package/skills/spec-app-review/SKILL.md +51 -0
- package/skills/spec-app-review/references/checklist.md +194 -0
- package/skills/spec-dependency-analysis/SKILL.md +75 -0
- package/skills/spec-evidence-analysis/SKILL.md +78 -0
- package/skills/spec-failure-domain-analysis/SKILL.md +44 -0
- package/skills/spec-ideation/SKILL.md +46 -0
- package/skills/spec-integrity-analysis/SKILL.md +47 -0
- package/skills/spec-matrix/SKILL.md +79 -0
- package/skills/spec-matrix/assets/test-cases/TC-001.md +35 -0
- package/skills/spec-matrix/assets/test-cases/TC-002.md +37 -0
- package/skills/spec-matrix/assets/test-cases/TC-006.md +50 -0
- package/skills/spec-matrix/assets/test-matrix-example.md +97 -0
- package/skills/spec-matrix/assets/test-matrix-template.md +117 -0
- package/skills/spec-matrix/workflow-assets/dist/index.d.ts +146 -0
- package/skills/spec-matrix/workflow-assets/dist/index.d.ts.map +1 -0
- package/skills/spec-matrix/workflow-assets/dist/index.js +7655 -0
- package/skills/spec-matrix/workflow-assets/dist/invariants.d.ts +6 -0
- package/skills/spec-matrix/workflow-assets/dist/invariants.d.ts.map +1 -0
- package/skills/spec-matrix/workflow-assets/skills/matrix/SKILL.md +35 -0
- package/skills/spec-matrix/workflow-assets/skills/matrix/scripts/invariants.js +1 -0
- package/skills/spec-matrix/workflow-assets/skills/matrix/templates/report/default.md +30 -0
- package/skills/spec-matrix/workflow-assets/skills/matrix/workflows/matrix/def.yaml +82 -0
- package/skills/spec-object-review/SKILL.md +125 -0
- package/skills/spec-object-review/references/object-type-guide.md +113 -0
- package/skills/spec-review/SKILL.md +41 -0
- package/skills/spec-review/references/checklist.md +50 -0
- package/skills/spec-review/workflow-assets/dist/index.d.ts +146 -0
- package/skills/spec-review/workflow-assets/dist/index.d.ts.map +1 -0
- package/skills/spec-review/workflow-assets/dist/index.js +7655 -0
- package/skills/spec-review/workflow-assets/dist/invariants.d.ts +6 -0
- package/skills/spec-review/workflow-assets/dist/invariants.d.ts.map +1 -0
- package/skills/spec-review/workflow-assets/skills/review/SKILL.md +35 -0
- package/skills/spec-review/workflow-assets/skills/review/scripts/invariants.js +1 -0
- package/skills/spec-review/workflow-assets/skills/review/templates/report/default.md +30 -0
- package/skills/spec-review/workflow-assets/skills/review/workflows/review/def.yaml +82 -0
- package/skills/spec-risk-complexity-analysis/SKILL.md +77 -0
- package/skills/spec-scope-boundary-analysis/SKILL.md +86 -0
- package/skills/spec-security-analysis/SKILL.md +84 -0
- package/skills/spec-security-analysis/assets/security-analysis-example.md +89 -0
- package/skills/spec-security-analysis/assets/security-analysis-template.md +73 -0
- package/skills/spec-security-analysis/references/component-type-mapping.md +161 -0
- package/skills/spec-security-analysis/references/gdpr/ChII-Principles.md +58 -0
- package/skills/spec-security-analysis/references/gdpr/ChIII-DataSubjectRights.md +84 -0
- package/skills/spec-security-analysis/references/gdpr/ChIV-ControllerProcessor.md +83 -0
- package/skills/spec-security-analysis/references/gdpr/ChV-DataTransfers.md +62 -0
- package/skills/spec-security-analysis/references/gdpr/index.md +54 -0
- package/skills/spec-security-analysis/references/iso27001/A5-OrganizationalControls.md +64 -0
- package/skills/spec-security-analysis/references/iso27001/A6-PeopleControls.md +30 -0
- package/skills/spec-security-analysis/references/iso27001/A7-PhysicalControls.md +35 -0
- package/skills/spec-security-analysis/references/iso27001/A8-TechnologicalControls.md +66 -0
- package/skills/spec-security-analysis/references/iso27001/index.md +43 -0
- package/skills/spec-security-analysis/references/nist-800-53/AC-AccessControl.md +57 -0
- package/skills/spec-security-analysis/references/nist-800-53/AU-AuditAccountability.md +49 -0
- package/skills/spec-security-analysis/references/nist-800-53/CM-ConfigurationManagement.md +36 -0
- package/skills/spec-security-analysis/references/nist-800-53/IA-IdentificationAuthentication.md +44 -0
- package/skills/spec-security-analysis/references/nist-800-53/SA-SystemServicesAcquisition.md +50 -0
- package/skills/spec-security-analysis/references/nist-800-53/SC-SystemCommunications.md +53 -0
- package/skills/spec-security-analysis/references/nist-800-53/SI-SystemInformationIntegrity.md +52 -0
- package/skills/spec-security-analysis/references/nist-800-53/index.md +58 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V1-Architecture.md +33 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V10-MaliciousCode.md +33 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V11-BusinessLogic.md +32 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V12-Files.md +34 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V13-API.md +34 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V14-Configuration.md +35 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V2-Authentication.md +36 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V3-SessionManagement.md +35 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V4-AccessControl.md +39 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V5-Validation.md +37 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V6-Cryptography.md +34 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V7-ErrorLogging.md +37 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V8-DataProtection.md +34 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V9-Communication.md +32 -0
- package/skills/spec-security-analysis/references/owasp-asvs/index.md +59 -0
- package/skills/spec-security-analysis/references/soc2/CC1-ControlEnvironment.md +31 -0
- package/skills/spec-security-analysis/references/soc2/CC2-CommunicationInformation.md +27 -0
- package/skills/spec-security-analysis/references/soc2/CC3-RiskAssessment.md +29 -0
- package/skills/spec-security-analysis/references/soc2/CC4-MonitoringActivities.md +27 -0
- package/skills/spec-security-analysis/references/soc2/CC5-ControlActivities.md +28 -0
- package/skills/spec-security-analysis/references/soc2/CC6-LogicalPhysicalAccess.md +45 -0
- package/skills/spec-security-analysis/references/soc2/CC7-SystemOperations.md +42 -0
- package/skills/spec-security-analysis/references/soc2/CC8-ChangeManagement.md +32 -0
- package/skills/spec-security-analysis/references/soc2/CC9-RiskMitigation.md +34 -0
- package/skills/spec-security-analysis/references/soc2/index.md +46 -0
- package/skills/spec-security-analysis/references/standards-index.md +46 -0
- package/skills/spec-to-plan/SKILL.md +44 -0
- package/skills/spec-to-plan/references/step-1-analysis.md +58 -0
- package/skills/spec-to-plan/references/step-2-test-plan.md +37 -0
- package/skills/spec-to-plan/references/step-3-execution-plan.md +178 -0
- package/skills/spec-to-plan/workflow-assets/dist/index.d.ts +146 -0
- package/skills/spec-to-plan/workflow-assets/dist/index.d.ts.map +1 -0
- package/skills/spec-to-plan/workflow-assets/dist/index.js +7655 -0
- package/skills/spec-to-plan/workflow-assets/dist/invariants.d.ts +6 -0
- package/skills/spec-to-plan/workflow-assets/dist/invariants.d.ts.map +1 -0
- package/skills/spec-to-plan/workflow-assets/skills/to-plan/SKILL.md +35 -0
- package/skills/spec-to-plan/workflow-assets/skills/to-plan/scripts/invariants.js +1 -0
- package/skills/spec-to-plan/workflow-assets/skills/to-plan/templates/implementation-plan/default.md +43 -0
- package/skills/spec-to-plan/workflow-assets/skills/to-plan/workflows/to-plan/def.yaml +82 -0
- package/skills/specify/SKILL.md +69 -0
- package/skills/specify/assets/app-spec-template.md +143 -0
- package/skills/specify/assets/spec-template.md +299 -0
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import { InvariantEvaluator } from '@agent-ix/workflow-core';
|
|
2
|
+
export declare const artifactFrontmatterValid: InvariantEvaluator;
|
|
3
|
+
export declare const artifactRelationshipsResolve: InvariantEvaluator;
|
|
4
|
+
export declare function clearProjectRegistryCache(): void;
|
|
5
|
+
export declare const specInvariants: Record<string, InvariantEvaluator>;
|
|
6
|
+
//# sourceMappingURL=invariants.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"invariants.d.ts","sourceRoot":"","sources":["../src/invariants.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,yBAAyB,CAAC;AAqDjC,eAAO,MAAM,wBAAwB,EAAE,kBAqHtC,CAAC;AAIF,eAAO,MAAM,4BAA4B,EAAE,kBAiG1C,CAAC;AA4DF,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AAED,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAG7D,CAAC"}
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: spec-to-plan
|
|
3
|
+
description: Convert validated requirements into an implementation plan.
|
|
4
|
+
contributes:
|
|
5
|
+
workflows: ./workflows
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# /spec-to-plan
|
|
9
|
+
|
|
10
|
+
## When To Use
|
|
11
|
+
|
|
12
|
+
Use this skill when accepted requirements should become ordered implementation work.
|
|
13
|
+
|
|
14
|
+
## What It Does
|
|
15
|
+
|
|
16
|
+
Convert validated requirements into an implementation plan. The workflow definition is the source of truth for phases, gates, item schemas, recipes, and validation points.
|
|
17
|
+
|
|
18
|
+
## Workflow Behavior
|
|
19
|
+
|
|
20
|
+
- Start from the workflow status and follow reported next actions.
|
|
21
|
+
- Record evidence items before advancing analysis, review, or validation phases.
|
|
22
|
+
- Use recipes for deterministic command chains, but preserve human gates for acceptance.
|
|
23
|
+
- Prefer templates for stable artifact creation and generic file editing for broad semantic rewrites.
|
|
24
|
+
|
|
25
|
+
## Acceptance Criteria
|
|
26
|
+
|
|
27
|
+
- AC-1: Produces a plan that traces tasks back to requirement IDs.
|
|
28
|
+
- AC-2: Preserves dependencies, risks, and verification expectations in the plan.
|
|
29
|
+
- AC-3: Flags requirements that are not ready for planning instead of forcing tasks.
|
|
30
|
+
|
|
31
|
+
## Boundaries
|
|
32
|
+
|
|
33
|
+
- Do not silently overwrite existing human-authored requirements artifacts.
|
|
34
|
+
- Do not invent missing facts, links, or evidence; record assumptions and gaps.
|
|
35
|
+
- Do not expand to adjacent spec operations unless the user request requires it or the workflow directs it.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export { specInvariants as invariants } from "../../../dist/index.js";
|
package/skills/spec-to-plan/workflow-assets/skills/to-plan/templates/implementation-plan/default.md
ADDED
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
---
|
|
2
|
+
type: implementation-plan
|
|
3
|
+
id: "{{items.plan_answers.plan.id}}"
|
|
4
|
+
title: "{{items.plan_answers.plan.title}}"
|
|
5
|
+
traces_to:
|
|
6
|
+
- "{{items.plan_answers.plan.requirement_ids}}"
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# {{items.plan_answers.plan.id}}: {{items.plan_answers.plan.title}}
|
|
10
|
+
|
|
11
|
+
## Scope
|
|
12
|
+
|
|
13
|
+
This plan covers accepted requirements:
|
|
14
|
+
|
|
15
|
+
{{items.plan_answers.plan.requirement_ids}}
|
|
16
|
+
|
|
17
|
+
## Readiness Notes
|
|
18
|
+
|
|
19
|
+
{{items.plan_answers.plan.readiness_notes}}
|
|
20
|
+
|
|
21
|
+
## Work Breakdown
|
|
22
|
+
|
|
23
|
+
| Task | Requirement Trace | Outcome | Verification |
|
|
24
|
+
| ---- | ------------------------------------------- | ------------------------------ | ---------------------------------------------------- |
|
|
25
|
+
| T-1 | {{items.plan_answers.plan.requirement_ids}} | Define implementation changes. | Tests or review evidence linked to each requirement. |
|
|
26
|
+
| T-2 | {{items.plan_answers.plan.requirement_ids}} | Implement scoped changes. | Passing automated checks. |
|
|
27
|
+
| T-3 | {{items.plan_answers.plan.requirement_ids}} | Update verification evidence. | Requirements matrix or review report updated. |
|
|
28
|
+
|
|
29
|
+
## Dependencies
|
|
30
|
+
|
|
31
|
+
- Confirm every traced requirement is accepted and implementation-ready.
|
|
32
|
+
- Resolve readiness notes before scheduling blocked work.
|
|
33
|
+
|
|
34
|
+
## Risks
|
|
35
|
+
|
|
36
|
+
- Requirements with weak acceptance criteria may produce vague tasks.
|
|
37
|
+
- Missing trace evidence may cause implementation work to drift from the spec.
|
|
38
|
+
|
|
39
|
+
## Acceptance Criteria
|
|
40
|
+
|
|
41
|
+
- Every task traces to at least one requirement id.
|
|
42
|
+
- Every traced requirement has an implementation or verification task.
|
|
43
|
+
- Blockers are explicit and not hidden inside task descriptions.
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
name: to-plan
|
|
2
|
+
version: 0.1.0
|
|
3
|
+
description: Convert accepted requirements into a traced implementation plan.
|
|
4
|
+
initialPhase: intake
|
|
5
|
+
phases:
|
|
6
|
+
- { name: intake }
|
|
7
|
+
- { name: evidence_recorded }
|
|
8
|
+
- { name: plan_drafted }
|
|
9
|
+
- { name: validated }
|
|
10
|
+
- { name: accepted, terminal: true }
|
|
11
|
+
transitions:
|
|
12
|
+
- from: intake
|
|
13
|
+
to: evidence_recorded
|
|
14
|
+
invariants:
|
|
15
|
+
- "interview.complete:plan"
|
|
16
|
+
defaultGate: auto
|
|
17
|
+
- from: evidence_recorded
|
|
18
|
+
to: plan_drafted
|
|
19
|
+
invariants: []
|
|
20
|
+
defaultGate: auto
|
|
21
|
+
- from: plan_drafted
|
|
22
|
+
to: validated
|
|
23
|
+
invariants:
|
|
24
|
+
- "artifact.frontmatter_valid:implementation_plan"
|
|
25
|
+
defaultGate: auto
|
|
26
|
+
- from: validated
|
|
27
|
+
to: accepted
|
|
28
|
+
invariants: []
|
|
29
|
+
defaultGate: hitl
|
|
30
|
+
itemSchemas:
|
|
31
|
+
plan_answers: {}
|
|
32
|
+
ImplementationPlanSchema:
|
|
33
|
+
required: [type, id, title, traces_to]
|
|
34
|
+
properties:
|
|
35
|
+
type: { type: string }
|
|
36
|
+
id: { type: string }
|
|
37
|
+
title: { type: string }
|
|
38
|
+
traces_to: { type: array }
|
|
39
|
+
linkSchemas: {}
|
|
40
|
+
interviews:
|
|
41
|
+
plan:
|
|
42
|
+
itemType: plan_answers
|
|
43
|
+
completenessRule: all_required
|
|
44
|
+
questions:
|
|
45
|
+
- key: artifact_id
|
|
46
|
+
prompt: "Plan id, for example PLAN-001."
|
|
47
|
+
type: text
|
|
48
|
+
required: true
|
|
49
|
+
- key: slug
|
|
50
|
+
prompt: "Filename slug without the plan id."
|
|
51
|
+
type: text
|
|
52
|
+
required: true
|
|
53
|
+
- key: title
|
|
54
|
+
prompt: "Implementation plan title."
|
|
55
|
+
type: text
|
|
56
|
+
required: true
|
|
57
|
+
- key: requirement_ids
|
|
58
|
+
prompt: "Comma-separated accepted requirement ids this plan traces to."
|
|
59
|
+
type: text
|
|
60
|
+
required: true
|
|
61
|
+
- key: readiness_notes
|
|
62
|
+
prompt: "Known blockers, assumptions, or readiness notes."
|
|
63
|
+
type: text
|
|
64
|
+
required: true
|
|
65
|
+
artifactTemplates:
|
|
66
|
+
implementation_plan:
|
|
67
|
+
source: templates/implementation-plan/default.md
|
|
68
|
+
target: spec/plans/${items.plan_answers.plan.id}-${items.plan_answers.plan.slug}.md
|
|
69
|
+
phase: plan_drafted
|
|
70
|
+
frontmatterSchema: ImplementationPlanSchema
|
|
71
|
+
recipes:
|
|
72
|
+
draft-and-validate:
|
|
73
|
+
description: Record planning inputs, draft the traced plan, validate it, then stop at acceptance.
|
|
74
|
+
steps:
|
|
75
|
+
- command: advance
|
|
76
|
+
to: evidence_recorded
|
|
77
|
+
- command: advance
|
|
78
|
+
to: plan_drafted
|
|
79
|
+
- command: advance
|
|
80
|
+
to: validated
|
|
81
|
+
- command: advance
|
|
82
|
+
to: accepted
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: specify
|
|
3
|
+
description: Create or update spec files using quoin catalog authoring packs and Quire validation.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Specify
|
|
7
|
+
|
|
8
|
+
Use this skill when turning an agreed design, feature, or change request into
|
|
9
|
+
spec artifacts and supporting spec objects.
|
|
10
|
+
|
|
11
|
+
## Process
|
|
12
|
+
|
|
13
|
+
1. Identify the repository that owns the spec files.
|
|
14
|
+
2. Identify every artifact and object type that will be created or edited.
|
|
15
|
+
3. Run `quoin write <repo_dir> --types <type[,type...]>` once for the full set of types.
|
|
16
|
+
4. Use the returned skeletons, schemas, module roots, and examples as the authoring contract.
|
|
17
|
+
5. Author or edit the files directly in the target repo.
|
|
18
|
+
6. Run `quire validate <glob> [glob2 ...]` over the changed spec scope.
|
|
19
|
+
7. Fix validation errors before moving to review, matrix, or planning work.
|
|
20
|
+
|
|
21
|
+
## Type Selection
|
|
22
|
+
|
|
23
|
+
Request all needed types together so the agent does not repeatedly fetch the
|
|
24
|
+
same templates.
|
|
25
|
+
|
|
26
|
+
Examples:
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
quoin write . --types FR,domain,entity
|
|
30
|
+
quoin write ../service --types StR,US,FR,NFR
|
|
31
|
+
quoin write . --types process,configuration,value_object
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Type lookup is catalog-driven and case-insensitive. Types may come from bundled
|
|
35
|
+
`spec-artifacts-*`, bundled `spec-objects-*`, user-installed modules, or
|
|
36
|
+
community modules.
|
|
37
|
+
|
|
38
|
+
## Authoring Rules
|
|
39
|
+
|
|
40
|
+
- Let frontmatter identify exactly what each file is. The discriminator field is
|
|
41
|
+
`type` (e.g. `type: FR`, `type: master-requirements`); it names the archetype the
|
|
42
|
+
document conforms to.
|
|
43
|
+
- Use catalog skeletons and schemas rather than memory.
|
|
44
|
+
- Keep workflow definitions out of artifact/object type vocabularies.
|
|
45
|
+
- Validate every created or edited artifact with Quire.
|
|
46
|
+
- Use `spec-review` after validation for quality, consistency, and completeness review.
|
|
47
|
+
|
|
48
|
+
## Reserved OKF Files
|
|
49
|
+
|
|
50
|
+
`spec-artifacts-iso` ships two reserved archetypes for the OKF folder structure;
|
|
51
|
+
author them like any other type:
|
|
52
|
+
|
|
53
|
+
- `index.md` — `type: index`, body is a `## Contents` link list pointing at the
|
|
54
|
+
artifacts in the folder.
|
|
55
|
+
- `log.md` — `type: log`, body is a `## History` of changes to the folder's specs.
|
|
56
|
+
|
|
57
|
+
## Common Spec Layout
|
|
58
|
+
|
|
59
|
+
```text
|
|
60
|
+
spec/
|
|
61
|
+
├── spec.md
|
|
62
|
+
├── stakeholder/
|
|
63
|
+
├── usecase/
|
|
64
|
+
├── functional/
|
|
65
|
+
├── non-functional/
|
|
66
|
+
├── integration/
|
|
67
|
+
├── matrix/
|
|
68
|
+
└── analysis/
|
|
69
|
+
```
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
---
|
|
2
|
+
type: master-requirements
|
|
3
|
+
name: <app-name>
|
|
4
|
+
org: <your-org>
|
|
5
|
+
component_type: application
|
|
6
|
+
tags: []
|
|
7
|
+
implementation_language: null
|
|
8
|
+
depends_on:
|
|
9
|
+
# List all component repos this application owns
|
|
10
|
+
# - service-one
|
|
11
|
+
# - library-one
|
|
12
|
+
standards_alignment:
|
|
13
|
+
- iso-iec-ieee-29148
|
|
14
|
+
security_critical: false
|
|
15
|
+
---
|
|
16
|
+
# Master Requirements Specification
|
|
17
|
+
## <App Name>
|
|
18
|
+
|
|
19
|
+
### 1. Purpose
|
|
20
|
+
|
|
21
|
+
<!-- 2-3 sentences: What problem does this application solve? Who does it serve?
|
|
22
|
+
Be specific — avoid restating the component names. -->
|
|
23
|
+
|
|
24
|
+
### 2. Scope
|
|
25
|
+
|
|
26
|
+
This specification defines the **application-level** domain, encompassing end-to-end processes that span multiple component repositories. Individual component behavior is specified in each component's own `spec/` directory; this document defines how they compose into a complete system.
|
|
27
|
+
|
|
28
|
+
### 3. System Overview
|
|
29
|
+
|
|
30
|
+
#### 3.1 Component Registry
|
|
31
|
+
|
|
32
|
+
<!-- One row per component repo. Distinguish services vs libraries. -->
|
|
33
|
+
|
|
34
|
+
| Component | Type | Repo | Role |
|
|
35
|
+
|-----------|------|------|------|
|
|
36
|
+
| <!-- name --> | <!-- fastapi-service / python-lib / react-lib / etc --> | `<!-- repo-name -->` | <!-- What it does in 1 sentence --> |
|
|
37
|
+
|
|
38
|
+
#### 3.2 Dependency Graph
|
|
39
|
+
|
|
40
|
+
<!-- Required: Show how components connect. Use color styles to distinguish
|
|
41
|
+
services (red), libraries (green), SDKs (orange), UI (purple). -->
|
|
42
|
+
|
|
43
|
+
```mermaid
|
|
44
|
+
graph TD
|
|
45
|
+
A[ComponentA] --> B[ComponentB]
|
|
46
|
+
|
|
47
|
+
style A fill:#e74c3c,color:#fff
|
|
48
|
+
style B fill:#2ecc71,color:#fff
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
### 4. Architecture Rationale
|
|
52
|
+
|
|
53
|
+
<!-- Required: Explain WHY the architecture looks the way it does.
|
|
54
|
+
One ADR entry per major structural decision. -->
|
|
55
|
+
|
|
56
|
+
#### ADR-001: <!-- Decision Title -->
|
|
57
|
+
|
|
58
|
+
**Decision**: <!-- What was decided. One sentence. -->
|
|
59
|
+
|
|
60
|
+
**Rationale**: <!-- Why? What problem does this solve? -->
|
|
61
|
+
|
|
62
|
+
**Alternatives considered**: <!-- What else was evaluated and why it was rejected. -->
|
|
63
|
+
|
|
64
|
+
### 5. Stakeholder Requirements
|
|
65
|
+
|
|
66
|
+
| ID | Title | Artifact |
|
|
67
|
+
|----|-------|----------|
|
|
68
|
+
| StR-001 | <!-- Title --> | [StR-001](stakeholder/StR-001-<slug>.md) |
|
|
69
|
+
|
|
70
|
+
### 6. User Stories
|
|
71
|
+
|
|
72
|
+
| ID | Title | Role | Artifact |
|
|
73
|
+
|----|-------|------|----------|
|
|
74
|
+
| US-001 | <!-- Title --> | <!-- Role --> | [US-001](usecase/US-001-<slug>.md) |
|
|
75
|
+
|
|
76
|
+
### 7. Functional Requirements
|
|
77
|
+
|
|
78
|
+
<!-- Application specs MUST include these object types:
|
|
79
|
+
- domain: Bounded context, ER diagram (FR-001)
|
|
80
|
+
- process: One per major cross-service workflow
|
|
81
|
+
- configuration: Shared config across services
|
|
82
|
+
- integration: Consumer contract (how to integrate with this app) -->
|
|
83
|
+
|
|
84
|
+
| ID | Title | Object Type | Artifact |
|
|
85
|
+
|----|-------|-------------|----------|
|
|
86
|
+
| FR-001 | <!-- App --> Domain | domain | [FR-001](functional/FR-001-<slug>-domain.md) |
|
|
87
|
+
| FR-002 | <!-- Primary Workflow --> Process | process | [FR-002](functional/FR-002-<slug>-process.md) |
|
|
88
|
+
| FR-XXX | <!-- App --> Configuration | configuration | [FR-XXX](functional/FR-XXX-configuration.md) |
|
|
89
|
+
| FR-XXX | Consumer Integration Contract | integration | [FR-XXX](functional/FR-XXX-consumer-integration.md) |
|
|
90
|
+
|
|
91
|
+
### 8. Non-Functional Requirements
|
|
92
|
+
|
|
93
|
+
<!-- Application specs MUST include these three NFRs:
|
|
94
|
+
- Security Constraints (crypto, transport, error handling)
|
|
95
|
+
- System Reliability (SLA, p99 latency, scale limits, RTO/RPO)
|
|
96
|
+
- Deployment Topology (namespace, ingress, discovery, secrets) -->
|
|
97
|
+
|
|
98
|
+
| ID | Title | Artifact |
|
|
99
|
+
|----|-------|----------|
|
|
100
|
+
| NFR-001 | Security Constraints | [NFR-001](non-functional/NFR-001-security.md) |
|
|
101
|
+
| NFR-002 | System Reliability | [NFR-002](non-functional/NFR-002-reliability.md) |
|
|
102
|
+
| NFR-003 | Deployment Topology | [NFR-003](non-functional/NFR-003-deployment.md) |
|
|
103
|
+
|
|
104
|
+
### 9. Domain Model
|
|
105
|
+
|
|
106
|
+
See [FR-001 <!-- App --> Domain](functional/FR-001-<slug>-domain.md) for the bounded context definition, entity relationships, and ER diagram.
|
|
107
|
+
|
|
108
|
+
### 10. Scope Boundaries
|
|
109
|
+
|
|
110
|
+
<!-- Required: Explicitly list what this application does NOT do.
|
|
111
|
+
These are deliberate exclusions, not future work. -->
|
|
112
|
+
|
|
113
|
+
| Out of Scope | Rationale |
|
|
114
|
+
|---|---|
|
|
115
|
+
| <!-- Feature --> | <!-- Why deliberately excluded --> |
|
|
116
|
+
|
|
117
|
+
### 11. Security Model
|
|
118
|
+
|
|
119
|
+
<!-- Required: Define the actor model and trust hierarchy.
|
|
120
|
+
What roles exist? What can each role do? -->
|
|
121
|
+
|
|
122
|
+
#### Actor Roles
|
|
123
|
+
|
|
124
|
+
| Role | Description | Assigned By |
|
|
125
|
+
|------|-------------|-------------|
|
|
126
|
+
| `anonymous` | Unauthenticated caller | Default |
|
|
127
|
+
| `user` | Authenticated user | Auth system |
|
|
128
|
+
| `admin` | Administrator | Operator |
|
|
129
|
+
| `operator` | Infrastructure operator | Out-of-band |
|
|
130
|
+
|
|
131
|
+
#### Trust Boundaries
|
|
132
|
+
|
|
133
|
+
<!-- List capabilities and which roles can exercise them. -->
|
|
134
|
+
|
|
135
|
+
| Capability | anonymous | user | admin | operator |
|
|
136
|
+
|---|---|---|---|---|
|
|
137
|
+
| <!-- action --> | — | ✅ | ✅ | ✅ |
|
|
138
|
+
|
|
139
|
+
### 12. References
|
|
140
|
+
|
|
141
|
+
| Standard | Description |
|
|
142
|
+
|----------|-------------|
|
|
143
|
+
| ISO/IEC/IEEE 29148 | Requirements engineering standard |
|
|
@@ -0,0 +1,299 @@
|
|
|
1
|
+
---
|
|
2
|
+
type: master-requirements
|
|
3
|
+
name: <component-name> # Required: repo/component name
|
|
4
|
+
org: <your-org> # Required: owning organization
|
|
5
|
+
component_type: fastapi-service # Canonical type (fastapi-service, react-lib, etc.)
|
|
6
|
+
tags: # Optional capabilities
|
|
7
|
+
- postgres
|
|
8
|
+
- redis
|
|
9
|
+
implementation_language: python
|
|
10
|
+
depends_on: [] # Direct package/service dependencies
|
|
11
|
+
relationships: # Structured array of semantic cross-references
|
|
12
|
+
- target: "ix://org/repo/<dependency-name>"
|
|
13
|
+
type: "depends_on"
|
|
14
|
+
cardinality: "1:1"
|
|
15
|
+
|
|
16
|
+
standards_alignment:
|
|
17
|
+
- iso-iec-ieee-29148
|
|
18
|
+
- ieee-828
|
|
19
|
+
---
|
|
20
|
+
# Master Requirements Specification
|
|
21
|
+
## <Project Name>
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## 1. Purpose
|
|
26
|
+
|
|
27
|
+
This document defines the **scope, intent, and governing requirements framework** for the <Project Name> Python state machine library.
|
|
28
|
+
|
|
29
|
+
It establishes:
|
|
30
|
+
- The problem space addressed by the library
|
|
31
|
+
- The boundaries of responsibility
|
|
32
|
+
- The authoritative structure for requirements, verification, and change control
|
|
33
|
+
- The relationship between user intent, system behavior, and test evidence
|
|
34
|
+
|
|
35
|
+
This document is the **top-level requirements artifact** for the repository.
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## 2. Scope
|
|
40
|
+
|
|
41
|
+
### 2.1 In Scope
|
|
42
|
+
|
|
43
|
+
This specification governs:
|
|
44
|
+
- Core state machine behavior
|
|
45
|
+
- State lifecycle management
|
|
46
|
+
- Transition rules and validation
|
|
47
|
+
- Event handling semantics
|
|
48
|
+
- Error and failure handling behavior
|
|
49
|
+
- Public APIs that affect observable behavior
|
|
50
|
+
- Deterministic execution guarantees
|
|
51
|
+
|
|
52
|
+
### 2.2 Out of Scope
|
|
53
|
+
|
|
54
|
+
This specification does not govern:
|
|
55
|
+
- Application-specific business logic
|
|
56
|
+
- UI or visualization layers
|
|
57
|
+
- Deployment concerns
|
|
58
|
+
- Integrations beyond defined interfaces
|
|
59
|
+
- Experimental or prototype features not promoted to requirements
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## 3. System Overview
|
|
64
|
+
|
|
65
|
+
### 3.1 System Description
|
|
66
|
+
|
|
67
|
+
<High-level description of the Python state machine library, its purpose, and the problems it solves.>
|
|
68
|
+
|
|
69
|
+
### 3.2 Intended Users
|
|
70
|
+
|
|
71
|
+
- <Library consumers>
|
|
72
|
+
- <Framework integrators>
|
|
73
|
+
- <Tooling or platform developers>
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
## 4. Requirements Architecture
|
|
78
|
+
|
|
79
|
+
Requirements are decomposed and managed using a **hierarchical structure** consistent with ISO/IEC/IEEE 29148.
|
|
80
|
+
|
|
81
|
+
```
|
|
82
|
+
spec/
|
|
83
|
+
├── spec.md # This document (master specification)
|
|
84
|
+
├── stakeholder/ # Stakeholder requirements (StR-XXX)
|
|
85
|
+
├── usecase/ # User intent and usage scenarios (US-XXX)
|
|
86
|
+
├── functional/ # System / functional requirements (FR-XXX)
|
|
87
|
+
├── non-functional/ # Non-functional requirements (NFR-XXX)
|
|
88
|
+
├── tests.md # Bidirectional requirements ↔ tests mapping
|
|
89
|
+
├── test_cases/ # Verification artifacts (TC-XXX)
|
|
90
|
+
├── assets/
|
|
91
|
+
├── diagrams/ # State diagrams, sequence diagrams
|
|
92
|
+
├── models/ # Formal state and data models
|
|
93
|
+
└── poc/ # Explicitly requested proof-of-concepts
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
---
|
|
97
|
+
|
|
98
|
+
## 5. Requirement Classes
|
|
99
|
+
|
|
100
|
+
### 5.1 Stakeholder Requirements
|
|
101
|
+
|
|
102
|
+
Stakeholder Requirements capture **authoritative needs and expectations**.
|
|
103
|
+
|
|
104
|
+
- Format: `StR-XXX`
|
|
105
|
+
- Location: `stakeholder/`
|
|
106
|
+
- Nature: Normative for intent
|
|
107
|
+
- Purpose: Drive system requirements
|
|
108
|
+
|
|
109
|
+
---
|
|
110
|
+
|
|
111
|
+
### 5.2 User Requirements
|
|
112
|
+
|
|
113
|
+
User Stories describe **intent, expectations, and usage outcomes**.
|
|
114
|
+
|
|
115
|
+
- Format: `US-XXX`
|
|
116
|
+
- Location: `usecase/`
|
|
117
|
+
- Nature: Informational, non-binding
|
|
118
|
+
- Purpose: Drive functional requirements
|
|
119
|
+
|
|
120
|
+
---
|
|
121
|
+
|
|
122
|
+
### 5.3 Functional Requirements
|
|
123
|
+
|
|
124
|
+
Functional Requirements define **authoritative, testable system behavior**.
|
|
125
|
+
|
|
126
|
+
- Format: `FR-XXX`
|
|
127
|
+
- Location: `functional/`
|
|
128
|
+
- Nature: Normative and binding
|
|
129
|
+
- Purpose: Define observable behavior
|
|
130
|
+
|
|
131
|
+
All functional requirements:
|
|
132
|
+
- Use deterministic language
|
|
133
|
+
- Are independently testable
|
|
134
|
+
- Trace back to one or more user requirements
|
|
135
|
+
|
|
136
|
+
---
|
|
137
|
+
|
|
138
|
+
### 5.4 Non-Functional Requirements
|
|
139
|
+
|
|
140
|
+
Non-Functional Requirements define **quality constraints** (performance, security, etc.).
|
|
141
|
+
|
|
142
|
+
- Format: `NFR-XXX`
|
|
143
|
+
- Location: `non-functional/`
|
|
144
|
+
- Nature: Normative and binding
|
|
145
|
+
- Purpose: Constrain system qualities
|
|
146
|
+
|
|
147
|
+
---
|
|
148
|
+
|
|
149
|
+
### 5.5 Acceptance Criteria
|
|
150
|
+
|
|
151
|
+
Acceptance criteria define **verifiable outcomes** for functional requirements.
|
|
152
|
+
|
|
153
|
+
- Format: `{FR-XXX}-AC-N`
|
|
154
|
+
- Location: Within each functional requirement file
|
|
155
|
+
- Purpose: Verification anchor
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
## 6. Requirement Identification
|
|
160
|
+
|
|
161
|
+
### 6.1 Identifier Schema
|
|
162
|
+
|
|
163
|
+
| Artifact | Format | Example |
|
|
164
|
+
|-------|-------|--------|
|
|
165
|
+
| Stakeholder Requirement | `StR-XXX` | `StR-001` |
|
|
166
|
+
| User Story | `US-XXX` | `US-002` |
|
|
167
|
+
| Functional Requirement | `FR-XXX` | `FR-014` |
|
|
168
|
+
| Non-Functional Requirement | `NFR-XXX` | `NFR-003` |
|
|
169
|
+
| Acceptance Criteria | `{FR}-AC-N` | `FR-014-AC-1` |
|
|
170
|
+
| Test Case | `TC-XXX` | `TC-021` |
|
|
171
|
+
| Change Request | `CR-XXX` | `CR-009` |
|
|
172
|
+
|
|
173
|
+
Identifiers are immutable once assigned.
|
|
174
|
+
|
|
175
|
+
---
|
|
176
|
+
|
|
177
|
+
## 7. Requirement Quality Policy
|
|
178
|
+
|
|
179
|
+
All **functional requirements** SHALL:
|
|
180
|
+
- Define observable behavior
|
|
181
|
+
- Be unambiguous and atomic
|
|
182
|
+
- Avoid implementation details unless required
|
|
183
|
+
- Be testable through explicit criteria
|
|
184
|
+
|
|
185
|
+
Functional requirements SHALL NOT:
|
|
186
|
+
- Encode application-specific policy
|
|
187
|
+
- Contain compound behaviors
|
|
188
|
+
- Use subjective language
|
|
189
|
+
|
|
190
|
+
---
|
|
191
|
+
|
|
192
|
+
## 8. State and Execution Model
|
|
193
|
+
|
|
194
|
+
### 8.1 State Semantics
|
|
195
|
+
|
|
196
|
+
<System-wide definition of what constitutes a state, terminal state, and transitional state.
|
|
197
|
+
Each managed lifecycle SHALL have a corresponding FR with `domain: state_machine`
|
|
198
|
+
in `spec/functional/` providing the canonical parseable definition.>
|
|
199
|
+
|
|
200
|
+
### 8.2 Transition Semantics
|
|
201
|
+
|
|
202
|
+
<System-wide rules for valid transitions, guards, and invalid transitions.>
|
|
203
|
+
|
|
204
|
+
### 8.3 Determinism Guarantees
|
|
205
|
+
|
|
206
|
+
<Statements about execution order, determinism, and concurrency assumptions.>
|
|
207
|
+
|
|
208
|
+
---
|
|
209
|
+
|
|
210
|
+
## 9. Events and Signals
|
|
211
|
+
|
|
212
|
+
### 9.1 Event Model
|
|
213
|
+
|
|
214
|
+
<Overview of domain events. Each service SHALL have at least one event catalog FR
|
|
215
|
+
with `domain: event` in `spec/functional/` defining canonical event types and schemas.>
|
|
216
|
+
|
|
217
|
+
### 9.2 Event Guarantees
|
|
218
|
+
|
|
219
|
+
- Ordering guarantees
|
|
220
|
+
- Delivery guarantees
|
|
221
|
+
- Failure semantics
|
|
222
|
+
|
|
223
|
+
---
|
|
224
|
+
|
|
225
|
+
## 10. Error and Failure Model
|
|
226
|
+
|
|
227
|
+
### 10.1 Error Classification
|
|
228
|
+
|
|
229
|
+
- Configuration errors
|
|
230
|
+
- Runtime execution errors
|
|
231
|
+
- Invalid transition attempts
|
|
232
|
+
|
|
233
|
+
### 10.2 Failure Handling Guarantees
|
|
234
|
+
|
|
235
|
+
<System-wide expectations for error propagation, recovery, and reporting.>
|
|
236
|
+
|
|
237
|
+
---
|
|
238
|
+
|
|
239
|
+
## 11. Traceability
|
|
240
|
+
|
|
241
|
+
Bidirectional traceability SHALL be maintained between:
|
|
242
|
+
- Stakeholder Requirements → User Stories / Functional Requirements
|
|
243
|
+
- User Requirements → Functional Requirements
|
|
244
|
+
- Functional Requirements → Acceptance Criteria
|
|
245
|
+
- Acceptance Criteria → Test Cases
|
|
246
|
+
|
|
247
|
+
Traceability is recorded in `traceability_matrix.md`.
|
|
248
|
+
|
|
249
|
+
---
|
|
250
|
+
|
|
251
|
+
## 12. Verification Strategy
|
|
252
|
+
|
|
253
|
+
Functional requirements SHALL be verified using one or more of:
|
|
254
|
+
- Automated tests
|
|
255
|
+
- Manual tests
|
|
256
|
+
- Analysis
|
|
257
|
+
- Inspection
|
|
258
|
+
|
|
259
|
+
Verification evidence SHALL reference test cases in `test_cases/`.
|
|
260
|
+
|
|
261
|
+
---
|
|
262
|
+
|
|
263
|
+
## 13. Change Management
|
|
264
|
+
|
|
265
|
+
All requirements artifacts are **configuration-controlled items**.
|
|
266
|
+
|
|
267
|
+
- Changes are proposed via change requests (`CR-XXX`)
|
|
268
|
+
- Changes require impact analysis
|
|
269
|
+
- Approved changes update affected requirements, tests, and traceability
|
|
270
|
+
- Historical versions are preserved
|
|
271
|
+
|
|
272
|
+
---
|
|
273
|
+
|
|
274
|
+
## 14. Lifecycle Status
|
|
275
|
+
|
|
276
|
+
Functional requirements MAY declare a lifecycle status:
|
|
277
|
+
- DRAFT
|
|
278
|
+
- APPROVED
|
|
279
|
+
- IMPLEMENTED
|
|
280
|
+
- VERIFIED
|
|
281
|
+
- DEPRECATED
|
|
282
|
+
|
|
283
|
+
---
|
|
284
|
+
|
|
285
|
+
## 15. Governance Notes
|
|
286
|
+
|
|
287
|
+
- This document defines **system intent**, not implementation
|
|
288
|
+
- Functional requirements SHALL precede code changes
|
|
289
|
+
- Proof-of-concept code SHALL only exist when explicitly requested
|
|
290
|
+
- Deprecated requirements SHALL be archived, not removed
|
|
291
|
+
|
|
292
|
+
---
|
|
293
|
+
|
|
294
|
+
## 16. References
|
|
295
|
+
|
|
296
|
+
- ISO/IEC/IEEE 29148 — Requirements Engineering
|
|
297
|
+
- IEEE 828 — Configuration Management
|
|
298
|
+
|
|
299
|
+
---
|