Skip to content

README.md

Latest commit

 

History

History
77 lines (51 loc) · 5.07 KB

README.md

File metadata and controls

77 lines (51 loc) · 5.07 KB
Raw

Specs — the canonical spec home

This directory is the single source of truth for cross-repo specifications in Plattar Stack 2.0. It lives in the umbrella repo (plattar-platform) because the work it describes spans multiple pillars (renderer, plattar-components, viewer, cms) and must not be owned by any one of them.

Two kinds of artifacts live here, and they have different lifecycles:

  1. Feature specs — specs/NNN-slug/ folders, one per cross-repo feature. These are produced and consumed by the /speckit-* skills and are scoped to a single piece of work. They are born, implemented, and then frozen as a historical record.
  2. Standing contracts — specs/contracts/. These define the long-lived interfaces between pillars. They outlive any single feature; features change them, but they are never "done".

If you are about to start a feature, read docs/feature-workflow.md first — it defines the end-to-end cross-repo flow. This README only explains how the artifacts are laid out on disk.

Feature specs: specs/NNN-slug/

Every cross-repo feature gets exactly one folder here, named NNN-slug — a zero-padded three-digit number plus a short kebab-case slug, for example specs/042-room-presets/.

Why centralised numbering

GitHub Spec Kit keys its state off the git branch name and auto-assigns feature numbers per-repo. If each submodule numbered features independently, the same feature would get a different number in every repo, and /speckit-* state would collide across the stack.

We avoid this by assigning the NNN-slug once, centrally, here, and then reusing the identical string everywhere downstream:

  • the feature folder: specs/NNN-slug/
  • the git branch in every affected submodule: feat/NNN-slug
  • the PR title and issue labels in every affected submodule

One feature ID, fanned out across repos. See docs/feature-workflow.md for the exact commands and merge order.

What goes in a feature folder

The /speckit-* skills generate these artifacts. Commit all of them — they are the durable record of the decision, not throwaway scaffolding. Never gitignore spec artifacts.

File Produced by Purpose
spec.md /speckit-specify (refined by /speckit-clarify) What we're building and why — requirements, scope, acceptance criteria. No implementation detail.
plan.md /speckit-plan How we'll build it — the per-repo technical plan and design decisions.
tasks.md /speckit-tasks The dependency-ordered, actionable task list /speckit-implement executes.
feature-specific contracts /speckit-plan Any interface a feature introduces that is local to that feature. Promote to specs/contracts/ only once it becomes a standing cross-pillar interface.

/speckit-analyze and /speckit-checklist produce review/consistency outputs over these artifacts; commit those too when they add durable value.

A typical folder:

specs/
  042-room-presets/
    spec.md
    plan.md
    tasks.md
    checklist.md          # optional, from /speckit-checklist
    contracts/            # optional, feature-local interfaces
      preset-payload.md

Standing contracts: specs/contracts/

These define the interfaces between the four pillars — the seams across which the dependency order (@plattar/renderer → @plattar/react-components → { viewer, cms }) is actually enforced. A change to one of these is, by definition, a coordinated multi-repo change and should go through the cross-repo feature flow.

Contract What it governs
contracts/renderer-api.md The @plattar/renderer public surface: the typed programmatic engine API and the <plattar-embed> web component — the typed replacement for the legacy postMessage messenger.
contracts/design-tokens.md The frozen --theme-* / --font-heading CSS-variable layer that lets host apps and the CMS rebrand @plattar/react-components at runtime.
contracts/scene-schema.md The scene / product / variation data model the CMS produces and the renderer consumes, including units and coordinate conventions.

All three are currently Draft. They define the shape and the open questions; concrete APIs are filled in per-feature via /speckit-plan. See each contract's own Open questions section for what remains undecided.

Related docs