Sample SDD Repo - MathBuddy

A standards-driven development (SDD) course material repo. Follow the phases below to set up and build your venture project.

= Human input required at this step

---

Running the Project

MathBuddy is a Next.js (App Router) app. Source lives in frontend/.

cd frontend
npm install
npm run dev

Then open http://localhost:3000.

---

Phase I — Copy Skills

Clone the course material repo parallel to your project repo, then copy STD-002 (VKF) and STD-001 (SDD) skills, commands, and state into this repo.

Command	What it does
cp -r (manual)	- Copies .claude/skills/venture-foundation/ (VKF skill + 5 reference guides)
	- Copies .claude/commands/vkf/ (12 commands: init, validate, constitution, etc.)
	- Copies .claude/commands/sdd/ (4 commands: start, status, implement, complete)
	- Copies .claude/state/vkf-state.yaml and sdd-state.yaml (tracking state files)

Status: Done — details

---

Phase II — Bootstrap VKF

Run VKF commands to scaffold the knowledge foundation before writing any specs.

Command	What it does
/vkf:init	- Creates specs/constitution/ with 8 template files (mission, pmf-thesis, principles, etc.)
	- Creates specs/features/ directory for feature specs
	- Creates changes/ and archive/ directories for SDD change management
/vkf:constitution	- Interactively fills Core constitution files (mission, pmf-thesis, principles, index)
	- Replaces all [REQUIRED] placeholders with actual product decisions
/vkf:validate	- Audits repo against all 4 STD-002 requirements (structure, constitution, freshness, workflows)
	- Must pass all checks before moving to Phase III

Status: Done — details

---

Phase III — Spec-Driven Development

Adopt STD-001: every behavior-changing feature gets a specification before implementation begins. First cycle: basic-calculator.

Command	What it does
/sdd:start {slug}	- Creates changes/{slug}/ with proposal.md, spec-delta.md, and tasks.md
	- Sets sdd-state.yaml cycle to phase: proposal
	- Commits with [spec] prefix
Fill [REQUIRED] sections	- Review and approve proposal, spec-delta, and tasks before implementation
/sdd:status	- Shows current cycle state, task progress, and unfilled [REQUIRED] placeholders
/sdd:implement	- Reads spec-delta and executes tasks one by one following the spec exactly
	- Marks tasks [x] in tasks.md, transitions state to phase: implementation
	- Commits each task with [impl] prefix
Verify feature	- Test the feature works as specified before completing the cycle
/sdd:complete	- Merges spec-delta into canonical specs/features/ (creates new spec files or updates existing ones)
	- Moves changes/{slug}/ to archive/{slug}/
	- Clears sdd-state.yaml cycle and adds entry to history
	- Commits with [spec] and [archive] prefixes

Status: Done — details

---

➕ ADDING NEW FEATURES

Repeatable playbook for every new feature. Same SDD loop, no exceptions for behavior-changing code.

/sdd:start {slug}  →  fill specs  →  /sdd:implement  →  /sdd:complete

Does this change need a proposal?

Change type	Proposal?	How to handle
Adding new features or functionality	Yes	/sdd:start
Modifying observable behavior	Yes	/sdd:start
Breaking API changes	Yes	/sdd:start
Architecture or security pattern changes	Yes	/sdd:start
Bug fix restoring already-specified behavior	No	Commit with [fix] prefix
Refactor with no behavior change	No	Commit with [refactor] prefix
Quick idea or tech debt	No (yet)	Add to backlog/items.yaml

The cycle

Command	What it does
/sdd:start {slug}	- Refuses to run if the working tree is dirty — commit or stash first
	- Auto-creates and switches to branch {slug} from your current branch (usually main); on collision, tries 001-{slug}, 002-{slug}, …
	- Creates changes/{slug}/ folder with proposal.md, spec-delta.md, and tasks.md
	- proposal.md = what problem and how we solve it
	- spec-delta.md = Given/When/Then scenarios for every requirement
	- tasks.md = implementation checklist
	- All three contain [REQUIRED] placeholders; updates sdd-state.yaml with active cycle slug and phase: proposal
Fill [REQUIRED] sections	- Review and approve the proposal, spec-delta, and tasks Claude drafts
	- Check progress with /sdd:status
	- This is where you shape what gets built — if the spec is wrong, the code will be wrong
/sdd:implement	- Picks next unchecked task from tasks.md and implements it following spec-delta exactly
	- Modifies source files (frontend/), marks task [x], transitions to phase: implementation
	- Commits with [impl] prefix; run multiple times or with --all for all tasks
Verify feature	- Test the feature in the browser or run tests before completing the cycle
/sdd:complete	- Creates new folder in specs/features/ with merged spec from spec-delta
	- Updates existing spec files with MODIFIED sections from spec-delta
	- Moves changes/{slug}/ to archive/{slug}/ (change directory is now empty)
	- Updates sdd-state.yaml: clears active cycle, adds to history array
	- Three commits: [spec] for spec merge, [archive] for move, [state] for cleanup
Open PR & merge (if on a branch)	- Rebase on latest main, resolve any specs/features/ or sdd-state.yaml conflicts, then merge
	- First cycle to merge wins; others must rebase and reconcile their spec-delta against it

What happens if 3 people start the same feature in parallel

Scenario	Outcome	Resolution
All 3 use the same slug on separate branches	changes/{slug}/ path collides; sdd-state.yaml shows different active cycles per branch	Agree on one owner for the slug; others rename to {slug}-v2 or abandon their branch
All 3 use different slugs for the same behavior	Three parallel changes/*/ folders; no git conflict until /sdd:complete touches overlapping specs/features/ files	Last two to merge must rebase, reconcile spec-delta.md against the already-merged spec, and re-run /sdd:complete
First branch runs /sdd:complete and merges to main	specs/features/{feature}/ now exists; sdd-state.yaml history updated	Branches 2 and 3 must git pull --rebase origin main before their own /sdd:complete
Two branches edit the same canonical spec file (e.g. specs/features/calculator/behavior.md)	Merge conflict on /sdd:complete or PR merge	Hand-merge the MODIFIED sections; re-run /vkf:validate to confirm structure is still valid
Two branches both mutate sdd-state.yaml active cycle	YAML merge conflict (only one active cycle slot)	Keep the later branch's cycle entry; append both to history array in chronological order

Example feature ideas for MathBuddy

Slug	Description	Complexity
keyboard-input	Allow typing numbers and operators via keyboard	Low
calculation-history	Show recent calculations in a scrollable list	Medium
percentage-button	Add a % button for percentage calculations	Low
backspace-button	Delete last digit instead of full clear	Low
memory-functions	M+, M-, MR, MC memory storage	Medium
dark-light-toggle	Switch between dark and light themes	Medium

Backlog (optional)

For quick ideas that aren't ready for a full cycle, use the lightweight backlog:

# backlog/items.yaml
items:
  - summary: "Add keyboard input support"
    priority: high
    status: queued
    added: 2026-03-16
  - summary: "Add percentage button"
    priority: medium
    status: queued
    added: 2026-03-16

When ready to build, promote to a full cycle:

1. Set status to in_progress
2. Run /sdd:start {slug}
3. Follow the standard workflow
4. Set backlog status to done on completion