truthmark/docs/ai/agent-onboarding.md

---
status: active
doc_type: agent-guide
last_reviewed: 2026-05-16
source_of_truth:
  - repo-rules.md
  - ../README.md
---

# Agent Onboarding

## Purpose

Fast routing for agents. Repository-wide rules live in [docs/ai/repo-rules.md](repo-rules.md).

## Startup

1. Read your agent entry point, usually [AGENTS.md](../../AGENTS.md).
2. Read [docs/README.md](../README.md).
3. Identify whether the task changes scaffold behavior, diagnostics, installed workflows, or only documentation placement.
4. Read only the docs that govern that slice before editing code or canonical docs.

## Change Routing

### CLI or scaffold behavior

Read:

1. [docs/truthmark/engineering/architecture/overview.md](../truthmark/engineering/architecture/overview.md)
2. [docs/truthmark/engineering/behaviors/init-and-scaffold.md](../truthmark/engineering/behaviors/init-and-scaffold.md)
3. [docs/truthmark/engineering/contracts/config-route-and-check-contracts.md](../truthmark/engineering/contracts/config-route-and-check-contracts.md)
4. [docs/truthmark/product/capabilities/lane-separated-truth.md](../truthmark/product/capabilities/lane-separated-truth.md)

### Diagnostics, routing, or containment checks

Read:

1. [docs/truthmark/engineering/architecture/overview.md](../truthmark/engineering/architecture/overview.md)
2. [docs/truthmark/engineering/behaviors/check-diagnostics.md](../truthmark/engineering/behaviors/check-diagnostics.md)
3. [docs/standards/documentation-governance.md](../standards/documentation-governance.md)
4. [docs/truthmark/engineering/contracts/config-route-and-check-contracts.md](../truthmark/engineering/contracts/config-route-and-check-contracts.md)

### Installed workflow, prompt, or reporting changes

Read:

1. [.truthmark/config.yml](../../.truthmark/config.yml)
2. [docs/truthmark/product/capabilities/agent-native-workflow-injection.md](../truthmark/product/capabilities/agent-native-workflow-injection.md)
3. [docs/truthmark/engineering/workflows/installed-workflow-runtime.md](../truthmark/engineering/workflows/installed-workflow-runtime.md) and [docs/truthmark/engineering/contracts/generated-host-surfaces.md](../truthmark/engineering/contracts/generated-host-surfaces.md)
4. [docs/standards/maintaining-repository-truth.md](../standards/maintaining-repository-truth.md)
5. The manifest, renderer, generated surfaces, and focused tests named by the workflow truth docs

### Package version changes

Read:

1. [docs/standards/versioning.md](../standards/versioning.md)
2. [docs/standards/change-notes.md](../standards/change-notes.md)
3. [docs/standards/testing-and-verification.md](../standards/testing-and-verification.md)

### PR or release text

Read:

1. [docs/standards/change-notes.md](../standards/change-notes.md)
2. [docs/standards/versioning.md](../standards/versioning.md), only when package version changes are in scope

### Documentation structure or policy changes

Read:

1. [docs/README.md](../README.md)
2. [docs/standards/documentation-governance.md](../standards/documentation-governance.md)
3. [docs/standards/maintaining-repository-truth.md](../standards/maintaining-repository-truth.md)

## Agent Rules

Do:

- treat [docs/ai/repo-rules.md](repo-rules.md) as the primary authority for repository-wide rules
- route code changes to the nearest maintained architecture, contract, and truth docs
- update [docs/truthmark/routes/areas.md](../truthmark/routes/areas.md) when canonical routing changes
- apply [docs/standards/versioning.md](../standards/versioning.md) before changing or accepting a package version
- write `changes/` notes from [docs/standards/change-notes.md](../standards/change-notes.md) when PR or release text is needed
- preserve the generated Truthmark block in [AGENTS.md](../../AGENTS.md) unless the template behavior itself is changing
- keep non-canonical planning notes separate from current-state docs

Do not:

- treat [README.md](../../README.md) as the final source of behavioral truth
- invent unimplemented commands such as a current `truthmark realize` CLI command
- leave routing broad when you can point to a smaller maintained truth surface
- rewrite functional code during documentation-only tasks

## Verification

Use [docs/standards/testing-and-verification.md](../standards/testing-and-verification.md) for commands and [docs/standards/pre-completion-checklist.md](../standards/pre-completion-checklist.md) as the completion gate.