AI AGENT DIRECTIVES

The following rules MAY be overridden or modified if, and only if, express permission is granted by an authorized human administrator.

Independent Reasoning

• Exercise Independent Thought: Do not blindly follow existing patterns if they are fundamentally flawed.
• Challenge Assumptions: Actively surface architectural weaknesses, inefficient processes, or logical flaws when you detect them.
• Explicit Deviation: If you modify or deviate from prior logic, you MUST explicitly state when you are doing so and justify why.

Code Quality

• Halt Inefficiency: You MUST NOT replicate bad logic during refactoring, porting, planning, or general coding.
• Identify & Improve: When you encounter poor code, clearly identify the issue and proactively implement or propose a solution.
• Scope-Proportional Upgrades: Keep your improvements proportional to the scope of the requested change. Strictly avoid over-engineering or unnecessary architectural expansion.

Output Handling

• Strict Encoding: Always save and output files using UTF-8 encoding without BOM.
• Chat Deliverables: Default to standard Markdown syntax when delivering code or text via chat.
• Corruption Check: Always perform a sanity check for mojibake (character encoding corruption) before delivering any downloadable files.

Markdown Document Formatting

All Markdown formatting rules in this section are conditional on the document's intended audience. A document's audience is determined by its stated purpose, the requesting context, or explicit declaration by the human administrator.

AI-Only Documents

Documents whose primary consumers are AI coding agents (sprint plans, agent context files, session reports, specification updates consumed by agents) MUST use pure Markdown with no embedded HTML tags of any kind. No anchor tags, no page-break rules, no inline style attributes, no div wrappers. Standard Markdown headings, emphasis, links, code blocks, and tables are sufficient. HTML comments are permitted only where an established convention requires them (e.g., the auto-copy header in docs/changelog.md).

Human-Facing Documents

Documents intended for human reading, print rendering, or web publication (overview documents, formal reports, published specifications) follow these formatting rules:

• Justify Large Paragraphs: Wrap all substantial paragraph blocks in <div style="text-align:justify">. Always include a blank line before and after the opening tag or the output will render incorrectly.
• Heading Anchors: Every Markdown heading at every level MUST be preceded by an HTML anchor tag declaring both name and id attributes with an identical lowercase, hyphenated slug derived from the heading text. Place the tag on the line immediately before the heading with no blank line between them.
• Page Breaks: Insert <hr class="print-page-break"> directly before every level-two Markdown header (##). In documents that include a Table of Contents, also insert this tag after the Abstract (before the ToC) and again directly after the ToC. You MUST NOT use a standard "---" horrizontal rule directly before or in conjunction with the HTML-type horrizontal rule, <hr>.
• Stacking Order for Level-Two Headers: When both an anchor tag and a page break tag are required, always stack them in this order: anchor first, <hr> second, heading third. Example:

  <a name="section-title" id="section-title"></a>
  <hr class="print-page-break">
  
  ## Section Title
  

Ambiguous Cases

When audience is not explicitly stated, apply the following defaults:

• Sprint plan documents (*-Updates.md in .handoff/plans/): AI-only.
• Session reports (in .handoff/reports/): AI-only.
• Agent context files (CLAUDE.md, copilot-instructions.md): AI-only.
• Technical specifications (*-spec.md): Human-facing.
• Overview and narrative documents: Human-facing.
• README, CHANGELOG: Human-facing (but these typically do not need anchors or page breaks; use judgment).

If still uncertain, ask.

Prose Constraints

• Chronological Planning: When authoring sprint plans or code update logs, strictly sequence all development sessions in chronological order.
• Punctuation Limits: Only utilize em-dashes when absolutely necessary. Default to parentheses, commas, or standard hyphens to structure your sentences.
• Avoid AI Tropes: Strip out cliche AI rhetorical devices, particularly the contrasting device: "It's not just this — it's that."