AGENTS.md

AGENTS.md is the workspace-level project instruction file. It lets project rules live with the repo, so every prompt does not need to repeat build commands, code style, safety boundaries, and release flow.

In the filesystem-first architecture, AGENTS.md explains how this project works. AgentDir instructions.md explains who one durable agent is. Both enter context composition, but neither can override harness permission gates, response contracts, or verification requirements.

# Project Instructions

- Use `cargo test -p a3s-code-core` for core changes.
- Never commit real secrets from `.a3s/config.acl`.
- Prefer `rg` for search.
- Release checks must include package metadata, CI, and provider verification.

Good Content

• Build, test, lint, format, and release commands.
• Directory responsibilities, module boundaries, and code style.
• Safety rules for secrets, permissions, external side effects, and data handling.
• Verification policy for different kinds of changes.
• Project-specific terminology and common workflows.

Bad Content

• Secrets, tokens, private credentials, or personal machine paths.
• Worker-agent role descriptions; put those in .a3s/agents/.
• Durable-agent identity and default output style; put those in instructions.md.
• Reusable checklists; put those in .a3s/skills/.

Nested Rules

The current runtime auto-loads only the workspace-root AGENTS.md. Nested AGENTS.md files are still useful as repository documentation or host-level conventions, but they are not traversed automatically by A3S Code unless the host reads them and injects their content.

Use nested AGENTS.md files only when subdirectories truly differ, such as a desktop app, API package, or SDK with a different toolchain. Do not copy the root file just to repeat it; duplicated rules make it harder for long-running agents to identify the current source of truth.

Relationship To Other Conventions

repo/
├── AGENTS.md          # project-level durable instructions
├── agent.acl          # runtime config
└── .a3s/
    ├── agents/        # worker/subagent definitions
    └── skills/        # reusable skills

AGENTS.md gives the agent project facts and working boundaries. agent.acl tells the runtime how to connect models and directories. agents/ and skills/ provide discoverable roles and reusable process.