docs: add CLAUDE.md with spec reference

[beogip]

Summary

• Adds CLAUDE.md with architecture guide, build commands, and project conventions
• References the code-first-agents spec as the authoritative source for design decisions
• Documents the dispatch pipeline, output levels (L1/L2/L3), error envelope contract, and testing patterns

Test plan

• Verify CLAUDE.md renders correctly on GitHub
• Confirm spec link resolves

[greptile-apps]

Greptile Summary

This PR adds CLAUDE.md, a documentation file that gives Claude Code contextual guidance when working in this repository. It covers build commands, the dispatch pipeline, output level helpers, error envelope codes, and project conventions.

• Architecture docs: Describes the Tool class dispatch pipeline (parseArgs → builtins → validateInput → handler → output stamping → jsonOutput), all five error envelope codes, and the L1/L2/L3 output helpers — all verified accurate against the current source.
• Convention docs: Documents TypeScript strictness settings, Biome lint rules, conventional commits enforcement via lefthook, and the bun:test testing approach including the CLI fixture subprocess pattern.

Confidence Score: 5/5

Documentation-only change with no runtime code modifications — safe to merge.

The single added file is pure documentation. All factual claims — dispatch pipeline structure, error envelope codes, output level helpers, build commands, and peer dependency version — were verified against the actual source files and package.json. No code is touched.

No files require special attention.

Important Files Changed

Filename	Overview
CLAUDE.md	New documentation file providing Claude Code with architecture guidance, build commands, dispatch pipeline description, and project conventions — all verified accurate against the source code.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[argv tokens] --> B[parseArgs\nargs.ts]
    B --> C{subcommand}
    C -->|schema / help| D[dispatchBuiltin\nauto-registered]
    C -->|unregistered / empty| E[rejectUnknown\nunknown_subcommand envelope]
    C -->|registered| F[validateInput\nargs.ts safeParse]
    F -->|invalid| G[input_validation_error\nenvelope]
    F -->|valid| H[handler\nreturns result without ok]
    H -->|non-object return| I[non_object_return\nenvelope]
    H -->|throws ToolError| J[toolErrorEnvelope\ncustom error code]
    H -->|throws other| K[unexpected_error\nenvelope]
    H -->|plain object| L[validateOutput\nstamp ok:true then safeParse]
    L -->|schema mismatch| M[schema_violation\nenvelope]
    L -->|ok field missing| M
    L -->|valid| N[success envelope]
    D --> O[jsonOutput\nstdout + exit 0]
    E --> O
    G --> O
    I --> O
    J --> O
    K --> O
    M --> O
    N --> O

Loading

_{Reviews (2): Last reviewed commit: "fix(docs): correct parseArgs return shap..." | Re-trigger Greptile}