@kekkai/blueprint

Architecture as Code — one Blueprint compiles into ESLint rules, a human handbook, and an AI agent contract.

When an AI writes your code, the architecture is the first thing it quietly erodes

What it costs — and what blueprint does about each:

• Placement — new files land wherever's convenient; a few sessions later, nothing lives where it should.
  → Layers become import-boundary rules the agent reads up front and lint blocks — ✗ services/ may not import from pages/
• Single responsibility — one file quietly grows to do five jobs and own none.
  → Written into the agent contract, backed by the mechanical caps lint can prove.
• File size — every edit grows the file; months in, a module hits 6,000 lines and every agent loads all of it to touch one function.
  → maxLines caps it before it taxes your token budget — ✗ order.service.ts 6,000 / 300
• Readability — optimized for done, not the next reader — who's another agent that now can't navigate it.
  → Handbook + contract set one bar — naming, shape, ownership — for every session.
• Consistency — each session re-derives your architecture from scratch, and guesses differently.
  → survey emits deterministic facts; the contract fixes the rules once.
• Adoption — point it at a 3-year repo, expect 4,000 errors, team disables it day one.
  → Baseline locks today's debt and gates only what's new — .blueprint-baseline.json

blueprint pins all of this down in one config — one source the rules, the docs, and the contract all compile from, so they can never disagree. Edit the config, regenerate, everything moves together. The packaging is the product.

Quick start

Two ways to adopt on an existing repo.

Hands-off — paste this to your agent; it runs start to finish on its own:

Run npx @kekkai/blueprint init --authoring to adopt @kekkai/blueprint in this repo,
then execute the blueprint-authoring.md it writes, fully and to the end.

You judge, the agent assists — blueprint writes the playbook, then launches your agent to walk it with you:

npx @kekkai/blueprint init --agent claude

Framework auto-detected, existing configs never overwritten, re-runs idempotent. What each acceptance step guards, greenfield scaffolding, and the full flow: AI-Assisted Adoption.

🔒 Security & trust

• Never launches an agent by default — it writes plain-markdown contracts and hands off; there is no credential or network surface. init --agent claude|codex is the one explicit opt-in, running under your own agent CLI's permissions.
• No network access, zero runtime dependencies — local file operations only.
• Writes are declared and bounded — --dry-run prints every effect; inspect / deps are read-only; files are only edited when losslessly rewritable, never overwritten.
• Provenance-signed releases — published from GitHub Actions with npm provenance.

Details: Security & Trust

📖 Documentation

Full guide, API reference, and the engineering philosophy behind it (English / 繁體中文):

→ https://taco3064.github.io/blueprint/

License

MIT © taco3064