Getting Started

You can get from curious to first use in one short path:

1. Install the commands into a target project.
2. Vendor the catalog so the project has the principle data locally.
3. Run dot-scout to create or refresh .principles files.
4. Run dot-audit after the change.

1. Install into a project

From this repository:

./install.sh all <project-dir>

That installs the command files for the supported agent environments and vendors the required catalog data into the target repo.

If you are on Windows, or if you want a narrower install target such as Copilot-only or Codex-only, use the full guide:

• INSTALL.md

2. Commit the installed files

The commands are repo-local. Commit them so every teammate and every CI environment gets the same setup.

cd <project-dir>
git add .claude/ .github/ .agents/ .principles-catalog/
git commit -m "Add .principles AI commands and principle files"

3. Run dot-scout

Use the agent-native command for your environment:

/dot-scout   # Claude / Copilot
$dot-scout   # Codex

dot-scout analyzes the project tree, detects stacks and signals, proposes .principles placement, and writes the files after confirmation.

4. Run dot-audit after the change

/dot-audit current changes

Or describe the target more naturally:

/dot-audit the payment module
/dot-audit README.md
/dot-audit @ddd src/orders

The workflow is intentionally simple:

dot-scout → code → dot-audit

Next steps

• Go to How It Works if you want the mental model.
• Go to Commands if you want the operational details.
• Go to Extending if you want to add your own catalog.