truthmark/docs/ai/agent-onboarding.md

status, doc_type, last_reviewed, source_of_truth

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

Agent Onboarding

Purpose

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

Startup

1. Read your agent entry point, usually AGENTS.md.
2. Read docs/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
2. docs/truthmark/engineering/behaviors/init-and-scaffold.md
3. docs/truthmark/engineering/contracts/config-route-and-check-contracts.md
4. docs/truthmark/product/capabilities/lane-separated-truth.md

Diagnostics, routing, or containment checks

Read:

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

Installed workflow, prompt, or reporting changes

Read:

1. .truthmark/config.yml
2. docs/truthmark/product/capabilities/agent-native-workflow-injection.md
3. docs/truthmark/engineering/workflows/installed-workflow-runtime.md and docs/truthmark/engineering/contracts/generated-host-surfaces.md
4. docs/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
2. docs/standards/change-notes.md
3. docs/standards/testing-and-verification.md

PR or release text

Read:

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

Documentation structure or policy changes

Read:

1. docs/README.md
2. docs/standards/documentation-governance.md
3. docs/standards/maintaining-repository-truth.md

Agent Rules

Do:

• treat docs/ai/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 when canonical routing changes
• apply docs/standards/versioning.md before changing or accepting a package version
• write changes/ notes from docs/standards/change-notes.md when PR or release text is needed
• preserve the generated Truthmark block in AGENTS.md unless the template behavior itself is changing
• keep non-canonical planning notes separate from current-state docs

Do not:

• treat 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 for commands and docs/standards/pre-completion-checklist.md as the completion gate.