Skip to content

AGENTS.md

Used in the playbook Project foundation, stage 8.

Download agents.md — the source, as in the repository.

How to use

The template's own instructions:

Starter from the UASK Engineering Hub, playbook mgmt.project-foundation, stage 8 (format: https://agents.md/). Save as AGENTS.md in the repository root. It is the single normative source of rules for every coding agent and human contributor; tool files point to it and add only tool specifics — for Claude Code a CLAUDE.md with the line "@AGENTS.md". Keep it short: rules here, product intent in project/. Sections marked "Optional" may be deleted; delete these comments when a section is written.

Fields

Front-matter fields and sections of the document the template creates. A section marked Optional in the template may be deleted from a copy; every other field and section stays (tools/check_artifacts.py checks this for the kinds it knows).

Field or sectionWhereRequired
1. Productsectionrequired
2. Roles and authoritysectionrequired
3. Engineering baselinesectionrequired
4. Principlessectionoptional
5. Repository layout and sources of truthsectionrequired
6. Workflowsectionrequired
7. Architecture decisionssectionrequired
8. Testing and evidencesectionrequired
9. Reportingsectionrequired
10. Languagesectionoptional

Example

A filled-in copy for an invented product, templates/examples/agents.md, in the Hub repository.It shows the level of detail to aim for, not text to reuse.

example-agents.md
# AGENTS.md — Fieldnotes
This is the **single normative source** of project rules for every coding agent and contributor.
Tool-specific files (`CLAUDE.md` and others) import or point to this file and add only what is specific to
that tool.
## 1. Product
Fieldnotes is a note-taking app for field researchers who work offline. The repository is `example-org/fieldnotes`.
Intent is in [project/VISION.md](project/VISION.md), requirements in [project/PRD.md](project/PRD.md).
## 2. Roles and authority
| Role | Who | Decides |
|---|---|---|
| Owner | Alex Doe | what `mgmt.roles-and-decision-rights#R9` lists: goals, scope, tier, architecture approval, acceptance, licences, publishing, anything public |
| Technical lead (adviser) | Sam Roe | nothing alone — reviews architecture and risks, writes task briefs |
| Lead | coding agent | everything else: research, design proposals, implementation, tests, docs, evidence |
The lead does not decide on the owner's behalf: scope, the technology stack, licences, anything that is published.
## 3. Engineering baseline
Hub rules apply from `.uask/hub/`; a project rule may tighten them, never weaken them. Tier: standard.
## 4. Principles
- Notes belong to the user: no feature may make a note unreadable without the app.
## 5. Repository layout and sources of truth
```text
app/ the application
project/ vision, PRD, blueprint, roadmap, decisions
tests/ checks; `bash tests/run.sh` runs all of them
```
| Kind of information | Source of truth |
|---|---|
| Rules for agents and contributors | `AGENTS.md` |
| Product intent and requirements | `project/VISION.md`, `project/PRD.md` |
| Architecture | `project/BLUEPRINT.md` |
| Accepted decisions | `project/decisions/NNNN-*.md` with status `accepted` |
| Plan and priorities | `project/ROADMAP.md` + tracker issues and milestones |
## 6. Workflow
Issue, branch `feat/<issue>-<slug>`, change, checks, pull request, review, squash merge. Commits follow Conventional
Commits and name the issue.
## 7. Architecture decisions
ADRs live in `project/decisions/`, from `templates/adr.md`. Agents write `proposed` only; the owner accepts.
## 8. Testing and evidence
`bash tests/run.sh` runs every check locally and in CI. A task is done when its checks were seen to fail before the change and pass after it.
## 9. Reporting
At the end of a task the agent reports the result, the evidence (commit and check output), what was not done and what is not verified.
## 10. Language
Files and issues are in English. The owner may write in any language; the agent answers in the owner's.

Completion checks

A copy is complete when:

  • every required field and section above is present, in the same order, and no bracketed placeholder is left;
  • the template's comments are deleted from the copy;
  • python3 .uask/hub/tools/check_artifacts.py . reports no failure for it: front matter, sections, ids, leftover placeholders and comments (tools/check_artifacts.py, in every release bundle);
  • the exit criteria of stage 8 of the playbook Project foundation are met;
  • the owner has approved it, where the playbook asks for approval. Only the owner sets approved.

Source

templates/agents.md, as in the repository. Placeholders are in square brackets; comments carry the instructions.

agents.md
# AGENTS.md — Product name
<!-- Starter from the UASK Engineering Hub, playbook mgmt.project-foundation, stage 8 (format: https://agents.md/).
Save as AGENTS.md in the repository root. It is the single normative source of rules for every coding
agent and human contributor; tool files point to it and add only tool specifics — for Claude Code a
CLAUDE.md with the line "@AGENTS.md". Keep it short: rules here, product intent in project/.
Sections marked "Optional" may be deleted; delete these comments when a section is written. -->
This is the **single normative source** of project rules for every coding agent and contributor.
Tool-specific files (`CLAUDE.md` and others) import or point to this file and add only what is specific to
that tool.
## 1. Product
<!-- Two to four sentences: what it is, for whom, which repository. Link project/VISION.md and project/PRD.md. -->
## 2. Roles and authority
| Role | Who | Decides |
|---|---|---|
| Owner | … | what `mgmt.roles-and-decision-rights#R9` lists: goals, scope, tier, architecture approval, acceptance, licences, publishing, anything public |
| Technical lead (adviser) | … | nothing alone — reviews architecture and risks, writes task briefs |
| Lead | coding agent | everything else: research, design proposals, implementation, tests, docs, evidence |
<!-- List what the lead does not decide on the owner's behalf (scope, stack, licences, hosting,
production deployment). Never request or print secrets. -->
## 3. Engineering baseline
<!-- Optional for the Hub itself; keep it in every consumer project. Which UASK Engineering Hub release this
project follows and which items apply, referred to by id, never copied. Example:
"Follows UASK Engineering Hub vX.Y.Z (commit or tag): arch.adr, arch.c4-model,
config.conventional-commits, config.semantic-versioning. Project rules below may tighten them,
never weaken a MUST." -->
## 4. Principles
<!-- Optional. A few principles that decide trade-offs in this project. -->
## 5. Repository layout and sources of truth
<!-- A short tree of top-level folders, then one table: kind of information → the file that owns it. -->
| Kind of information | Source of truth |
|---|---|
| Rules for agents and contributors | `AGENTS.md` |
| Product intent and requirements | `project/VISION.md`, `project/PRD.md` |
| Architecture | `project/BLUEPRINT.md` |
| Accepted decisions | `project/decisions/NNNN-*.md` with status `accepted` |
| Plan and priorities | `project/ROADMAP.md` + tracker issues and milestones |
## 6. Workflow
<!-- Issue → branch → change → checks → pull request → review → merge. Branch names, commit convention,
who merges and when (for example: the agent squash-merges its own PR on green CI within an approved
task), what never happens (direct pushes to main, merging on red CI). -->
## 7. Architecture decisions
<!-- Where ADRs live, the template, who writes them (agents: proposed only) and who accepts them. -->
## 8. Testing and evidence
<!-- The one command that runs every check locally and in CI, e.g. `bash tests/run.sh`.
"Done" means verified: the command and its result. -->
## 9. Reporting
<!-- What the agent reports at the end of a task: result, evidence, not done, owner decisions. Details go
to files or the PR, not to chat. -->
## 10. Language
<!-- Optional. Language of repository files and of communication with the owner. -->