add-tool

name	add-tool
description	Add a new kit tool end-to-end (core → CLI → API → C16 tests → just check). Use for any new tool id.

Skill: add-tool

Use when adding a new tool to the kit. Follow only this skill’s steps — do not reimplement pipelines in adapters.

Read order

1. Root AGENTS.md (kit hard boundaries)
2. This skill
3. Justfile recipes (just check)
4. Existing tool as template: crates/kit-core/src/tools/tool_a.rs

Recipe (REQ-030)

1. Name a stable tool id (kebab for routes/CLI, snake for Rust module), e.g. tool-b / tool_b.
2. Implement in kit-core only:
   • Module crates/kit-core/src/tools/<tool_id>.rs
   • Public async run(...) (and optional run_synthetic_* helper)
   • pub const TOOL_ID: &str = "<tool-id>";
   • Export from tools/mod.rs
3. Synthetic unit tests in the same module (REQ-028). No real student PII.
4. Wire CLI thin adapter:
   • crates/kit-cli/src/adapters/<tool_id>.rs calling kit_core::tools::<id>::run only
   • clap subcommand in kit-cli main (no secret flags)
5. Register explicit API route POST /jobs/{tool_id}:
   • crates/kit-api/src/jobs/<tool_id>.rs thin adapter
   • Route in router.rs + authorized handler in routes.rs (same authz/CSRF as other jobs)
6. Document env names only (if any) in docs/ops/env-names.md — values via fnox/Render.
7. Shared-entrypoint test (REQ-003 / C16): automated test proving CLI and API adapters produce the same bytes as kit_core::tools::<id>::run (see crates/kit-api/tests/c16_tool_a_shared_entrypoint.rs).
8. Run just check and fix until green.

Forbidden (REQ-003 / REQ-031) — dual-body ban

• Dual pipeline bodies: reimplementing source/transform/sink logic in kit-cli or kit-api. Both surfaces MUST call the same kit-core entrypoint. Dual implementations are defects.
• Secret values, age private keys, OAuth/break-glass secrets, or valued .env in git.
• Real student PII in fixtures, samples, logs, chat, or commits.
• Weakening allowlist authz to open (empty/missing allowlist stays fail-closed).
• Live cloud deploy claims from foundation work; Airtable live without ops wave.
• Putting Google tokens in SPA localStorage / sessionStorage.

Checklist

• TOOL_ID matches CLI subcommand and POST /jobs/{tool_id}
• Transform logic only in kit-core
• Synthetic tests green
• C16 test CLI + API vs core
• just check green
• No secrets / PII committed

Evidence for MS-06

Tool B was added by following this skill (see docs/ops/ms06-add-tool-evidence.md).