Turn tacit judgment into a shared decision system.

Create the registry

Give the decision system one authoritative home.

Keep full rules in one directory. Put the short routing index and CLI configuration at the repository root.

your-repository/
├── AGENTS.md
├── pdd.config.json
├── docs/
│   └── principles/
│       ├── change-protocol.md
│       └── pdd-01-example.md
└── scripts/
    └── check-principles.sh

Write one earned rule

Record judgment that a new agent cannot infer safely.

Use a repeated review finding, production lesson, or costly trade. Do not begin with a list of preferences.

Keep one decision in one principle.

The portable PDD skill compares each proposal with every current principle before it adds a token.

The package uses the Agent Skills format across supported harnesses.

npx skills add Principle-Driven/pdd --skill pdd-principles

The installer detects supported harnesses. Use --agent or --global to select a different target.

Use $pdd-principles to classify this principle proposal.
Implement the correct result.

Index for agents

Route every contributor to the same current rule.

Put the token, title, essence, and file path in AGENTS.md. No handoff is necessary.

## Principles

- **PDD-01@v1 — Use Ubiquitous Language** —
  Use one domain vocabulary in discussion, tests, and code.
  → `docs/principles/pdd-01-ubiquitous-language.md`

Cite the dependency

Make each dependency visible in the code.

Cite a token where the rule carries real weight. State the local dependency, not the complete rule.

// PDD-02@v1: Permission is authoritative at use.
// The earlier check only gives fast feedback.
downloadExport(request);

Make deliberate risk searchable.

Use one marker format for accepted risks. Include the scenario, reason, and condition for a new decision.

// ACCEPTED-RISK: A restore can reveal one bit about a
// hidden unique field. Integrity has priority. Revisit when
// restore quarantine can make the outcome actor-neutral. PDD-06@v1

Enforce with the CLI

Turn a version change into a complete review queue.

When the first code citation appears, install the CLI. Run it on every pull request, including principle-only changes.

npm install --save-dev @principle-driven/cli
npx pdd check

- name: Check decision system
  run: npx pdd check