bluecraft/skills/agent-docs/references/rule-doc-template.md

Rule agent-docs/ Template

Use this structure for Markdown files inside agent-docs/ when the document's main job is to govern behavior: rules, policy, constraints, decision criteria, or workflow guidance.

Minimum Required Shape

# <Document Title>

<Opening statement: what this doc governs, when it applies, and that it must be followed in scope.>

## Applies To

- <specific task or document types>

## Does Not Apply To

- <out-of-scope task or document types>

## Authority

- <source of truth: owning doc, repository path, command, or code area>

## <Rule Section>

- <instructions>

## Edge Cases

- <exceptions, ambiguous cases, or branch conditions>

## Failure Modes

- <what usually goes wrong and how to recover>

## Checklist

- <validation questions>

Required Sections

• # <Document Title>
• opening statement
• ## Applies To
• ## Authority
• at least one topic-specific rule section
• ## Checklist

Conditionally Required Sections

• ## Does Not Apply To when scope boundaries are easy to misread or likely to overlap with sibling docs
• ## Edge Cases when branch conditions or exceptions would otherwise be inferred
• ## Failure Modes when maintainers need recovery guidance or common-mistake handling

Notes

• Make the scope explicit.
• Keep the document responsible for one topic.
• Use semantic filenames and headings.
• Write for maintainers. State actions, constraints, and decision criteria directly.
• If the document references repository files, write repository-relative paths in backticks, not Markdown links or machine-local absolute filesystem paths.
• State the user or maintainer decision directly: what to do, what to avoid, and how to choose.
• Treat Authority as required. If no authority can be named, the rule is probably too vague or not ready to be canonicalized.
• Add Edge Cases and Failure Modes when the workflow is easy to misapply or the scope boundary is easy to misunderstand.
• Prefer linking to inventories, examples, or narrower child docs instead of embedding long registries inline.