Step-by-step setup for a new developer (or a Claude agent) joining Plattar Stack 2.0. By the end you will have the whole stack cloned, the Spec Kit CLI installed, the existing pillars running locally, and a clear picture of the day-to-day spec-driven workflow.
Read these first — in this order:
- .specify/memory/constitution.md — the non-negotiable engineering principles.
- shared-config.md — pinned tool versions, conventions, and the canonical config every repo inherits.
- README.md — the umbrella overview and repo map.
- docs/architecture.md — how the four pillars fit together.
Then come back here and follow the steps below.
This is a Windows shop; commands below are PowerShell-friendly. Install and verify each tool before continuing.
| Tool | Required | Used here | Purpose | Verify |
|---|---|---|---|---|
| git | 2.x | 2.50 | Clone + submodules | git --version |
| gh (GitHub CLI) | 2.x | 2.76 | PRs, issues, repo ops — must be authenticated | gh --version && gh auth status |
| Node.js | 18+ | 22 | Runtime for both apps and both npm packages | node --version |
| npm | 9+ | 10 | Package manager | npm --version |
| Python | 3.11+ | 3.13 | Runtime backing the Spec Kit CLI | python --version |
| uv | 0.11+ | 0.11 | Installs/runs the Spec Kit CLI as a tool | uv --version |
Git protocol is SSH in this org. Confirm your auth before cloning:
gh auth status # should show: Logged in to github.com ... (SSH)
ssh -T git@github.com # should greet you by GitHub usernameIf gh auth status is not logged in, run gh auth login (choose GitHub.com, SSH) before proceeding.
We use GitHub Spec Kit for spec-driven development, pinned to v0.11.5. Install it once as a uv tool:
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v0.11.5
specify --versionspecify --version should report the pinned 0.11.5. The CLI is global once installed; you do not reinstall it per repo.
Spec Kit is initialised per repo with the Claude integration and PowerShell scripts:
specify init --integration claude --script psThis installs the /speckit-* commands as skills under .claude/skills/ plus PowerShell helpers under .specify/scripts/powershell/. The umbrella repo (this one) is already initialised — you only run specify init inside a pillar when scaffolding a new pillar (see docs/feature-workflow.md).
Clone the umbrella repo with submodules — this pulls every pillar at the SHA the umbrella pins:
git clone --recurse-submodules git@github.com:Plattar/plattar-platform.git
cd plattar-platformIf you already cloned without --recurse-submodules, fetch the submodules afterwards:
git submodule update --init --recursiveEach pillar is an independent repo with its own remote, CI, branches, and release cadence — the umbrella just pins each at a commit SHA. After a git pull on the umbrella, re-sync submodule pointers with git submodule update --init --recursive.
Repository layout once cloned:
plattar-platform/ # umbrella: constitution, cross-repo docs + specs
├── .specify/memory/constitution.md
├── docs/ # you are here
├── specs/ # canonical cross-repo specs + contracts
├── plattar-renderer-sdk/ # submodule -> Plattar/plattar-renderer-sdk (NEW)
├── plattar-components/ # submodule -> Plattar/plattar-components (EXISTING)
├── plattar-viewer/ # submodule -> Plattar/plattar-viewer (EXISTING)
└── plattar-cms/ # submodule -> Plattar/plattar-cms (NEW)
See docs/architecture.md for what each pillar does and docs/glossary.md for terminology.
Two pillars exist today and run immediately; two are greenfield and are scaffolded later. Pillar deep-dives live under docs/pillars/.
The shared component library + the CSS-variable theming bridge. See docs/pillars/plattar-components.md.
cd plattar-components
npm install
npm run build # Vite library build -> ESM/CJS + .d.ts
npm run storybook # local Storybook for browsing/developing componentsConfirm the exact Storybook script name (
npm run storybook) against the pillar'spackage.json— script names are owned by the pillar. TBD if it differs.
The customer-facing 3D configurator + Room Planner overlay. Consumes @plattar/react-components and embeds the renderer. See docs/pillars/plattar-viewer.md.
cd plattar-viewer
npm install
npm run dev # Next.js dev server (Turbopack) -> http://localhost:3000
npm run build # static export to out/
npm test # Jest unit testsThe Babylon.js renderer SDK that replaces the legacy Three.js renderer + embed shim. Not yet scaffolded — there is no npm install step until it is. When scaffolding begins it follows the standard flow: specify init --integration claude --script ps, then plan the build via /speckit-plan. See docs/pillars/plattar-renderer-sdk.md.
- Run/build commands: TBD — decided per-repo via
/speckit-plan.
The authoring tool for scenes / products / variations. Consumes @plattar/react-components + @plattar/renderer. Not yet scaffolded — same story as plattar-renderer-sdk. See docs/pillars/plattar-cms.md.
- Run/build commands: TBD — decided per-repo via
/speckit-plan.
Dependency / release order:
@plattar/renderer→@plattar/react-components→{ viewer, cms }. Build and release upstream packages before the apps that consume them.
All feature work is spec-driven. With the Claude integration the Spec Kit commands are skills you invoke in Claude Code:
| Skill | What it does |
|---|---|
/speckit-constitution |
Create/update the project constitution |
/speckit-specify |
Write the feature spec from a description |
/speckit-clarify |
Ask targeted questions to fill spec gaps |
/speckit-plan |
Produce the implementation plan + design artifacts |
/speckit-tasks |
Generate the dependency-ordered task list |
/speckit-analyze |
Cross-check spec ↔ plan ↔ tasks for consistency |
/speckit-checklist |
Generate a custom review checklist |
/speckit-implement |
Execute the tasks |
/speckit-converge |
Reconcile the codebase with the spec and append remaining work |
Where things live:
- Constitution (the rules) is central, here in the umbrella: .specify/memory/constitution.md. Pillars point back to it via their own
CLAUDE.mdoverlay and shared-config.md. - Canonical cross-repo specs and contracts are central too, under specs/ — including the renderer API contract, design-tokens contract, and scene-schema contract.
- Per-pillar specs live in each submodule's own
.specify/(Spec Kit keys its state off the git branch name, so each repo runs its own Spec Kit).
Always commit generated spec artifacts (
spec.md/plan.md/tasks.md). Never gitignore them.
One feature usually touches several pillars. The convention: assign one feature ID centrally (e.g. 042-some-feature), reuse it as the branch feat/042-some-feature, the PR title, and issue labels in every affected repo, then merge in dependency order. The full procedure — central ID assignment, fan-out branch creation, one PR per repo, merge order — is in docs/feature-workflow.md. Read it before starting any change that spans more than one pillar.
- Read the rules first. .specify/memory/constitution.md and shared-config.md are mandatory reading before you write code or specs. They override defaults.
- Spec before code. Drive features through the
/speckit-*flow; commit the generatedspec.md/plan.md/tasks.md. - One feature ID, everywhere. Reuse the central ID across branch names, PR titles, and labels in every affected repo. See docs/feature-workflow.md.
- Respect the dependency order.
@plattar/renderer→@plattar/react-components→{ viewer, cms }. Merge and release upstream first. - Ask before committing or publishing. Do not commit, push, open PRs, or publish npm packages without confirmation. npm publishing for
@plattar/react-componentsuses Trusted Publishing (GitHub OIDC) from CI — never publish a stored-token release by hand. - Keep submodules in sync. After pulling the umbrella, run
git submodule update --init --recursive. The umbrella pins SHAs deliberately.
Stuck on something not covered here? Check docs/glossary.md for terminology and the relevant docs/pillars/ page, then ask. Genuinely undecided items are marked TBD and are settled per-repo via /speckit-plan.