Contributing

Contributing

Thanks for your interest in improving Bead Me Up, Scotty! This page covers the project layout, conventions, and how to verify changes.

Get set up

git clone https://github.com/brendan-appstart/bead-me-up-scotty.git
cd bead-me-up-scotty
npm install
npm run dev            # http://localhost:3000

See Getting Started for pointing it at real data, and Demo Mode to develop without bd installed.

Project layout

app/                  # pages + API route handlers (the only server entry points)
  api/**              # list/create/patch/delete, status, comments, deps, archive,
                      # plus doctor, config, projects, insights, activity, publish
lib/
  bd.ts               # the ONLY bd CLI bridge (execFile, JSON envelope, write mutex)
  demo-store.ts       # in-memory fallback seeded from the export
  store.ts            # picks bd vs demo
  schema.ts           # Zod schemas + types (the bd data model)
  beads-view.ts       # pure view-model helpers (colors, blocked, epic progress)
  attribution.ts      # human-vs-agent origin
  config.ts           # local app config (NOT stored in beads)
components/           # sidebar, board (dnd), detail drawer, create modal,
                      # epics, graph, settings, command palette, insights, …
design/               # the design spec (design.md) and the Claude Design export

Conventions & ground rules

• bd is the source of truth. Never add a parallel persisted schema. All beads reads/writes go through lib/bd.ts — don't shell out to bd from anywhere else.
• Validate at the boundary. bd output and form input are both validated with Zod (lib/schema.ts). Trust nothing unparsed.
• Writes are serialized. The embedded Dolt backend is single-writer; respect the write mutex in lib/bd.ts.
• App config stays out of beads. Local settings live in ~/.config/bead-me-up-scotty/config.json (see Configuration).
• This is not the Next.js you may know. This repo runs a version of Next.js with breaking changes from older releases. Before writing code, read the relevant guide under node_modules/next/dist/docs/ and heed deprecation notices. (See AGENTS.md.)

Issue tracking with beads

This project dogfoods beads for its own task tracking via the bd CLI:

bd ready              # find available work
bd show <id>          # view an issue
bd update <id> --claim   # claim work
bd close <id>         # complete work
bd prime              # full workflow context

Verify before you push

npm run build         # typecheck + production build (the canonical check)
npm run lint          # eslint

A clean npm run build means types check and the production build succeeds — run it before opening a PR.

Design reference

The UI was designed in Claude Design and rebuilt here with Next.js + shadcn/Tailwind. The original export and a screen/token map live under design/ui-export/, and the full behavioral spec is in design/design.md.

License

By contributing you agree your contributions are licensed under the project's MIT License.