AGENTS.md

Scope

This file defines repository-wide workflow and documentation rules. Cross-harness principles live in SYSTEM.md; more-specific AGENTS.md files add local contracts without weakening higher-priority safety or integrity requirements.

Lifecycle

For non-trivial work, use a proportionate lifecycle:

1. Specify — define the goal, acceptance criteria, constraints, risks, and out-of-scope work.
2. Understand and route — inspect the relevant documentation, code, configuration, existing patterns, skills, and tools.
3. Plan — identify affected files and symbols, state ownership, sequence changes, and choose verification checks.
4. Implement — make the smallest correct change; preserve required behavior and keep the working tree focused.
5. Validate — run the strongest applicable checks and inspect changed behavior and the final diff.
6. Close — update affected documentation, record evidence and gaps, and summarize the result.

Phases may loop backward when validation reveals a design or planning problem. Trivial work may collapse phases; do not add process that does not improve correctness.

State assumptions. Ask only when unresolved ambiguity materially changes scope, safety, or behavior. Do not silently choose between materially different interpretations.

Repository Awareness

Before architectural decisions or edits:

• Start at the repository root and walk to each target path.
• Read every applicable parent and child AGENTS.md in that path.
• Read nearby project documentation and relevant configuration.
• Treat the nearest applicable AGENTS.md as the local contract; parent documents provide broader rules.

Do not infer conventions from memory. If documentation conflicts, follow higher-priority instructions and the most specific applicable local contract.

Skill and Tool Routing

Before planning or implementing non-trivial work, use skill-orchestration when available:

• discover the current skill catalog
• select only skills with a concrete role in the task
• resolve and read selected skill instructions
• choose tools based on the actual files, behavior, and verification needs

Do not load every domain skill or duplicate a static routing matrix. If no skill matches, continue with the applicable repository instructions and tools.

Repository Legibility

Prefer project workflows that provide:

• deterministic setup and repeatable commands
• explicit dependencies, versions, and environment selection
• isolated workspaces and test targets
• structured output with actionable paths, locations, and errors
• local observability through tests, logs, dev servers, or browser automation

If a required feedback loop is unavailable, record that verification gap rather than treating an unobserved result as passing.

Minimal Changes

Implement only what the request requires. Do not:

• add future-proofing without a demonstrated need
• introduce single-use abstractions
• rewrite working code unnecessarily
• modify unrelated files
• clean up adjacent code unrelated to the outcome

Supporting tests, documentation, generated files, imports, and shared root-cause fixes are in scope when required for correctness. Minimal does not mean incomplete.

Data Safety

Follow SYSTEM.md → Safety and Data Integrity for every database-handling project.

Test Database Guardrails

• Never run database-backed tests, seeders, or fixtures against a target loaded from local .env or another development/local environment.
• Before any test suite, inspect test environment selection, configuration, bootstrap/setup, fixtures, hooks, and reset behavior.
• Run tests only with an explicit test selector and a provably test-only, in-memory, or dedicated database. The selector alone is not proof when variables or cached configuration can override the target.
• Do not rely on a default environment or bare test command when it can load local .env. For Laravel, include --env=testing even for filtered or targeted runs.
• A testing request authorizes reset only for the verified isolated test database. Destructive operations against another database require explicit user authorization naming the operation and target.

Verification

Before verification, identify the repository's supported commands and target environment. For non-trivial work, run a baseline when practical so pre-existing failures are distinguishable from regressions.

Choose checks that match changed behavior:

• tests or focused regression tests
• linting and formatting checks
• type checking and builds
• static analysis and integration checks
• documentation/configuration parsers
• local runtime, browser, or API observation

Do not require a test when behavior cannot be meaningfully tested; use the strongest alternative and explain the gap. Never claim a check passed unless it was run and its result is known.

For refactors, preserve behavior. For bug fixes, reproduce when practical and verify the reported path. For features, verify acceptance criteria and regression risk.

Closure and Shipping

Before declaring work complete:

• inspect the final diff for scope, accidental changes, and generated artifacts
• update documentation when contracts, ownership, architecture, or workflow changed
• report changed files, verification commands/results, baseline failures, and remaining risks
• obtain required human review; automated checks do not replace human judgment

Commit, push, merge, deploy, or create an MR/PR only when explicitly requested, using the repository's approved Git workflow.

Documentation (DOX)

Documentation should evolve with architecture. Update existing documentation before creating new documentation.

Create a child AGENTS.md only when introducing a meaningful architectural boundary or persistent local convention. Child documents should describe:

• Purpose
• Ownership
• Local Contracts
• Work Guidance
• Verification
• Child Documentation Index

Avoid duplicating rules already documented higher in the hierarchy. Remove stale or contradictory text when changing a contract.

Child Documentation Index

No child AGENTS.md files are needed for the current repository structure. Root-owned files include root-level project documentation and instruction files.

Continuous Improvement

Record stable discoveries—recurring mistakes, architectural constraints, module ownership, hidden assumptions, and important conventions—in the appropriate documentation level. Keep temporary findings in the task response.

Success Signals

A healthy repository demonstrates:

• small, focused, reversible changes
• explicit ownership and consistent conventions
• deterministic workflows and repeatable verification
• accurate, current documentation
• human review at appropriate risk boundaries
• fewer repeated mistakes