Polydeukes

English · 한국어

A development discipline framework for building alongside an AI coding partner. Deterministic covenants, a verifiable work ledger, a local memory graph, and adversarial verification — on one thin core.

Quick start

Run from the project root in your own terminal. Download the executable for your system (pdks-linux-x64 or pdks-darwin-arm64) from a GitHub Release, make it executable, and place it on PATH as pdks. It includes all three adapters and memory commands and runs without Node, npm, or a package.json.

1. Connect your agent

pdks adapter claude-code init
# or
pdks adapter codex init
pdks adapter grok init

The installer creates configuration and merges project hooks. Reopen Claude Code, approve Codex hooks through /hooks, or approve Grok project trust and reload its Hooks tab. Verify the connection with a real call and .polydeukes/roi.log. Rerun init after moving the executable or project. For Git diff checks alone, use pdks init.

2. Configure your first discipline

Open the generated polydeukes.config.yaml in your editor. Keep the generated protectedPaths and witness blocks. Add this disciplines list, or append the entry to your existing list. It reports newly added lines containing TODO in src/:

disciplines:
  - id: 'no-new-todo-lines'
    why: 'Resolve TODOs before adding source lines.'
    enforce: advise
    declare:
      mechanism: 'added-only'
      scope: { source: 'target.path', include: ['^src/'] }
      supply: { pre: 'empty', post: 'empty' }
      extract:
        before:
          - { op: 'source', of: 'pre' }
          - { op: 'lines' }
          - { op: 'keyByPattern', re: '(.*TODO.*)' }
        after:
          - { op: 'source', of: 'post' }
          - { op: 'lines' }
          - { op: 'keyByPattern', re: '(.*TODO.*)' }
        added:
          - { op: 'onlyIn', of: 'after', notIn: 'before' }
      relate:
        - id: 'nothing-added'
          relation: { op: 'empty', of: 'added' }
          message: 'Resolve this TODO: {value}'

Unchanged TODO lines are allowed; repeating an identical existing line is also treated as already present. advise reports a violation and lets work continue. Choose enforce: block when you want the entry to stop a session call. Diff checks also need --enforce block to stop on a blocking entry.

The config file itself is protected during agent sessions. Edit it yourself, or use the witness procedure for an intentional agent edit. In Claude Code, the installed discipline-draft skill can help turn a problem you describe into an entry.

3. Check the result

pdks explain
git diff HEAD | pdks covenant check --diff

explain should list no-new-todo-lines as declare on both surfaces. To see a violation, add a new // TODO: quick-start check line to a tracked file under src/, then rerun the diff command. Expect a diagnostic naming the discipline, an advised row in .polydeukes/roi.log, and exit code 0. Remove the line and rerun; that diagnostic should disappear.

Continue with more discipline examples, pre-commit integration, or pdks docs for the installed documentation.

Status and CLI

Seven npm packages and one Rust crate ship; a Python SDK is also available — @polydeukes/core (the covenant protocol), the session adapters (adapter-claude-code, adapter-grok, adapter-codex), @polydeukes/sdk-ts (four asynchronous verbs for covenant checks and memory), the crate polydeukes-sdk (the same four verbs for a Rust host), the Python package polydeukes-sdk (four verbs over the standalone executable), @polydeukes/memory (the optional markdown index behind pdks memory), and the polydeukes umbrella, which carries the judge and whose pdks bin (an alias of polydeukes) is the CLI. The ledger and verify packages are still blueprint. The CLI today:

pdks init                # create the project scaffold: config file and telemetry ignore line
pdks adapter claude-code init  # Claude Code
pdks adapter grok init         # Grok
pdks adapter codex init        # Codex
git diff --cached | pdks covenant check --diff      # judge the staged diff (the pre-commit entry point)
git diff HEAD | pdks covenant check --diff          # the same judgment over the working tree
git diff main...HEAD | pdks covenant check --diff   # ... or over a ref range (a PR's scope)
pdks covenant check < input.json                    # or an input IR another program built
pdks explain             # print what each surface judges, skips, and excludes — no judgment
pdks docs [topic]        # read the bundled documentation, offline
pdks memory ingest       # index the project's markdown into .polydeukes/memory.db (included in the single executable)
pdks memory search <query> | show <id>             # search that index, or show a document or section
pdks memory lint | stats                           # report broken links, or count documents, links, and isolated documents
pdks memory obligations <key>                      # list every obligation the config's rules extracted for one key
pdks memory supersession <id>                      # list the chain of documents that replace, or were replaced by, one document

The installer also drops a discipline-draft skill into .claude/skills/: describe a recurring problem to your AI partner and the skill classifies it into a config entry — judged at advise when the current declaration grammar can express it, a draft: true entry otherwise.

Since v0.5.0 the default posture is diagnostic. A broken discipline lands as a recorded advisory — exit 0, one advised telemetry row, the entry's own why on stderr — rather than a refused call. What blocks unasked is the judging chain's self-protection; enforce: block on an entry is a promotion its author chooses, and the promotion ladder is draft → advise → block.

The documentation ships inside the package, so pdks docs answers from the same version that does the judging — no network, and no drift between what a search engine indexed and what is installed. The Documents table below is the same set plus the narrative layer, grouped from getting started to reference. Planned — each arrives with its package: pdks verify (adversarial verification) and pdks ledger start <id> (work tracking).

---

What it is

Polydeukes externalizes the discipline a developer applies to themselves — test first, verify before committing, record decisions, don't repeat the same mistake — into deterministic machinery, rather than prompt-level requests, and shares that machinery with an AI partner.

The framing is partnership, not control. A covenant is not a fence that cages the AI; it is a shared promise that applies equally to the human and the AI. The origin of the name and the philosophy behind it are in STORY.md.

The design starts from AI development tooling embedded in a real production monorepo, and from an analysis of whether that tooling can be extracted into a general discipline framework.

Structure — a thin core plus independent packages

The executable composes the judge and three host adapters. Each adapter translates its host’s events into the shared core vocabulary; the judge consumes that vocabulary.

Package	Role
@polydeukes/core	Covenant protocol (stdin-JSON / exit-2), the config schema and its validation, algebra declaration schema, the input IR as a JSON Schema for hosts in other languages, transcript interface — a minimal core that is agnostic to domain and agent. Reading a config off disk is the umbrella's loadConfig, not the core's: the core touches no file but its own telemetry log
polydeukes (the judge, src/covenant/)	Deterministic judgment at edit and commit time, plus the meta-covenants that protect the judging chain itself
@polydeukes/ledger (planned)	Work tracking. Completion authority moves from "I'm done" to "the actions passed"
@polydeukes/memory	An optional local SQLite + FTS5 index over the project's markdown documents, used through pdks memory ingest, search, show, lint, and stats. The documents stay the record; the index is rebuilt from them
@polydeukes/verify (planned)	A multi-agent adversarial verification orchestrator

core, the umbrella polydeukes, the session adapters, sdk-ts, sdk-rust, sdk-python, and memory ship today. The planned adoption order once the rest exists is covenant → memory → ledger → verify: covenant and memory are expected to pay off regardless of project size, while ledger and verify target the scale of multiple worktrees and team workflows.

Design blueprint (in brief)

The core principle of the extraction strategy is a one-way layering: general core inward, domain outward, with every dependency pointing inward at the core and none pointing back out. The core knows nothing of any specific product or AI runtime.

pdks (CLI · common runtime · judge)
  ├── adapter-claude-code ──┐
  ├── adapter-codex ────────┼── core (shared vocabulary · schemas)
  └── adapter-grok ─────────┘

sdk-ts / sdk-rust / sdk-python ── process calls ── pdks

Three separations:

• Language ⊥ agent — language coupling (test commands, path globs for TS/Python/Go) goes in polydeukes.config.yaml; AI-runtime coupling (transcript schema) goes in adapter-*. The two are orthogonal.
• Essential vs incidental — "verification is decided by exit code" is essential; "that command happens to be vitest" is incidental (config). "Knowledge is a local SQLite file" is essential; "that file happens to live on S3" is incidental (a sync adapter).
• Measurement as a first-class citizen — collect covenant-ROI and memory-search telemetry, then feed it back in a closed loop. Prove "it produces safer code" with data.

Documents

docs/README.md is the documentation index — the same map as below, with a one-page summary of how the framework works. The tables here are grouped by layer; start at the top layer you need.

Tutorials and guides

Document	Contents
docs/tutorials/first-judgment.md	First visible judgment — install, wire Claude Code, and watch a protected edit get judged
docs/how-to/connect-surfaces.md	Connect the session and change-set surfaces, including Grok and Codex
docs/how-to/configure-project.md	Configure the project file, IDE support, and advise versus block
docs/how-to/write-disciplines.md	Worked declarations, especially locale key pairing
docs/troubleshooting.md	Fail-closed states, the witness valve, and the telemetry log

Reference

Document	Contents
docs/reference/configuration/index.md	Configuration reference — every key, its rules, and its pitfalls
docs/reference/declaration-language/index.md	Declaration language reference — every source, extraction step, relation, and mechanism
docs/reference/packages/polydeukes.md	Package reference — subcommands, exit codes, and the package contract

Background and releases

Document	Contents
Introducing Polydeukes (Korean)	The author's introduction to the project on funes-days
STORY.md	The origin of the name and the design philosophy (a founder's narrative)
docs/why-polydeukes.md	Why Polydeukes? — the design whitepaper: the principles, the failure stories behind them, and the measurements that settled each one
CHANGELOG.md	Release notes per milestone

License

MIT