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”Start with installation → first judgment → connection and configuration → discipline authoring.
| Your task | Guide |
|---|---|
| Choose packages and extensions | Install |
| See an allowed and a blocked observation | First judgment |
| Connect an agent, Git, or CI | Connect surfaces |
| Turn recurring mistakes into a discipline | Write disciplines |
| Retrieve decisions and evidence | Use memory |
| Invoke judgment from a program | SDKs and references |
| Diagnose skips, blocks, and installation errors | Troubleshooting |
| Upgrade an earlier installation | Migrate to Rust |
The documentation home connects these learning paths with the command references.
Read the judgment model and observation limits to understand what your disciplines can establish. Use the reference pages when you need exact keys and exit codes.
Reference
Section titled “Reference”CLI commands
Section titled “CLI commands”| Command | Purpose |
|---|---|
pdks covenant check |
Judge an input IR or unified diff; read verdicts and exit codes |
pdks init |
Create project configuration |
pdks explain |
Inspect registered disciplines and enforcement |
pdks docs |
Search and retrieve installed documentation |
pdks memory |
Search current Markdown documents and open their sections |
Configuration
Section titled “Configuration”Configuration reference covers polydeukes.config.yaml keys,
enforcement levels, discipline lists, and witness settings.
Declaration language
Section titled “Declaration language”Declaration language reference lists every source, extraction step, combinator, relation, and mechanism with its syntax and constraints.
Packages
Section titled “Packages”| Package | Responsibility |
|---|---|
polydeukes (the pdks CLI) |
Package contract, and the judge that lives inside it; subcommands live under reference/cli/ |
| Input IR / schemas | The protocol, the input IR, the config schema, telemetry |
pdks-claude-code |
Claude Code session surface — hook payloads become the input IR |
pdks-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 |
pdks-memory |
Optional Markdown queries over current files |
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 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.