Set up your repository

Give the next developer or agent enough evidence to reconstruct your current judgment.

Start with one recurring mistake that your agent makes. The following steps turn an earned correction into a rule with discoverable dependencies.

1. Create the files

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

your-repository/
├── AGENTS.md
├── pdd.config.json
└── docs/
    └── principles/
        ├── change-protocol.md
        └── pdd-01-ubiquitous-language.md

The starter files supply the template, index, configuration, and change protocol.

If your repository already has a principle protocol, preserve its authority rules. The starter format is a proposal for new adopters.

2. Write one rule

1. Copy the principle template into docs/principles/.
2. Name the file with its token and title, such as pdd-01-ubiquitous-language.md.
3. Choose one short, uppercase prefix for tokens.
4. Give the rule a token and version, such as PDD-01@v1.
5. Put the required choice and its binding exceptions in Rule, first.
6. Explain the repeated bad behavior in a short Rationale.
7. Record the adoption evidence in dated History.

Use the complete example file for structure. Optional Implications give examples without adding requirements.

Before adoption, compare the proposal with every current principle. Reuse or advance the current owner when it already covers the choice.

Under the starter protocol, a new token needs an independent recurring choice, repository evidence, and the repository owner's approval.

If you find no earned rule, keep the template only. Do not create principles from task plans or implementation logs.

Principle skill

The portable skill compares a proposal with every current rule. It follows the target repository's authority and admission protocol.

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

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

Use $pdd-principles to classify this principle proposal.
Follow our repository's authority and change protocol.
Show the evidence before adopting a new token.

If a harness cannot load skills, use the change protocol directly.

3. Add the index

Each entry gives the contributor a current token, a short summary, and the path to the full rule.

## Principles

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

Read the full principle before you change covered code.
Judge every change against the applicable principles.
Change a principle before dependent code departs from it.
Cite a current token for each “working as designed” decision.
Before you add a principle, read every current principle.

If a nested directory has its own agent index, add each applicable principle there.

4. Cite dependencies

Add a pinned token where code, tests, tools, or review decisions depend on the rule. State only the local dependency.

// PDD-02@v1: This download checks current permission before use.
// The preview check only gives early feedback.
await requireDownloadPermission(userId, exportId);
return readExport(exportId);

The full rule remains in its principle file. A citation makes the dependent code discoverable after a meaning change.

A “working as designed” review decision must cite a current token.

5. Add the CLI check

Install the CLI as a development dependency. The repository lock file pins its version.

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

Use pdd.config.json to configure your prefix, principle directory, agent indexes, and ignored paths.

Exclude standalone examples and fixtures that use another project’s tokens. Keep actual governing citations in the scanned scope.

Run the check on every pull request, including changes that only affect principles.

- name: Check decision system
  run: npx pdd check

Do not add a path filter. A principle-only change can make existing code citations stale.

6. Review a version change

1. Give a new agent no previous context.
2. Ask the agent to explain one decision from the repository evidence.
3. Practice a meaning change on a branch.
4. Run pdd check to find old citations.
5. Review each dependency before updating its citation.

The complete example shows the report for an old token.

Starter files

Download the files that your repository needs.