Skip to content

README.md

Latest commit

 

History

History
121 lines (103 loc) · 7.32 KB

README.md

File metadata and controls

121 lines (103 loc) · 7.32 KB

Specflow v1.0 — Planning Documents

This directory contains the planning, architecture, and design documents for transforming Specflow from a repository of scripts into a standalone, installable CLI tool.

Start here: Master Execution Plan

Document Index

Plan

Document Description
MASTER-PLAN.md Top-level execution plan with 6 phases, dependencies, risks, and success metrics

PRDs (Product Requirement Documents)

Document Phase Description
PRD-001: CLI Rewrite 2 Replace bash scripts with Node.js CLI commands
PRD-002: MCP Server 3 Stdio MCP server exposing contract tools to Claude Code
PRD-003: Installation & Packaging 4 One-line install, clean npm package, global CLI
PRD-004: Agent System 5 Agent frontmatter, registry, CLI commands, MCP tools
PRD-005: Knowledge Embedding 9 Skill, MCP tools, new agent, agent enrichment, hook enhancement
PRD-006: Knowledge Graph 10 sql.js knowledge graph, violation recording, fix tracking, skill discovery, MCP graph tools
PRD-007: Incremental Enforcement & PR Compliance 11a/b/d --staged, --diff, --suggest flags, PR compliance reports
PRD-008: Contract Creation 11c specflow contract create with template and AI modes
PRD-009: Contract Packages 11e Shareable contract packages via npm: add, remove, publish
PRD-010: Spec Integrity Toolkit 12 spec_coupling contracts, frontmatter schema, review/snapshot/migrate-docs commands
PRD-011: Spec Integrity v1.1 13 Correctness hardening, Document entity, lifecycle verbs, traceability, YAML security

ADRs (Architecture Decision Records)

Document Decision
ADR-001: Repository Structure Clean root, move docs, remove sample apps
ADR-002: Node.js Over Bash Rewrite all bash scripts in Node.js, eliminate jq dependency
ADR-003: CLI Architecture Single entry point, mode detection, no CLI framework dependency
ADR-004: MCP Server Design Stdio JSON-RPC, minimal protocol, reuse contract engine
ADR-005: Agent Registry YAML frontmatter on agent files, runtime index, no manifest file
ADR-006: Knowledge as Components Embed knowledge in skills, agents, MCP tools, and hooks instead of static docs
ADR-007: Knowledge Graph (Amended) Use sql.js (WASM SQLite) as knowledge graph storage layer; AgentDB deferred to future stable release
ADR-008: Incremental Enforcement Add --staged and --diff flags to enforce command for git-scoped scanning
ADR-009: Contract Packages Contract packages distributed via npm with specflow field in package.json
ADR-010: Specs as Enforced Artefacts Documentation becomes a first-class enforceable category via spec_coupling
ADR-011: Document Lifecycle and Frontmatter Schema YAML frontmatter, status lifecycle (Draft/Accepted/Superseded/Deprecated), version snapshots
ADR-012: Bidirectional Document Linking implements/implemented_by reciprocity, validated and auto-fixed by doctor
ADR-013: Correctness Hardening Repo-relative paths, minimatch, fail-loud git diff, rule-scoped overrides, atomic writes
ADR-014: Document Entity + Type Registry Promote Document to real entity; central DocumentTypeRegistry; transitionTo with state-machine enforcement
ADR-015: Lifecycle Verb Family specflow doc accept/supersede/deprecate/bump/stamp/revive — atomic lifecycle transitions
ADR-016: Contract-Root Traceability specflow audit --contract, typed links (tests/blocks/contradicts), owners field, review --html
ADR-017: YAML Security Hardening FAILSAFE schema, reject anchors/duplicate-keys/proto tags, body↔frontmatter consistency

DDDs (Domain Design Documents)

Document Domain
DDD-001: Contract Engine YAML loading, regex compilation, file scanning, violation reporting
DDD-002: Enforcement Pipeline Git/build/edit/CI gates, hook protocol, journey enforcement, deferrals
DDD-003: Agent Registry Agent discovery, search, contract context injection
DDD-004: Knowledge Graph Graph model, domain services, SQL query patterns, sql.js integration
DDD-005: Incremental Enforcement Git integration, file filter pipeline, baseline comparison, domain model
DDD-006: Contract Packages Package lifecycle, conflict resolution, registry interaction, domain model
DDD-007: Spec Integrity Domain Document entity, lifecycle state machine, link graph, coupling enforcement, snapshot ledger
DDD-008: Document Lifecycle Domain Document entity behaviour, DocumentTypeRegistry, LifecycleOrchestrator, AuditLog, state-machine enforcement

Simulation Reports

Document Features Edge Cases
SIMULATION-REPORT.md Phase 8 — Full user journey 7 edge cases
SIMULATION-REPORT-2.md Phase 11 — 5 new features 38 edge cases

Phase Dependencies

Phase 1: Clean Foundation (ADR-001)
    |
    v
Phase 2: CLI Rewrite (PRD-001, ADR-002, ADR-003, DDD-001, DDD-002)
    |           |
    v           v
Phase 3:     Phase 4:
MCP Server   Install Script
(PRD-002,    (PRD-003)
 ADR-004)
    |           |
    v           v
Phase 5: Agent System (PRD-004, ADR-005, DDD-003)
    |
    v
Phase 6: Documentation & Polish
    |
    v
Phase 7: Rust Native Engine (if applicable)
    |
    v
Phase 8: Simulation Fixes (BLOCKING v1.0)
    |
    v
Phase 9: Knowledge Embedding (PRD-005, ADR-006)
    |
    v
Phase 10: Knowledge Graph via sql.js (PRD-006, ADR-007 Amended, DDD-004)
    |
    v
Phase 11: Best-in-Class Features (PRD-007/008/009, ADR-008/009, DDD-005/006)
    |-- 11a: Incremental Enforcement (--staged, --diff)
    |-- 11b: Auto-Fix Suggestions (--suggest)
    |-- 11c: Contract Creation
    |-- 11d: PR Compliance Report
    |-- 11e: Contract Packages
    |
    v
v1.0 Release