Skip to content

SPEC-DRIVEN-DEVELOPMENT.md

Latest commit

 

History

History
116 lines (76 loc) · 6.5 KB

SPEC-DRIVEN-DEVELOPMENT.md

File metadata and controls

116 lines (76 loc) · 6.5 KB
Raw

Spec-driven development

In this repository, spec-driven development has three layers that stay in sync:

  1. GitHub Spec Kit baseline — specs/001-baseline/ (spec.md, code-inventory.md), initialized with GitHub Spec Kit (.specify/, Cursor Agent skills in .cursor/skills/speckit-*). The inventory maps 100% of production code in src/. How to install, initialize, and use Spec Kit: SPEC-KIT.md.
  2. Product behavior — what CodeReviewGuardian guarantees to applications that integrate it (see USAGE.md, CONFIGURATION.md, INSTALLATION.md). PHPUnit and PHPStan enforce contracts in CI where applicable.
  3. Traceability anchors — stable REQ-* identifiers in Makefiles and demos (when present) so changes to scripts, ports, and demo workflows stay discoverable from issues and PRs.

There is no separate executable spec language (for example Gherkin); tests and static analysis are the mechanical proof alongside this document.

User stories

The sections below state behavior; this subsection states intent in backlog-friendly form.

ID Story
US-01 As a integrator, I want to install and enable this package so that I can rely on documented services, configuration, and extension points.
US-02 As an integrator, I want stable configuration keys and defaults so that upgrades remain predictable (see CONFIGURATION.md).
US-03 As an integrator, I want clear usage guidance so that I can integrate features without reverse-engineering internals (see USAGE.md).
US-04 As a maintainer, I want behavior changes covered by automated tests so that regressions are caught in CI.
US-05 As a contributor, I want REQ-* anchors on scripted flows so that PRs and issues cite the same identifiers as this document.

Out of scope for these stories: guarantees outside the stated public API and outside dependency limits (PHP, Symfony, third-party libraries).

Bundle functional scope

Goal: Provider-agnostic code review guardian for PHP projects. Works with any PHP project (Symfony, Laravel, Yii, CodeIgniter, etc.) and any Git provider (GitHub, GitLab, Bitbucket, etc.)

In scope

Explicit non-goals

  • Behavior not documented here or in linked integrator docs.
  • demo/ trees: illustrative unless a path is explicitly published as stable API in this document.

Demos (if present): examples only; not part of the Packagist contract unless services or contracts are explicitly documented as stable.

Validating the functional spec

  • Run composer qa and/or make qa / make release-check as documented in CONTRIBUTING.md (Docker-based flows may apply).
  • Run PHPUnit and PHPStan in CI and locally for code changes.
  • New or changed behavior should add or adjust tests under tests/ (or the repo’s documented test layout) rather than relying on prose alone.

Requirement identifiers (REQ-*)

ID Where What it marks
(none yet) Makefile, demo/**/Makefile Add REQ-* comments next to targets when scripted behavior must stay traceable; document each ID here.

When you change scripted behavior, update the existing REQ-* comment if the ID still matches the rule, or add a new REQ-* and document it here and in the PR description.

Suggested workflow for contributors

  1. Clarify behavior in an issue or draft PR: acceptance criteria for the product and, if relevant, Makefiles/demos (REQ-*).
  2. Implement with tests and static analysis.
  3. Anchor scripts and demos when dev UX changes: add or adjust REQ-* comments and this table.
  4. Ship integrator docs when behavior or configuration changes: USAGE.md, CONFIGURATION.md, CHANGELOG.md, and UPGRADING.md when consumers must change code or config.
  5. Keep Spec Kit artifacts in sync when production code under src/ changes:

GitHub Spec Kit (summary)

This repository uses GitHub Spec Kit with Cursor Agent (cursor-agent integration).

Artifact Path
Operator manual (install, init, usage) SPEC-KIT.md
Baseline spec specs/001-baseline/spec.md
Code inventory (100%) specs/001-baseline/code-inventory.md
Constitution .specify/memory/constitution.md
Cursor Agent skills .cursor/skills/ (speckit-*)

Quick start (maintainers):

# Install Specify CLI (once per machine) — see SPEC-KIT.md
specify init --here --force --integration cursor-agent --script sh
specify integration list   # Cursor → installed (default)

In Cursor Agent, start a new feature with /speckit-specify <description>. For day-to-day tooling details, skills reference, folder layout, and troubleshooting, read SPEC-KIT.md.

Relationship to Engram / external checklists

ENGRAM.md covers Nowo-wide documentation checklist items. This document ties together what the package does, how we verify it, and local REQ-* habits. Both coexist: Engram for org-level compliance, this file for product + traceability expectations.

See also