tocket: Instructions file for Claude Code

CLAUDE.md - Tocket

Role

You are the Executor for the Tocket CLI — a context scaffold and file convention for multi-agent workspaces.

Your job is to implement precisely, following the Architect's plans. Read the Memory Bank before every session.

---

Build & Run

npm install          # Install dependencies
npm run build        # Compile TypeScript (tsc → dist/)
npm test             # Run test suite (node:test, 327 tests, 91 suites)
node dist/index.js   # Run CLI locally

---

Code Style

• TypeScript strict mode — all code must pass tsc with strict: true
• ESM only — "type": "module" in package.json
• Imports use .js extension — import { foo } from "./bar.js" (not .ts, not bare)
• Type-only imports — import type { Command } from "commander"
• Node built-ins use node: prefix — import { join } from "node:path"
• Named exports only — no default exports
• Semicolons — yes
• Code in English — variables, functions, comments, commits

---

Architecture

Commands follow the registration pattern:

src/index.ts                    # Entry: registers commands + dashboard detection
src/commands/<name>.cmd.ts      # One file per command (init, generate, sync, validate, config, focus, status, diff, handoff, doctor, lint, eject, suite/loop, decide, work, packs)
src/commands/dashboard.ts       # Interactive menu (no-args entry point)
src/templates/memory-bank.ts    # Template generators for tocket init
src/utils/theme.ts              # Purple theme, banner, semantic helpers (chalk)
src/utils/git.ts                # Git wrappers (staged, modified, commits, branch, diff, recently modified)
src/utils/config.ts             # Global config read/write (~/.tocketrc.json)
src/utils/xml.ts                # Payload XML parser (for tocket diff)
src/utils/context.ts            # Shared constants and helpers
src/utils/appmaps.ts            # AppMap last-run schema (tocket.appmaps.last-run/v0)
src/utils/triage.ts             # Suite triage (heuristic stub + Jev Choice)
src/utils/decide.ts             # Generic decide record (stub or Jev)
src/utils/work.ts               # Reference worker: read Choice, stamp notebook receipt (no Jev)
src/utils/jev.ts                # TypeSafe System One client (Choice + Noul)
src/eval/triage-eval.ts         # POC C agreement / stability eval
src/eval/decide-eval.ts         # Optional decide stub vs fixture label