Welcome to criisp.fm

Day-one checklist

• Install Cursor (Mac Universal) and Node.js 22 LTS
• Ask Garett to invite you to the private repo garettwoolley/criisp-fm
• Clone, install, run — commands are in IDE setup
• Open the live Scrum board: Sprint 1 milestone (public) · after access, product Sprint 1
• Walk DEMO.md once on localhost:3000
• Run npm run lint, npm test, npm run audit
• Read the always-on Cursor rule .cursor/rules/criisp.mdc

1. Language selection

We write the product in TypeScript (strict) on React 19 and Next.js 16 App Router, with Tailwind CSS v4 and Zustand for deck state. Audio is vanilla Web Audio — not a React library.

We do not use Python, Go, or a separate API repo. There is no backend in the MVP. Mix files never leave the browser tab.

2. IDE selection and setup

The team IDE is Cursor. Download the Mac build from the official page (not a random mirror):

https://cursor.com/download → macOS → Universal

Setup (do this in order)

1. Install Cursor and sign in (Agent will not run without it).
2. File → Open Folder → the criisp-fm clone (not the parent criisp folder).
3. Install the recommended extensions when prompted: Prettier and ESLint. They are listed in .vscode/extensions.json.
4. Confirm format-on-save. We already checked this in .vscode/settings.json: editor.defaultFormatter = esbenp.prettier-vscode and ESLint fix on save.
5. Terminal:

git clone https://github.com/garettwoolley/criisp-fm.git
cd criisp-fm
git checkout v2
npm install
npm run dev

App: http://localhost:3000 · this playbook locally: http://localhost:3000/playbook

VS Code is allowed only if GitHub Copilot and other agents are off. Approved AI is Cursor Tab + Cursor Agent in this repo — see §6. We do not mix agent products.

3. Development strategy — Scrum

We run Scrum, not Kanban. That is a process choice, not a tooling accident. The product is a web MVP, but we still want a frozen sprint goal so interview insights do not thrash the deck mid-week. New learning goes on the Product Backlog and waits for the next Sprint Planning (class: changes during a sprint are discouraged).

Roles (class: Product Owner, Development Team, Scrum Master)

Cadence

• Sprint length: 1 week, Monday 09:00 MT → Friday 16:00 MT.
• Current sprint: Sprint 1 — Oct 13–17, 2026 (due 17 Oct 2026). Same milestone on the private product repo after you are invited: criisp-fm/milestone/1.
• Sprint 1 Goal: a new engineer can clone the repo, run the quality gate, and find committed work on the board.
• Estimate: Fibonacci 1 / 2 / 3 / 5 / 8. Sprint 1 capacity is 8 points (playbook 5 + CI 3).
• Scope freeze: if a user interview on Wednesday changes our mind, it becomes a Product Backlog item for Sprint 2. We do not add it to Sprint 1.

Meetings (class: the five Scrum events)

Definition of Done

• Issue is on the current sprint milestone
• PR into v2 (until v2 merges to main)
• CI green: lint, Prettier, Vitest, npm audit --omit=dev, build
• Review from CODEOWNERS (@garettwoolley)
• If you touched the deck, DEMO.md still plays
• Feature branch deleted after squash-merge

4. Git strategy and controls

Branching is GitHub Flow (class: short-lived feature branch → pull request → main; best fit for SaaS / startups). We are not running Git Flow — there is no develop, release-*, or hotfix-* branch.

Reality check: production-ready history lives on main. The live product line is v2 until that work is merged. Branch every story off v2 until the Scrum Master says otherwise.

git checkout v2
git pull origin v2
git checkout -b feat/persist-shelf
# ... commits ...
git push -u origin HEAD
gh pr create --base v2 --title "feat(shelf): persist cassettes in OPFS"

Commit convention

Conventional Commits, imperative, scoped:

feat(deck): drag cassette into the candidate well
fix(audio): keep A/B crossfade at 3ms equal-power
docs(playbook): add Sprint Review time
test(timecode): clamp negative seconds to zero
chore(deps): bump next to 16.3.8

Review / approval controls

• Do not commit to main or v2 directly.
• One approving review from .github/CODEOWNERS (@garettwoolley).
• CI on every PR: .github/workflows/ci.yml (lint, format, test, audit, build).
• Use the PR template .github/PULL_REQUEST_TEMPLATE.md — paste the issue URL.
• Squash merge. Delete the branch.
• Never force-push main or v2. Never commit .env*, mix wav/aiff files, or API keys.
• Pre-commit hook (Husky) runs npx lint-staged — Prettier + ESLint on staged files. Do not skip hooks (--no-verify) unless the Scrum Master agrees in the Daily Scrum.

5. Issue tracking

Tool: GitHub Issues. A sprint is a milestone. Columns are labels matching the class Scrum board (Product Backlog / Sprint Backlog / In Progress / Blocked / Done).

Live Sprint 1 board (open this): https://github.com/garettwoolley/criisp-fm-playbook/milestone/1

The product repo is private, so the public playbook repo carries the board a classmate or professor can open without an invite. After you are added to garettwoolley/criisp-fm, use the same Sprint 1 there: https://github.com/garettwoolley/criisp-fm/milestone/1.

File new work with New issue → User story. Do not drop work onto In Progress yourself during the week — that is a sprint change. Raise it in Daily Scrum; the PO parks it on the Product Backlog.

6. AI agents and controls

We are at class Stage 2: agents help us develop, with different jobs, inside one product (Cursor). We are not Stage 3 (cost-routed fleet wired to logs).

How to use Agent on a sprint item

1. Inspect / Plan (higher care): paste the GitHub issue URL, ask Agent to read DEMO.md and .cursor/rules/criisp.mdc before it edits.
2. Implementation: Agent writes the diff. You stay on a feat/… branch.
3. Test / verification: Agent must run npm test and npm run lint. If it did not, you do.
4. Code review: you re-read every hunk. Say so in the PR template’s Agent notes.

The always-apply Cursor rule is .cursor/rules/criisp.mdc. Hard lines: no backend unless the ticket says so; no AudioContext in React state; hardware colors #F8F5F0 / #111215 / #FF4800; rounded-none on chassis controls.

7. Code quality

8. Testing frameworks

Class listed five startup test types. We are explicit about which ones exist today versus later.

npm test          # vitest run
npm run test:watch

Testing fits Scrum here: a story is not Done if CI’s Vitest job is red, and a deck story is not Done if DEMO.md fails in Review.

9. Other controls, tools, and procedures

Run, build, Node

package.json engines: node >= 20. CI uses Node 22. Install from nodejs.org.

npm run dev      # http://localhost:3000
npm run build    # required before you call a story Done
npm start        # production server locally

Infrastructure / deploy (class: host + how it is created)

Today: local only. Mix File objects live in Zustand; a refresh clears the shelf. When share ships we will outsource infra to Vercel (class Option 3 — not hand-rolled Terraform). One project, linked to garettwoolley/criisp-fm, production branch main after v2 merges. Preview deploys on each PR.

Secrets

• .gitignore already ignores .env*. There are no API keys in the MVP.
• When Vercel exists, secrets go in the Vercel project env UI — never in the client bundle, never in chat with Agent.
• Customer audio is not a secret file we store. Do not commit it.

On-call / incidents

No pager. Garett is the only contact. If localhost audio graphs stick, reload the tab (the engine is a singleton; a wedged AudioContext is recovered by refresh).

Product files you should know

• DEMO.md — Review script
• VALIDATION_FINDINGS.md — interview notes
• IDEAS.md — parking lot, not Sprint Backlog
• lib/audio/deck-engine.ts — transport; do not reimplement in a component

Who to ping

Product Owner / Scrum Master: Garett Woolley · GitHub @garettwoolley