cli-printing-press AGENTS.md

CLI Printing Press - Development Conventions

Machine vs Printed CLI

This repo is the machine (generator, templates, binary, skills) that produces printed CLIs. When fixing a bug or adding a feature, ask: machine change or printed-CLI change?

• Machine changes (generator, templates, parser, skills) affect every future CLI and must generalize across APIs, spec formats, and auth patterns.
• Printed-CLI changes (~/printing-press/library/<api-slug>/) fix one CLI and do not compound.
• Default to machine changes. If a problem appears in a printed CLI, ask first whether the generator should have gotten it right. Only fix the printed CLI directly when the issue is genuinely API-specific.
• Don't change the machine for one CLI's edge case. If a fix helps one API but breaks another, guard it with a clear conditional or leave it as a printed-CLI fix.
• Don't hardcode API/site names in reusable artifacts. Skills, templates, generator code, prompts, and shared docs must use placeholders (<api>, <site>, "the target site") unless the text is explicitly an example or test fixture.
• Update dependent verifiers in the same change. A new generator capability that affects scoring requires a scorer update; one that changes the MCP surface requires an audit update. When iterating on a printed CLI to discover issues, classify findings as systemic (retro candidate) vs specific (printed-CLI fix).

Anti-reimplementation

A printed CLI wraps an API; it does not replace one. Novel-feature commands must call the real endpoint or read from the local store populated by sync.

• Reject hand-rolled response builders that return constants, hardcoded JSON, or struct literals shaped like an API payload.
• Reject endpoint stubs that return "OK" or a canned success message without calling the client.
• Reject aggregations computed in-process when the API has an aggregation endpoint.
• Reject enum mappings and reference data synthesized locally when the API returns them.
• Carve-outs: commands that read from internal/store; commands that operate on the local SQLite file via database/sql; commands that call the API and then cache to the store; commands whose data is curated static content via // pp:novel-static-reference; commands that make a real hidden client call via // pp:client-call, but only when the hidden helper performs a real external API call. Do not use // pp:client-call for hardcoded payloads, local-only transforms, or fake endpoint stubs. Enforced by the absorb manifest's Kill Check (skills/printing-press/references/absorb-scoring.md) and dogfood's reimplementation_check, which flags handler files showing neither a client call nor a store access without an opt-out.