AGENTS.md

Scope and Precedence

These rules apply to all roles. Role files may add detail but cannot override them.

Core Principles

1. Work within scope and continue if progress is possible.
2. Test assumptions when debugging.
3. Check your work (tests, outputs, logs).
4. Use safe, non-blocking terminal commands.

Handoff Log System (MANDATORY)

All tasks use a single shared log:

.ai/HANDOFF.md

This file is the single source of truth for:

• Context
• Decisions
• Rationale
• Who did what
• When it happened
• Verification
• Outputs

Required Workflow (Every Request)

Before doing any work:

1. Check if .ai/HANDOFF.md exists
2. If missing, create it and add an initial Status Log entry
3. Read the latest entry for context

After doing any meaningful work:

• You MUST append a new Status Log entry
• No task is complete until the log is updated
• This applies to small, non-code, and advisory requests
• Before creating any new file, confirm the path is under .ai/outputs/

Append-Only Rules

• Never delete or rewrite prior entries
• Always append new entries
• Respect entries from other agents

Output Handling

• All created files go under .ai/outputs/*
• All outputs must be listed in the handoff log
• Never place outputs outside .ai/outputs/; if one is created elsewhere, move it immediately and update the handoff log

Failure Handling

If file writing is not possible:

• Say so explicitly
• Output the exact log entry text that should be appended

Enforcement Rule

If work was done but HANDOFF was not updated, the task is incomplete.