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 section | Where | Required |
|---|---|---|
| 1. Product | section | required |
| 2. Roles and authority | section | required |
| 3. Engineering baseline | section | required |
| 4. Principles | section | optional |
| 5. Repository layout and sources of truth | section | required |
| 6. Workflow | section | required |
| 7. Architecture decisions | section | required |
| 8. Testing and evidence | section | required |
| 9. Reporting | section | required |
| 10. Language | section | optional |
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.
# 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 tothat 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
```textapp/ the applicationproject/ vision, PRD, blueprint, roadmap, decisionstests/ 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 ConventionalCommits 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 — 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 tothat 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. -->