mirror of
https://github.com/merlinhu1/truthmark.git
synced 2026-08-25 07:53:25 +02:00
e9cd67f0b5
* docs: replace legacy truth path references * feat: fold contextpack into workflow status * refactor: remove semantic repository index * fix: remove vulnerable frontmatter dependency * feat: broaden truth sync write authorization * test: restore workflow state regression coverage --------- Co-authored-by: MerlinH <merlinh221@gmail.com>
98 lines
4.3 KiB
Markdown
98 lines
4.3 KiB
Markdown
---
|
|
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.
|