Skip to content

SPEC-DRIVEN-DEVELOPMENT.md

Latest commit

 

History

History
120 lines (80 loc) · 6.96 KB

SPEC-DRIVEN-DEVELOPMENT.md

File metadata and controls

120 lines (80 loc) · 6.96 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 TranslationYamlToolsBundle 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 translator, I want nested YAML flattened/sorted so that diffs in translation PRs stay readable.
US-02 As a translator, I want machine translation for missing keys so that I bootstrap locales via Google/DeepL/LibreTranslate.
US-03 As an integrator, I want Symfony console commands so that I run tools in CI and locally without custom scripts.
US-04 As a maintainer, I want PHPUnit on parsers so that YAML round-trips do not corrupt keys.
US-05 As a contributor, I want REQ-* anchors on scripted flows so that PRs cite the same identifiers as this document.
US-06 As a maintainer, I want optional runtime missing-key logging and a Web UI so that I triage untranslated strings discovered in dev/staging.

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: Symfony developer tools for YAML translations: path discovery, nested tree conversion, key sorting, audit reports, machine translation for missing keys (Google, DeepL, LibreTranslate; pluggable), and optional Doctrine-backed missing translation log with CLI + Web UI.

In scope

  • Console commands: tree, flatten, sort, fill-missing, audit, and missing-log maintenance commands.
  • MachineTranslatorInterface backends and locale routing configuration.
  • Optional missing_translation_log feature: translator decorator, async flush (Messenger or EventDispatcher), Doctrine entity, CLI, and gated Web UI routes.
  • Documented integration (see root README.md and docs/).
  • Configuration and runtime behavior described in CONFIGURATION.md and USAGE.md.
  • Consumer-facing change notes in CHANGELOG.md and UPGRADING.md when applicable.

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