spec-system-plugins

docs-spec-system

Contract-first specs for long-horizon AI software delivery.

What This Is • Quickstart • Workflow • Epics & One-shot • Agent Setup • CLI

What This Is

docs-spec-system gives teams a deterministic spec workflow that scales with AI-assisted development.

It keeps planning and execution synchronized with strict traceability and gated approvals:

• R -> D -> T -> S -> evidence
• EARS + RFC requirement quality checks
• Contract-change docs for downstream repository coordination
• Epic one-shot runtime with blocker policies and finalize gates
• Generated product map and traceability reports

What ships in this repo

Module	Purpose
specctl CLI	Bootstrap, lint/render/check, approvals, migration, epic + one-shot orchestration
skills/docs-spec-system/	Codex/Claude skill pack with rules, workflows, and templates
.claude-plugin/	Claude Code plugin packaging
tests/	Unit + integration tests for lifecycle and runtime integrity

Quickstart

Install

git clone https://github.com/dana0550/spec-system.git
cd spec-system
python -m pip install -e .

Bootstrap a new specs workspace

specctl init
specctl feature create --name "User Authentication" --owner [email protected]
specctl render
specctl check

Validate quality gates

specctl lint --strict
specctl render --check
specctl check --strict

Workflow

Feature workflow (phase-gated)

1. requirements_draft -> requirements_approved
2. requirements_approved OR design_draft -> design_approved
3. design_approved OR tasks_draft -> tasks_approved
4. implementing -> verifying -> done

Before each phase approval, refresh and scan impact for the feature:

specctl impact refresh --feature-id F-###
specctl impact scan --feature-id F-###
specctl approve --feature-id F-### --phase requirements

specctl impact refresh --feature-id F-###
specctl impact scan --feature-id F-###
specctl approve --feature-id F-### --phase design

specctl impact refresh --feature-id F-###
specctl impact scan --feature-id F-###
specctl approve --feature-id F-### --phase tasks

Each feature lives in docs/features/F-###-<slug>/:

• requirements.md
• design.md
• tasks.md
• verification.md

Contract change workflow

Create a contract change artifact when launching a new service or evolving existing service/API behavior:

specctl contract create \
  --name "Fraud Scoring Service Standup" \
  --owner [email protected] \
  --change-type service_added

Contract changes live in docs/contracts/CC-###-<slug>.md and are tracked in docs/CONTRACT_CHANGES.md. Statuses are manually edited (draft|approved|published|closed) and validated by specctl check. --change-type is required so change intent is always explicit. Use change_type: service_added for new service launch notifications and change_type: service_changed for service interface/behavior evolution. Track target-repo PR rollout in the standard Downstream Notification Context table (repo | owner | context | pr_url | state).

Core invariants

• Requirements use EARS trigger terms and RFC modal keywords.
• Acceptance scenarios use Gherkin shape (Given/When/Then).
• IDs are immutable once assigned.
• Traceability chain is complete before completion.
• Generated docs remain deterministic for identical inputs.

flowchart LR
  A["requirements"] --> B["design"]
  B --> C["tasks"]
  C --> D["verification"]
  D --> E["traceability report"]

Epics and One-shot

Epics are orchestration units with first-class runtime control.

Epic create

specctl epic create \
  --name "Billing Reliability" \
  --owner [email protected] \
  --brief ./brief.md \
  --mode agentic

Required brief sections: