Polydeukes documentation
Polydeukes is a development discipline framework for building alongside an AI coding partner. Choose a guide for your task below.
Start here
Section titled “Start here”| If you want to | Read |
|---|---|
| Get to a first visible judgment | First judgment — install, wire Claude Code, and watch one protected edit get judged |
| Connect Claude Code, Grok, Codex, or git | Connect the surfaces — session and commit setup, including Grok and Codex |
| Shape the project config | Configure the project — discovery, IDE support, and advise versus block |
| Write a real discipline | Write disciplines — worked declarations, especially locale key pairing |
| Recover from a block or skip | Troubleshooting — the fail-closed states, the witness valve, and the log |
| Understand why the framework exists | Why Polydeukes? — the design whitepaper |
| Contribute to these docs | Contributing — bilingual pairs, stable IDs, catalog, and checks |
Reference
Section titled “Reference”Look up configuration keys, declaration syntax, CLI commands, and package contracts.
| Document | Answers |
|---|---|
| Configuration reference | What may go in polydeukes.config.yaml, and what each key does |
| Declaration language reference | Every source, extraction step, combinator, relation, and mechanism |
polydeukes (the pdks CLI) |
Package contract, and the judge that lives inside it; subcommands live under reference/cli/ |
@polydeukes/core |
The protocol, the input IR, the config schema, telemetry |
@polydeukes/adapter-claude-code |
Claude Code session surface — hook payloads become the input IR |
@polydeukes/adapter-grok |
Grok session surface — hook payloads become the input IR |
@polydeukes/adapter-codex |
Codex session surface — hook payloads become the input IR, one element per file the patch touches |
@polydeukes/sdk-ts |
Call the judge from TypeScript and handle its result |
How it works
Section titled “How it works”Polydeukes judges what a developer or an AI agent is about to do, records the verdict, and by default lets the work proceed. Three ideas carry the rest.
Covenants check agreed development practices. The same disciplines apply to human and AI work. This project’s authors use them in daily development.
Judging and stopping are separate decisions. Every declared discipline is judged on matching
calls. By default, a violation is recorded with its reason and the call continues. Set
enforce: block on an entry to stop violations. The framework’s own protections block session
calls by default.
Judgments are recorded. .polydeukes/roi.log stores verdicts and their context. Use the log
to investigate violations, skipped checks, and unexpected results. The
design explanation describes how these records informed the project.
Two surfaces
Section titled “Two surfaces”| Surface | Judges | Wired by | For |
|---|---|---|---|
| Session | A tool call, before it runs | pdks-claude-code init, pdks-grok init, or pdks-codex init |
A project developed with an AI partner |
| Commit | A unified diff on stdin — staged, the working tree, or a ref range | A pre-commit hook piping git diff --cached, or run on demand |
A human developing alone, and CI |
The commit judge also answers on demand: git diff HEAD | pdks covenant check --diff after a task,
git diff main...HEAD | … before a PR. Same verdict a commit would receive, delivered as an exit
code with no prompt — the gate is whatever consumes that code.