feat(cli): add @leadsolutions/lead-protocol for one-command project setup

[leonardobuares]

Summary

Adds @leadsolutions/lead-protocol, a zero-install command-line tool for the Lead Protocol. Today, adopting the protocol means cloning a release tag by hand, copying .agents/ into your project, and pasting the boot procedure into CLAUDE.md and AGENTS.md. This PR collapses that into a single command (npx @leadsolutions/lead-protocol init) and adds three commands to inspect protocol state without needing Python or a server.

Problem

The current setup path (documented in the README "Quick Start") is manual and easy to get wrong:

• You clone a specific release tag, then cp -R the .agents/ scaffold into your project. The exact steps differ between bash and PowerShell, so the docs carry two copies.
• The CLAUDE.md and AGENTS.md boot procedures are copy-pasted by hand. There is nothing to keep them consistent, and re-pasting them is the only way to apply an update.
• Upgrading to a newer release means repeating the clone-and-copy dance and reconciling it with whatever you already changed.
• Inspecting state (a pair's handoff.md, whether decisions.jsonl and handoff.md are schema-valid, the overall picture) means reading files by hand or running validate_state.py, which assumes a working Python install.

For a framework whose whole pitch is "nothing forgotten, nothing re-explained", the onboarding and inspection story leans on manual file shuffling.

What this adds

A small TypeScript CLI, published as the scoped package @leadsolutions/lead-protocol, exposing the lead-protocol binary with four commands:

• init - copies the .agents/ scaffold into the current directory and writes CLAUDE.md and AGENTS.md. The generated boot procedure lives inside <lead-protocol> tags, so the command is idempotent: a new file gets the tagged block, an existing file without tags gets the block appended (your content is preserved), and an existing tagged block is replaced in place. It also creates or appends the protocol's .gitignore entries. --yes skips the confirmation prompt.
• handoff - prints the current handoff state for an (actor, agent) pair, with --pair, --raw, and --json.
• validate - validates decisions.jsonl and handoff.md against their JSON schemas (auto-discovers them when no path is given). Exit codes: 0 passed, 1 validation errors, 2 config errors. This is a Node reimplementation, so it needs no Python.
• status - a one-screen summary of the current protocol state, with --json.

The scaffold (.agents/) is bundled into the package at build time, so init works with no git and no network beyond fetching the package itself. Runtime requirements are Node >= 18 only: no git, no Python, no server.

Usage

Recommended, once the package is published (see "Publishing" below):

npx @leadsolutions/lead-protocol init        # scaffold the protocol into the current project
npx @leadsolutions/lead-protocol status      # one-screen state summary
npx @leadsolutions/lead-protocol handoff     # show a pair's handoff state
npx @leadsolutions/lead-protocol validate    # validate state files against their schemas

Or install globally:

npm install -g @leadsolutions/lead-protocol
lead-protocol init

Try it from this branch before it is published on npm:

cd cli
npm install
npm run build
node dist/index.js init            # or: npm link  &&  lead-protocol init

Changes

• New cli/ package @leadsolutions/lead-protocol (TypeScript, bundled with tsup, commander for arg parsing, @inquirer/prompts for prompts, ajv for schema validation, chalk for output).
• Commands under cli/src/commands/: init, handoff, validate, status.
• Library helpers under cli/src/lib/: project detection, handoff parser, schema validator, <lead-protocol> guideline writer, and shared UI helpers.
• cli/scripts/sync-templates.mjs copies the .agents/ scaffold into the build output so the package is self-contained.
• cli/scripts/test-pack.mjs packs the package and checks the resulting tarball.
• cli/README.md documenting installation and every command.

No kernel, schema, or .agents/ changes: this PR only adds the cli/ directory.

Testing

• npm run build produces dist/, and node dist/index.js --help lists the four commands.
• Ran each command locally: init (into a scratch directory, verified .agents/, CLAUDE.md, AGENTS.md, and .gitignore), status, handoff, and validate against valid and intentionally broken fixtures (confirmed exit codes 0/1).
• npm run test:pack packs the package and verifies the published file set.
• npm run typecheck passes.

Publishing to npm (maintainer action)

This package is not on npm yet, so the npx and npm install -g commands above only work after the first publish. Only a maintainer with access to the @leadsolutions scope can do this. Steps:

1. Create an npm account at https://www.npmjs.com/signup (username, email, password, then confirm the email).

2. Create the npm organization that owns the scope. @leadsolutions/lead-protocol is a scoped package and @leadsolutions is the scope, which must exist as an npm org. Go to https://www.npmjs.com/org/create, set the organization name to leadsolutions, and pick the free "Unlimited public packages" plan. Whoever creates the org can later invite other members as admin or developer.

3. Log in from the terminal with npm login (prompts for username, password, and the OTP if 2FA is enabled).

4. Publish from the cli/ directory (the package.json lives there, not at the repo root):

   cd cli
   npm publish --access public

   --access public is required on the first publish of a scoped package; without it npm tries to publish privately and fails on the free plan. The package already defines a prepublishOnly script that runs npm run build, so the build runs automatically. Only the dist/ folder is published (set via the files field).

5. Verify at https://www.npmjs.com/package/@leadsolutions/lead-protocol. After that, anyone can run npx @leadsolutions/lead-protocol init.

For future updates: bump the version in cli/package.json (for example 0.1.0 to 0.2.0), then run npm publish --access public again from cli/ (the build runs via prepublishOnly).

Exact names used in the code, for reference:

• npm organization: leadsolutions
• package name (cli/package.json): @leadsolutions/lead-protocol
• installed binary: lead-protocol
• package URL: https://www.npmjs.com/package/@leadsolutions/lead-protocol
• end-user command: npx @leadsolutions/lead-protocol init

Checklist

• Code follows project conventions
• Tests added/updated (pack/smoke test via npm run test:pack)
• Documentation updated (cli/README.md)
• Protocol files follow defined schemas - N/A, no .agents/ files were modified

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[mmilanez]

Reviewed and tested locally. CLI commands (init, handoff, validate, status) work as documented. No .agents/ kernel or schema changes — purely additive cli/ directory. Merging as maintainer.