Skip to content

ADR-0004: Adopt Spec-Kit + Master/Trace Pattern for All New Feature Work

Status: Accepted Date: 2026-05-03 Deciders: Architecture team Impacted Repos: All

Context

Multiple repos accumulated documentation sprawl:

  • admin-web-app had 3 PRDs all titled "BookingZone Admin Panel V*", multiple roadmap files, audit notes, and a 332KB todo.md.
  • reservation-api-server had a single 2000-line bookingzone-frappe-context.mdc rule file used as a catch-all "system context".
  • Cross-cutting changes (e.g., adding SSO across 3 repos) had no canonical home; teams duplicated PRDs across repos and they drifted within weeks.

BMAD-style persona workflows worked but produced too many artifacts at scale and didn't address cross-repo coordination.

Decision

Adopt GitHub Spec-Kit as the per-repo methodology, augmented with a master/trace cross-repo spec pattern:

Per-repo

Every repo:

  1. Has .specify/ initialized with Spec-Kit (specify init --here).
  2. Has .specify/memory/constitution.md that inherits from bz-platform-context/constitution/system-constitution.md and adds only repo-specific principles.
  3. Stores feature specs in specs/NNN-<slug>/.
  4. Uses Spec-Kit slash commands (/speckit-specify, /speckit-plan, /speckit-tasks, /speckit-analyze, /speckit-implement).

Cross-repo (master/trace)

Features that touch 2+ repos:

  1. The master spec lives in bz-platform-context/specs/SYS-NNN-<slug>/. It contains: spec.md, plan.md, optional contracts/, repo-impact/<repo>.md per impacted repo, and rollout-checklist.md.
  2. Each impacted repo creates a trace spec in its local specs/ that references the master and contains only repo-local plan + tasks.
  3. PRs in each repo cross-link to the master spec and to sister PRs.

Discipline

  • Bug fixes, refactors < 50 LOC, and dependency upgrades MAY skip the spec workflow but MUST link the PR to the relevant spec or ADR.
  • Constitution updates require a version bump and an Amendment Log entry in the system constitution OR repo constitution as appropriate.
  • Old PRDs / roadmap markdowns are archived to docs/archive/ per repo; new requirements live exclusively in specs/ and bz-platform-context/specs/.

Consequences

Positive

  • One place per feature: spec folder is the canonical home.
  • /speckit-analyze mechanically catches drift between spec, plan, tasks.
  • Cross-cutting features have one master, eliminating duplication.
  • Onboarding: new engineer reads the constitution + glossary + recent specs; full picture in <2 hours instead of <2 weeks.

Negative / Trade-offs

  • Cultural shift: "write spec before code" requires discipline.
  • Slight up-front cost per feature (offset by faster downstream work).
  • Two-place look-ups for cross-cutting features (master + trace).

Risks / Mitigations

  • Risk: master and trace specs drift over time. Mitigation: trace specs reference master via path; PR templates require both links.
  • Risk: developers bypass spec for "small" changes that turn out to be significant. Mitigation: PR review checklist includes "is this bigger than 50 LOC / cross-cutting?"; CI lints flag missing spec links on large diffs.

Alternatives Considered

  • BMAD-Method only: rejected; doc sprawl symptoms confirmed in admin-web-app.
  • Custom internal framework: rejected; reinvents Spec-Kit at higher cost.
  • Confluence-only specs: rejected; specs must live next to code for agent context and version control.

Implementation Notes

  • Pilot repo: admin-web-app (PoC complete on branch spec-kit-poc).
  • Subsequent rollout: customer-web-app, venuplus-app, reservation-api-server (with BMAD coexistence on the latter).
  • AGENTS.md template in repo-registry.

References

  • system-constitution.md Principle V
  • GitHub Spec-Kit: https://github.com/github/spec-kit
  • BMAD-Method (legacy framework, retained for brownfield documentation): https://github.com/bmad-code-org/BMAD-METHOD