Skip to content

Adopt the repository specification standard: SPEC.md #82

Description

@PaulSnow

Every repository under active development carries a normative SPEC.md.

Standard: https://github.com/PaulSnow/tracking_repo/blob/main/docs/standards/spec-driven-development.md
Reference implementation: adex documents/SPEC.md

Requirements:

  • SPEC.md in the repo's documentation directory (documents/ or docs/, whichever the repo uses; create docs/ if neither). Never at the repository root.
  • Two sections:
    1. Architecture — what we are doing: purpose, surfaces, objects, invariants. Readable without the code.
    2. Specification — how it is implemented: layout, components, interfaces, data flows, deployment. Every architectural claim in section 1 traces to a mechanism in section 2.
  • CLAUDE.md opens with the normative hook:
    • ALL work is done against the spec — read the relevant section first; a change that contradicts the spec means fixing the spec or the plan first.
    • New work requires updating the spec — same MR/change set, not "later".

Acceptance:

  • SPEC.md written (both sections), describing the system as it is
  • CLAUDE.md hook added
  • Gaps found while writing the spec filed as issues, not silently fixed

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions