Start Your Next Project With Veritas

If this framework is doing its job well, starting a new project should feel simple.

The goal is not:

• install a complicated platform
• read a stack of internal docs
• hand-wire every rule before you can begin

The goal is:

• run one setup flow
• get the right starter files
• let the repo guide the AI from the beginning

For the exact generated paths and artifact contracts behind that starter kit, use Artifacts and Schemas. For the exact CLI flags, use CLI Reference.

The Current Experience

The framework now ships a first bootstrap command:

npm install -D @kontourai/veritas
npx @kontourai/veritas init

That command writes the minimum starter kit:

1. an adapter
2. a starter policy pack
3. a team profile
4. a short human-friendly README in the repo

It also records the repo shape it inferred so the team can review the guessed source roots, test roots, and proof lane before moving on.

For agent-guided setup, use the plan-first variant:

npx @kontourai/veritas init --explore --output .veritas/init-plans/first-pass.json
npx @kontourai/veritas init --guided --answers answers.json --output .veritas/init-plans/guided.json
npx @kontourai/veritas init --apply --plan .veritas/init-plans/guided.json

That keeps the initialization conversation flexible while making the reviewed JSON plan the source of truth. The agent can inspect the repo and ask richer questions about proof lanes, protected paths, release expectations, and instruction targets, but --apply --plan remains the only file-writing step.

The Minimum Starter Kit

For the framework to guide the next project well, the repo should start with:

• one adapter
• one policy pack
• one team profile
• one proof lane

That is enough to make the system feel real without overbuilding.

What The Bootstrap Should Do

The bootstrap path should:

Inspect the repo

• what kind of project is this?
• where are the obvious surfaces?
• what is the likely build/test proof lane?

Generate the first framework files

• adapter
• policy pack
• team profile

Default to a safe rollout

• use shadow mode first
• recommend before warning
• warn before block

Wire normal development flow

• suggested local commands
• suggested CI hooks
• short onboarding docs

Why This Matters

If setup is heavy, teams will postpone it. If they postpone it, the framework arrives after local norms have already drifted.

That weakens the whole point of the system.

The framework should be present at project start so the repo can guide the AI from the first meaningful change.

Activation In Practice

Once bootstrapped, the repo should activate guidance in three ways:

1. Ambiently through repo-native instructions and artifacts
2. Explicitly through wrapper commands and skills
3. Downstream through evidence, review, and CI

This means the framework does not need every agent to behave identically. It needs the repo to expose guidance clearly and consistently.

What To Do Today

Use this sequence:

1. run npx @kontourai/veritas init, or use init --explore then init --guided --answers ... when you want an agent-reviewed plan first
2. if using the guided path, review .veritas/init-plans/<name>.json and run npx @kontourai/veritas init --apply --plan .veritas/init-plans/<name>.json
3. review the generated .veritas/ files
4. replace the default proof lane with the one that proves your repo is healthy
5. run npx @kontourai/veritas print package-scripts
6. run npx @kontourai/veritas print ci-snippet
7. run npx @kontourai/veritas apply package-scripts
8. run npx @kontourai/veritas apply ci-snippet
9. run npx @kontourai/veritas report --working-tree
10. or run npx @kontourai/veritas shadow run --working-tree
11. run npx @kontourai/veritas apply governance-blocks
12. optionally run npx @kontourai/veritas apply git-hook --configure-git
13. or run npx @kontourai/veritas apply stop-hook --tool generic
14. or run npx @kontourai/veritas apply runtime-hook
15. or run npx @kontourai/veritas print codex-hook --codex-home /path/to/.codex
16. then run npx @kontourai/veritas apply codex-hook --codex-home /path/to/.codex
17. or run npx @kontourai/veritas apply codex-hook --target-hooks-file /path/to/hooks.json
18. or run npx @kontourai/veritas runtime status --codex-home /path/to/.codex
19. optionally run npx @kontourai/veritas eval summary
20. wire the same paths into review and CI if you want them in your permanent workflow files

This slice is intentionally conservative. Install helpers exist, but the core usage should already be clear before you add extra wiring.

Use --changed-from <ref> --changed-to <ref> when you want branch-diff evidence instead of current-state evidence.

Use eval draft and eval record only after report. That keeps shadow eval grounded in a real run instead of free-floating operator notes. The eval input must come from .veritas/evidence/, and reruns should use --force if you intentionally want to replace an existing eval artifact.

For hooks or repo scripts, prefer shadow run so the framework owns the orchestration path instead of each repo rebuilding it. For git-based passive automation, prefer the tracked .githooks/post-commit adapter generated by apply git-hook. For agent turn-end feedback, prefer the tracked .veritas/hooks/stop.sh adapter generated by apply stop-hook. For agent-runtime integrations, prefer the tracked .veritas/hooks/agent-runtime.sh adapter generated by apply runtime-hook. For Codex specifically, prefer the tracked .veritas/runtime/codex-hooks.json artifact plus an explicit merge into a chosen Codex home or hooks file. If runtime status is run without a Codex target, treat that as “Codex target not inspected yet,” not as proof that Codex is fully installed.

If you want concrete payload examples before generating your own repo-local artifacts, inspect Example Fixtures.