codepremise kit

Make your coding agents write the map

The kit teaches your agents to maintain a .codepremise/ folder — business-logic claims mapped to code — while they work. One command, run from the root of your repo:

$curl -fsSL https://codepremise.dev/install.sh | sh

Then commit the new files. From then on, open any PR of that repo here by swapping the domain: github.com/o/r/pull/1 → codepremise.dev/o/r/pull/1.

What lands in your repo

.codepremise/ — the map; agents fill it as they touch code

├── nodes/ — one JSON claim per file (schema)

└── validate.mjs — validator + impact query; run it in CI

.agents/skills/ — ONE skill, every agent (Agent Skills standard)

├── codepremise/SKILL.md — the claim-writing rules, read by 40+ agents

└── codepremise-bootstrap/SKILL.md — seeds the map for existing repos

.claude/

├── skills/ — links to the same skill (Claude Code discovery)

├── hooks/codepremise-check.py — warns the agent when an edit stales a claim

└── settings.json — wires the hook (PostToolUse)

.codex/ · .cursor/ — same hook, per-agent wiring (codex · cursor)

How each agent is kept honest

Claude Code

Discovers the skill via .claude/skills/ links; a PostToolUse hook re-checks every claim touching an edited file and feeds the warning straight back to the agent mid-run.

enforced by hook

Codex

Reads the same skill from .agents/skills/; the hooks engine runs the check on PostToolUse and feeds it back to the model.

enforced by hook

Cursor

Reads the same skill from .agents/skills/; the afterFileEdit hook records staleness in the audit log.

skill + audit hook

The backstop for all three: node .codepremise/validate.mjs fails when any claim lies about the code — run it in CI to make truthfulness a merge requirement.

Already have a codebase? Bootstrap the map

For existing repos, open your agent in the repo and say “bootstrap the codepremise map”. The bootstrap skill mines your past agent conversations (the reasoning behind old changes was recorded at generation time — it’s in the session transcripts) and git history for authentic whys, ranks the load-bearing code, and then interviews you — mostly quick confirmations, not open questions — to fill what mining couldn’t source. Claims nobody can explain are listed instead of invented: that list is your repo’s real risk register.

How the map works, in one paragraph

One JSON file per claim in .codepremise/nodes/: a plain-language what and why, pointing at code by file + line range + a hash of those exact lines. Behavior change → the agent amends the claim. Pure refactor → it re-affirms only the pointers, which reviewers see as an explicit “behavior-preserving” statement. Claims connect through typed links — parent rule, flow step, depends-on — and the viewer warns when unrelated rules share lines. Before editing, agents ask the map for the blast radius: node .codepremise/validate.mjs . --impact src/file.ts:12-24.

← Open a pull request