bluecraft/skills/agent-docs/references/root-agents-template.md

Root AGENTS.md Template

Use this structure for the AGENTS.md at the root of the current Git working tree.

Recommended Shape

# Root AGENTS.md

- State that this file is the starting point for the repository's required `agent-docs`.
- Define the default path basis.

# Common Constraints

- Keep repository-wide rules here.
- Do not repeat topic-specific rules that belong in child docs.

# Required `agent-docs` Before Editing

- List the required `agent-docs` explicitly.
- Use explicit "Read and follow ..." wording.

Notes

• Keep this file short.
• Treat this file as an instruction document, not a passive index.
• Reference child docs only when they are actually needed.
• Write for maintainers and keep decisions explicit.
• When referring to child docs, write repository-relative paths in backticks such as agent-docs/example.md, not Markdown links or machine-local absolute filesystem paths.
• Do not turn the root file into a dump of all topic-specific rules.
• If the root starts collecting multiple topic-specific rule blocks, split them into child docs and keep only the routing decision here.

Complexity Budget

• Keep the root focused on three jobs only: entrypoint, repository-wide constraints, and next-step routing.
• If a root section starts carrying topic-specific decision logic, move that logic to a child doc and leave only the routing cue behind.
• Treat multiple topic-specific rule blocks in the root as a refactor trigger, not as a sign to keep extending the root file.