How PDD works

A new contributor can reconstruct the current judgment without a context handoff.

PDD puts the rule and its active dependencies in the repository. Developers and agents use that evidence to make decisions.

The method gives contributors the same basis for judgment. It can support several valid implementations.

The decision system

1. A principle file states the judgment. Its Rule gives the required choice and binding exceptions.
2. The agent index routes each contributor. Each entry in AGENTS.md links a current token to the full rule.
3. Comments cite local dependencies. A versioned token connects the code to the meaning that its author used.
4. Reviews cite current rules. A “working as designed” decision names the rule that justifies the behavior.
5. The CLI checks the connections. It reports missing entries, invalid citations, and old versions.

The complete example follows one permission rule through all five parts.

Write a principle

A principle prevents a recurring bad choice. A repeated correction supplies evidence, but it does not automatically earn a new token.

The starter format keeps the agent file short. The website supplies the teaching examples outside that file.

A useful rule changes an actual decision. For example, use-time validation stops an agent from adding coordination code for every timing gap.

Task plans and implementation logs describe individual changes. Keep them outside the principle registry.

Adopt a principle

1. Identify a recurring choice with repository evidence.
2. Read every current principle.
3. If a current rule already states the judgment, use that rule.
4. If the proposal changes an existing rule’s judgment, advance that rule.
5. If the judgment governs an independent decision, propose a new token.
6. Under the starter protocol, obtain the repository owner's approval before adopting that token.

Catalog entries are candidates. Downloading an entry does not make it a governing rule in your repository.

These steps concern adopted repository principles. If your repository has another authority or change protocol, follow that protocol.

The PDD principle skill applies this procedure in supported coding harnesses.

Change a principle

1. Change the principle before dependent content or code.
2. If its meaning or authority changes, increment the version.
3. Run pdd check to find old citations.
4. Review each dependent site against the new rule.
5. Update each citation after its review.
6. Include the principle and dependent changes in the same pull request.

A spelling correction keeps the version. A new requirement, exception, or transfer of authority requires a new version.

Under the starter protocol, a wording edit to the Rule needs evidence that its required and rejected choices stay unchanged.

Supporting examples cannot introduce obligations.

How PDD fits

PDD uses existing repository tools. It adds conventions that connect current judgment to its dependencies.

The CLI checks definitions and citations. It cannot determine whether a principle is useful or whether an implementation obeys it.