scramjet: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository structure

Scramjet is a product monorepo. Pi runtime packages are vendored in packages/ and modified directly where appropriate. Scramjet is not an extension of Pi — it IS the product; Pi is the runtime it uses.

scramjet/
├── packages/
│   ├── tui/            Pi runtime: terminal UI
│   ├── ai/             Pi runtime: LLM providers
│   ├── agent/          Pi runtime: agent loop, state
│   ├── coding-agent/   Pi runtime: CLI, tools, sessions
│   └── scramjet/       The product: commands, orchestration
│       ├── src/
│       ├── tests/
│       ├── bin/
│       ├── mach12/       # bundled development-methodology command set
│       ├── scramjet/     # bundled product operational command set
│       └── docs/
├── UPSTREAM_DIVERGENCE.md   Tracks Pi modifications for upstream sync
├── .github/workflows/
└── package.json             Root workspace config

Commands

npm run typecheck    # tsgo --noEmit (all packages)
npm run build        # topological build: tui -> ai -> agent -> coding-agent -> scramjet
npm test             # vitest --run across all workspaces
npm run lint         # biome check .
npx vitest run packages/scramjet/tests/command-status.test.ts   # single test file
scramjet-command-lint --strict <command-set-root>                # authoritative command-file authoring check

scramjet-command-lint is required when creating or editing Scramjet command files. Run it against each affected command-set root; resolve errors and address warnings or explain intentional legacy exceptions. If the installed/linked binary is unavailable after npm run build, use the source-tree wrapper without installing anything: node packages/scramjet/bin/scramjet-command-lint.js --strict <command-set-root>. The checker is specific to command Markdown and does not replace typecheck, tests, lint, or behavioral verification.

CI runs typecheck, build, test, lint, an npm pack round-trip smoke (including installed-runtime package-authority coverage), and a postinstall cleanup smoke on ubuntu and macOS.