docs: add runnable examples/ directory

[claude]

Summary

Adds a clonable, runnable examples/ directory so the pattern reads as "this isn't theory" rather than spec prose. Resolves #26.

• examples/changeset.ts — one complete, deterministic tool that demonstrates all three output levels from the spec with one subcommand each:
  • stats → L1 (data) — raw signals for the LLM to interpret
  • size → L2 (classification) — a discrete size class the skill can branch on
  • review-plan → L3 (instructions) — a verbatim review procedure the LLM executes
• examples/README.md — exact run commands and the expected JSON output for each level, plus help/schema introspection and the always-exit-0 error envelopes.
• README.md — links to examples/ from the main docs.

No LLM calls inside the tool; same input flags → same JSON. Imports from ../src/index.ts so it runs against source with no build step (bun run examples/changeset.ts ...), and the README notes the @code-first-agents/tool import for real projects.

Verification

• bun test → 113 pass, 0 fail
• bunx tsc --noEmit → clean
• bunx biome check . → clean (examples file included; only a pre-existing schema-version info note)
• Every command in examples/README.md was run; documented JSON matches actual output.

Generated with Claude Code

[greptile-apps]

Greptile Summary

Adds a clonable examples/ directory with a single deterministic tool (changeset.ts) that demonstrates all three output levels (L1 data, L2 classification, L3 instructions) defined in the Code-First Agents spec, together with an examples/README.md and a short section in the root README.md.

• examples/changeset.ts correctly uses the Tool API — l1Output, l2Output, l3Output — with shared Zod input schema and three subcommands (stats, size, review-plan); the framework stamps ok: true automatically, so handlers only return business data.
• examples/README.md documents every subcommand with verified JSON output, introspection (help/schema), error envelopes, and alternate inputs; the documented outputs are consistent with the implementation.
• The root README.md change is a minimal, accurate pointer to examples/.

Confidence Score: 5/5

Safe to merge — purely additive docs and example code with no changes to library source or tests.

All three files are additive only. The example tool uses the public API correctly, the classification logic is deterministic and consistent with the documented outputs, and the framework's ok: true stamping means handler omissions are not a concern. The PR description states tests and type-checking pass clean.

No files require special attention.

Important Files Changed

Filename	Overview
examples/changeset.ts	New runnable example tool; correctly registers three subcommands using l1Output/l2Output/l3Output, deterministic classification logic, and proper tool.run() entrypoint.
examples/README.md	New documentation file; expected JSON outputs match the implementation, error envelope snippets are accurate, and instructions are reproducible from the repo root.
README.md	Adds a short "Examples" section with a verified command and links to examples/README.md; no other changes.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["bun run examples/changeset.ts subcommand --files N --additions N --deletions N"] --> B{subcommand?}

    B -->|stats| C["L1 — Data\nl1Output handler\nreturns files, additions,\ndeletions, total_lines"]
    B -->|size| D["classifySize(files, churn)\nxs / small / medium / large / x-large"]
    B -->|review-plan| E["classifySize → reviewPlan(size)\nL3 — Instructions string"]
    B -->|help| F["dispatchBuiltin → help JSON"]
    B -->|schema| G["dispatchBuiltin → JSON Schema"]
    B -->|unknown| H["unknownSubcommandEnvelope\nok: false"]

    D --> I["L2 — Classification\nl2Output envelope\n{ok, message, classification, total_lines}"]
    E --> J["L3 — Instructions\nl3Output envelope\n{ok, message, instructions, size}"]
    C --> K["validateOutput stamps ok: true\njsonOutput → stdout, exit 0"]
    I --> K
    J --> K
    F --> K
    G --> K
    H --> K

Loading

_{Reviews (1): Last reviewed commit: "docs: add runnable examples/ directory" | Re-trigger Greptile}

[github-actions]

🎉 This PR is included in version 0.1.5 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀