lore-protocol: Instructions file for Claude Code

Lore CLI

Lore CLI is a tool for the Lore protocol -- a convention for embedding structured decision context (constraints, rejected alternatives, directives, confidence, test notes, cross-references) into git commit messages via trailers. It provides query, write, and maintenance commands over git history.

Tech Stack

TypeScript, Node.js 18+, ESM modules, Commander.js, vitest, chalk, smol-toml, tsup (bundler).

Build & Test Commands

Command	Description
npm run build	Build with tsup
npm run typecheck	Type-check with tsc --noEmit
npm test	Run all tests with vitest
npm run test:watch	Tests in watch mode
npm run lint	ESLint (src/ and tests/)
npm run format	Prettier (src/ and tests/)

Run npm run build && npm run typecheck && npm test before submitting changes.

Architecture

Strict layered architecture. Dependencies flow inward/downward only.

main.ts          — Composition root (the ONLY place concrete classes are instantiated)
  commands/      — Thin CLI handlers; one file per command
    helpers/     — Shared command logic (e.g., path-query pipeline)
  formatters/    — IOutputFormatter implementations (text, JSON)
  services/      — Business logic (parsing, querying, validation, staleness, commit building)
  interfaces/    — Contracts/ports (IGitClient, IConfigLoader, IOutputFormatter, IPrompt)
  types/         — Domain models, config schema, query/output shapes (pure data, zero logic)
  util/          — Constants and error types

Dependency rules:

• Commands depend on services and interfaces; never the reverse.
• Services depend on interfaces and types; never on commands or formatters.
• Types and utilities are leaf nodes with no upstream dependencies.
• No file in services/ imports from commands/ or formatters/.

Composition Root

src/main.ts is the composition root. It:

1. Instantiates all concrete implementations.
2. Loads configuration.
3. Creates services with constructor injection.
4. Creates the formatter factory (getFormatter) that defers format selection to call time.
5. Registers all commands with their dependency bags.