Act II · How a change flows
AI Factory · OpenSpec
Spec-driven development, adapted
Six adaptations
1 · Schema fork notaire-sdlc
A fork of the packaged spec-driven schema. Everything OpenSpec parses is unchanged; it adds the Constitution as mandatory context, the required sections per artifact, a traceability artifact (P4), and makes design mandatory (testing, regression, Playwright, deploy and rollback strategy).
2 · Constitution as CLI context
config.yaml holds a pointer and the non-negotiables, not a copy. The CLI injects it intoopenspec instructions for every artifact, so Claude Code, OpenCode, Copilot, Codex and Cursor all receive the same rules through the same channel.
3 · Closing the Explore → Propose gap
Exploration produces findings but no change. A project-owned triage skill turns each finding into a real, estimated, Use-Case-linked Issue, and creates Issues only after confirmation. Only that number may reach/opsx:propose.
4 · Mechanical Gate 1
validate-sdlc-plan.sh checks the mandatory sections, all 12 task groups, the Use Case reference, and that the Issue exists and is open on GitHub. It rejects a section left as a template comment. It runs in the pre-push hook and in PR Validation.
5 · Archive in the PR
The PR that implements a change also archives it, so no active change outlives its merge. Changes continued by later PRs declare multi_pr: true and are archived by the last one. Main Health fails on any leftover.
6 · Traceability that cannot lie
A row in traceability.md that says a permanent document was updated is a claim that the file is in the same diff. check-doc-traceability.py rejects the claim when it is not.
The five artifacts of a change
| Artifact | Carries | Checked by |
|---|---|---|
| proposal.md | Issue, Use Case, branch, objective, what changes, business rules, capabilities, impact analysis, documentation impact, out of scope | validate-sdlc-plan.sh (live Issue) |
| traceability.md | Issue → spec → tasks → commits → PR → merge → release; requirement coverage; docs ledger; gate log | check-doc-traceability.py |
| specs/<capability>/spec.md | ADDED / MODIFIED / REMOVED requirements with #### Scenario: acceptance criteria | openspec validate --strict |
| design.md | Decisions, risks, testing, regression, Playwright, deployment and rollback strategy | schema (mandatory) |
| tasks.md | 12 mandatory groups from Gate 1 to Gate 5 and the Definition of Done | validate-sdlc-plan.sh, archive hygiene |
Commands
cd docs openspec new change "<kebab-name>" # or: bash workspace/sdlc/seed-openspec-change.sh <name> --issue N --create openspec validate <change> --strict # structure bash ../workspace/sdlc/validate-sdlc-plan.sh <change> # Constitution completeness + live Issue openspec instructions <artifact> --change <change> # what any agent receives openspec archive <change> --yes # in the implementing PR