agentic-workflow-template
AGENTS.md5 starsChanged 44 days agoMITView on GitHub
This agent contract is informed by the engineering philosophy in docs/philosophy.md — deterministic quality gates, layered hooks, Swiss cheese defence, end-to-end traceability. The guardrails (tests, standards, CI checks) give us confidence in the output. Code review is spot-checking, not line-by-line. If something slips through, we tighten the system. This is a Turborepo monorepo template with a Next.js frontend (apps/web, port 3000) and a NestJS backend (apps/api, port 3001). Shared configuration is centralised in packages/ — TypeScript compiler options, ESLint rules,…
- Reads credentials
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,439 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository24 other files it gives its agents.
- assign-epicSkill
- briefingSkill
- bump-versionSkill
- captureSkill
- consultantSkill
- dependabot-reviewSkill
- fix-cicdSkill
- log-timeSkill
- morlockSkill
- morningSkill
- multi-repoSkill
- nightly-checkSkill
- pickupSkill
- pr-action-review-mine-loopSkill
- pr-action-reviewSkill
- pr-choreSkill
- pr-review-loopSkill
- prSkill
- pushSkill
- qa-review-actionSkill
- refineSkill
- runSkill
- syncSkill
- wrap-upSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
37 rules. About 0 are common, 31 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈31
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 75
Before starting any task, read the relevant context files.
- Distinctive: line 85
If a task spans multiple areas, read all relevant files.
- Distinctive: line 99
Before coding: Read the relevant docs. Your implementation must align with what's documented.
- Distinctive: line 101
If you need to deviate from the docs: STOP. Do not silently diverge.
- Distinctive: line 103
Ask whether we should update the docs to reflect the new direction.
- Distinctive: line 104
Default: update the docs first, then implement.
- Distinctive: line 106
After coding: Check if any docs need updating to reflect what was built.
- Distinctive: line 107
New features or significant changes: Update architecture docs if the system shape changed.
- Distinctive: line 111
If docs are stale or contradictory, flag it.
- Distinctive: line 115
When writing any code always refer to @docs/development/engineering-standards.md for best practices, patterns, and conventions.
- Distinctive: line 131
Read back PROGRESS.md and identify which docs need updating.
- Distinctive: line 132
Update the relevant docs (feature docs, architecture, ADRs, etc.).
- Distinctive: line 133
Delete PROGRESS.md and start fresh for the next feature.
- Distinctive: line 149
Every test must be observed failing for the right reason before it counts.
- Distinctive: line 154
Test after: write the test, then break the implementation to prove the test goes red, and restore.
- Distinctive: line 160
A failing test is a finding, not an obstacle: When one blocks a change: fix the code, or say the test is wrong and why and let the human …
- Very specific: line 168
Every task needs a Jira ticket: No work without a ticket. Exception: chore/ branches (dependency bumps, test maintenance, config …
- Distinctive: line 181
Read context first: Read all relevant documentation files before starting any task.
- Distinctive: line 182
Keep docs in sync: Update documentation in the same PR as code changes.
- Distinctive: line 183
Flag deviations: If implementation needs to differ from documented standards, flag it explicitly and discuss before proceeding.
- Distinctive: line 184
Docs before code: Create or update documentation before coding when work is non-trivial.
- Distinctive: line 185
Observed red: Every test is seen failing for the right reason before it counts (see TDD Workflow above).
- Distinctive: line 186
Small changes: Keep changes small and focused.
- Distinctive: line 187
Tests with features: Every feature or fix includes tests.
- Very specific: line 189
Run verification: Run scripts/verify.sh before opening a PR.
- Distinctive: line 192
Close tickets on merge: When a PR merges, close the corresponding Jira ticket immediately.
- Distinctive: line 193
Respect quality gates: Never bypass lint, typecheck, tests, or CI checks.
- Very specific: line 202
Use any types in TypeScript.
- Distinctive: line 204
Commit a schema change without an accompanying migration file.
- Very specific: line 209
Commit secrets, API keys, credentials, or .env files.
- Very specific: line 213
Create PRs without running scripts/verify.sh.
- Very specific: line 214
Start work without a ticket (except chore/ branches).
- Distinctive: line 222
Before raising any finding, fetch the full PR conversation:
- Distinctive: line 236
Never re-raise an issue that was pushed back on: If the author has already reviewed and rejected a suggestion, raising it again is noise.
- Distinctive: line 257
Only 🔴 findings block approval.
- Distinctive: line 313
Unit test coverage: Must exceed 70%.
- Distinctive: line 316
Mutation testing: Use Stryker (or equivalent) to validate test quality — tests that kill no mutants prove nothing.
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Agent Contract
This agent contract is informed by the engineering philosophy in docs/philosophy.md — deterministic quality gates, layered hooks, Swiss cheese defence, end-to-end traceability.
The guardrails (tests, standards, CI checks) give us confidence in the output. Code review is spot-checking, not line-by-line. If something slips through, we tighten the system.
Project Overview
This is a Turborepo monorepo template with a Next.js frontend (apps/web, port 3000) and a NestJS backend (apps/api, port 3001). Shared configuration is centralised in packages/ — TypeScript compiler options, ESLint rules, Jest presets, and a stub shared library. The entire stack is TypeScript strict-mode. When adopting this template, rename the @template namespace to your own project scope throughout all package.json files. Architecture decisions live in docs/adr/.
Repo Map
apps/web/ — Next.js 15 (App Router) frontend
apps/api/ — NestJS backend
packages/shared/ — Shared types, validation schemas, utilities
packages/ui/ — Shared React component library (stub)
packages/eslint-config/ — Centralised ESLint rules (base / nextjs / nestjs)
packages/jest-config/ — Centralised Jest presets (base / nestjs / nextjs)
packages/tsconfig/ — Centralised TypeScript configs (base / nestjs / nextjs / react-library)
packages/test-utils/ — Shared test data builders and helpers (stub)
docs/ — All documentation (plans, ADRs, architecture, runbooks)
scripts/ — Developer and CI scriptsWorkflow Loop
Proposal -> Plan -> Tickets -> Branch -> Code -> Gates -> Deploy -> Monitor -> Trace back- Work starts from Jira tickets. Every branch references a ticket.
- The active coding agent can pick up tickets from the backlog and execute them with the
pickupskill forPROJ-1. - Fast feedback loops (tests, lint, typecheck) catch problems early.
- CI pipeline and repo hooks act as deterministic guardrails.
- The active coding agent should browse, test, and verify the running app as part of the build experience (e.g. via the Playwright MCP server), not just write code blindly.
The Jira board mirrors this loop, and keeping it in sync is required, not optional. Tickets move forward through four statuses — Backlog (capture) → In Progress (pickup) → In Review (pr) → Done (pr-action-review on merge).
Skill Invocation
.agents/skills/ is the canonical skill source. A skill whose description starts with User-invoked only. may start only when the user names it, or when an already user-invoked workflow explicitly routes to its SKILL.md. Never select one merely because its description matches the task. assign-epic, capture, qa-review-action and run are automatic skills and may be selected when their descriptions match — capture and qa-review-action because asking for them in plain words ("capture that", "work through the QA comments") is itself a request to run them.
A skill whose description starts with Role adapter only. is a role body, not a workflow. It exists to be loaded by its role adapter in .claude/agents/, .codex/agents/, or .github/agents/ — never as a skill in the main loop, and never on a user's behalf. The model and tool guarantees stated in a role description are supplied by the adapter, not by the SKILL.md (a Codex role's sandbox_mode is the exception — see README); loading the body on its own gives you the instructions without the guarantees and makes the description false. To consult a role, delegate to its adapter through whatever mechanism the current runtime provides. If the runtime offers none, the role is simply unavailable there — do not read the body in its place, because that is the same false-guarantee failure.
Consulting the consultant Role
consultant is the escalation path for consequential decisions. Delegate to it — through the runtime's role adapter, never by loading the body — before committing to a non-trivial design choice, before a risky refactor, when a tradeoff is genuinely ambiguous, or when the same failure has beaten you twice. It is read-only: it returns a verdict you act on, it does not edit. Do not consult it for routine work you can handle alone.
It is deliberately not named advisor. Claude Code ships a built-in server-side tool literally named advisor, enabled by the advisorModel setting in .claude/settings.json. The two are different mechanisms, and on Claude Code both are live at once:
Built-in advisor tool | consultant role | |
| Context | The full conversation, every tool call and result | On Claude Code, fresh — the role body, this contract, and the delegation prompt. Not on Codex: a fork inherits the parent's turns unless the delegation sets fork_turns to "none" or a number |
| Grounding | Whatever is already in the transcript | Can read this contract, the relevant docs/, and the implementation — under the ADR reading policy below |
| Timing | The model calls it when it wants; Claude Code prompts it to call before substantive work and before declaring done | You delegate explicitly, at a decision point you chose |
| Guarantee | Server-side, guidance only | A pinned model on all three runtimes; a read-only tool list only where the adapter enforces one |
| Runtimes | Claude Code only | All three |
Treat the built-in tool as the ambient second opinion — it needs no instruction from you. Delegate to consultant when the decision turns on this repo's contract: a documented standard, an ADR, an architecture doc. The built-in tool sees those only if they already happen to be in the transcript; the role goes and reads them.
The fresh-context property is Claude Code's, not the contract's. Codex propagates context with fork_turns: omitted or "all" means the spawned role sees the parent's whole conversation, which is the opposite of the fresh, independently-grounded read the role exists to give. A Codex delegation that wants the role's actual behaviour has to ask for it — fork_turns: "none", or a small number of turns. The role's pinned model does bind on Codex, as last measured — measured, not inferred, on Codex 0.148.0: a consultant spawned from a gpt-6-luna parent ran its own turns on the role's pinned gpt-6-sol, both with fork_turns omitted and with fork_turns: "none" passed explicitly; the child's session rollout records a model switch to the pin before its first turn. The same test on the 5.6 models, on the same Codex version, left the child on the parent's model, as Codex documents for a full-history fork (it inherits the parent's model and does not accept overrides) — so the behaviour has flipped once already. verify:agents asserts the pin is written down, which is not the same as it taking effect: if the model matters, check the child's rollout or set it on the session. The role's sandbox_mode is still instruction-level only on Codex.
Do not read the "read-only" promise as stronger than it is. It is a hard tool restriction only on Claude Code, and even there the declared tools list is not exhaustive — Claude Code injects the built-in advisor tool into subagents on top of it, so a consultant delegation can itself call the advisor and bill another uncached full-transcript read. On Codex it is instruction-level only: a role's sandbox_mode is overwritten by the parent's; see README. What verify:agents actually asserts is narrower than "read-only": that the Claude and Copilot adapters declare exactly the tool lists recorded in the verifier, so a capability cannot be added to either without an explicit edit there.
Never write "consult the advisor" in a prompt, skill, or commit message and expect the role. On Claude Code that phrase resolves to the built-in tool, which silently bypasses every model and tool guarantee the role description promises — the same false-guarantee failure as loading a role body directly.
MCP Servers
.mcp.json configures the shared playwright MCP server (@playwright/mcp) for Claude Code and GitHub Copilot CLI. .codex/config.toml configures the same server for Codex. The run skill in .agents/skills/run/SKILL.md owns browser verification and uses Playwright to browse, click through, and screenshot the running app when it is available. Add further MCP servers to these shared runtime configurations as the project grows (e.g. a design-source server for Figma/Storybook, a CI-status server).
Required Context — Read Before Every Task
Before starting any task, read the relevant context files. Do not code from memory or assumptions.
| Area | Files to Read |
| Always | AGENTS.md, CONTRIBUTING.md |
| Architecture / design decisions | docs/architecture/, docs/adr/ |
| Engineering patterns | docs/development/engineering-standards.md |
| Quality / testing | docs/development/quality-strategy.md |
| Feature work | The Jira ticket — it is the source of truth for acceptance criteria |
If a task spans multiple areas, read all relevant files. When in doubt, read more rather than less.
ADR reading policy
docs/architecture/*.md (once populated) is the current-state layer — read it first, and treat it as the answer for "what's true now." docs/adr/ is an immutable decision log, not required reading on its own. Only open a specific ADR by name when the architecture docs cite it (e.g. "see ADR-0021") or are silent/ambiguous on something you need the historical "why" for. Do not read the whole docs/adr/ folder as a matter of course — as the ADR count grows, several will only partially supersede earlier ones (a specific section, not the whole document), and reading the folder wholesale burns tokens walking chains that a one-line current-state fact in docs/architecture/ would already answer.
This only works if the architecture docs stay in sync: per the Documentation Sync golden rule below, accepting an ADR that changes current-state behaviour (a data flow, a schema, a pattern) requires updating the relevant docs/architecture/*.md file in the same PR — not just writing the ADR. An ADR with no corresponding architecture-doc update is a sync failure, not a future to-do.
CI enforces this with scripts/check-adr-sync.sh: a diff that touches docs/adr/*.md without also touching docs/architecture/*.md fails the build (the check no-ops until docs/architecture/ exists). Some ADRs (tooling/process decisions) genuinely have no current-state doc to update — for those, add [skip-adr-sync: reason] to a commit message on the branch to skip the check. The override is reviewable in the commit history alongside the ADR itself, so keep the reason short but specific (e.g. [skip-adr-sync: CI tooling change, no architecture-doc impact]).
Documentation Sync — The Golden Rule
Documentation is the source of truth. Code follows docs, not the other way around.
- Before coding: Read the relevant docs. Your implementation must align with what's documented.
- If your implementation matches the docs: Proceed. No action needed.
- If you need to deviate from the docs: STOP. Do not silently diverge. Instead:
- Flag the deviation explicitly: what the docs say vs. what you think should change and why.
- Ask whether we should update the docs to reflect the new direction.
- Default: update the docs first, then implement. The docs lead, code follows.
- Also flag if the deviation might indicate we're heading in the wrong direction.
- After coding: Check if any docs need updating to reflect what was built. If you added a new pattern, endpoint, data flow, ADR, or changed behaviour — update the relevant docs in the same PR.
- New features or significant changes: Update architecture docs if the system shape changed. Feature context lives in Jira — not in the repo.
This applies to ALL documentation: architecture, ADRs, conventions, engineering standards, quality strategy, and runbooks.
If docs are stale or contradictory, flag it. Don't guess which version is correct — ask.
Coding Standards
When writing any code always refer to @docs/development/engineering-standards.md for best practices, patterns, and conventions.
PROGRESS.md — Session Scratchpad
Primary development agent only. PROGRESS.md is for the agent actively working a feature or fix on this branch. Secondary agents opened for quick, unrelated tasks (Jira lookups, ticket creation, chore commands, one-off queries) must not write to PROGRESS.md — they have no relevant progress to log and doing so pollutes the scratchpad and triggers the stop hook unnecessarily.
Maintain a PROGRESS.md file in the repo root during development sessions. This is a running log of progress, decisions, open questions, and direction changes.
During a session
- Append progress after completing each ticket or significant milestone.
- Record decisions made, problems encountered, and questions that arose.
- Note any direction changes or deviations from the plan.
Between features / at session end
- Read back PROGRESS.md and identify which docs need updating.
- Update the relevant docs (feature docs, architecture, ADRs, etc.).
- Delete PROGRESS.md and start fresh for the next feature.
PROGRESS.md serves three purposes:
- Progress tracking — proxy for progress against the plan.
- Knowledge capture — temporary home for discoveries during implementation.
- Recovery point — if a session is interrupted, the next session picks up where we left off.
Do not git-ignore
PROGRESS.md. It must be committable to feature branches so the recovery-point use case works across sessions. The pre-push hook and theprworkflow enforce that it is deleted before any PR is raised — that is sufficient. Git-ignoring it breaks cross-session continuity without adding any real protection.
Plans
- End with a concise unresolved questions list.
TDD Workflow (Observed Red)
Every test must be observed failing for the right reason before it counts. A test never seen red carries no evidence that it is wired to the behaviour it claims to cover — a confident assertion against a mocked collaborator goes green against an empty implementation.
Two orders satisfy this:
- Test first (default): write the test, run it red, implement, run it green. Batch the suite — write the tests for the whole ticket's acceptance criteria, watch them all go red, then implement. One-test-at-a-time micro-loops are human working-memory scaffolding; they cost turns here and buy the same evidence.
- Test after: write the test, then break the implementation to prove the test goes red, and restore. Test-after risks deriving assertions from the code rather than the requirement — so write them from the acceptance criteria, not from the implementation.
Exploratory-first is a path, not an exception. When proving out an unfamiliar approach, write the production code first to validate it works, then comment it out and write the tests. The commented-out code is what produces the red run, so this satisfies the rule. Uncomment incrementally to green.
Report the output of both runs — the red run's assertion message and the green run's result, not a bare "tests pass". A test derived from the implementation usually fails in a boring way (wrong field, null reference) rather than the way the requirement predicts, and only the message exposes that.
A failing test is a finding, not an obstacle. When one blocks a change: fix the code, or say the test is wrong and why and let the human decide. Rewriting an assertion to reach green is the human's call.
This applies to unit, integration, and E2E tests.
Absolute Rules
These are non-negotiable. No exceptions, no workarounds.
- Every task needs a Jira ticket. No work without a ticket. Exception:
chore/branches (dependency bumps, test maintenance, config housekeeping) are exempt — use achore/<short-description>branch name and achore:commit prefix. Allfeat/andfix/work still requires a ticket. - Every code change needs a feature branch — named per CONTRIBUTING.md (
<ticket-id>-<short-description>, orchore/<short-description>). - Merge = Close — Close the Jira ticket immediately when the PR merges.
- Never commit a schema change without a migration file — Schema and migration travel together, always.
- ADRs are immutable — Never edit the body of an accepted ADR. The only permitted change is updating its status line to
Superseded by ADR-XXXXand adding the corresponding blockquote pointer. All decision changes require a brand new ADR. SeeCONTRIBUTING.md§ Architecture Decision Records. - Never push with
--no-verifywithout explicit user approval. - Never ignore pre-existing errors — Fix them, don't bypass them.
- Never use
anytypes — Strict TypeScript only. Useunknownand narrow with type guards if the type is genuinely uncertain. - Always use i18n keys (if the project is localised) — Never hardcode user-facing strings.
- Ticket update safety check — Before updating any ticket, check its assignee. If it's assigned to someone other than the current user, or is unassigned, STOP and ask before proceeding.
What Every Agent MUST Always Do
- Read context first: Read all relevant documentation files before starting any task.
- Keep docs in sync: Update documentation in the same PR as code changes. Never let docs drift from reality.
- Flag deviations: If implementation needs to differ from documented standards, flag it explicitly and discuss before proceeding.
- Docs before code: Create or update documentation before coding when work is non-trivial.
- Observed red: Every test is seen failing for the right reason before it counts (see TDD Workflow above).
- Small changes: Keep changes small and focused. Prefer safe refactors.
- Tests with features: Every feature or fix includes tests. Never reduce coverage.
- Strict TypeScript: No
anytypes. Use strict mode, proper generics, and type guards. - Run verification: Run
scripts/verify.shbefore opening a PR. - Follow branching rules: Branch from
main, name branches with ticket IDs (see CONTRIBUTING.md). - Follow commit conventions: Include the ticket ID in commit messages (see CONTRIBUTING.md).
- Close tickets on merge: When a PR merges, close the corresponding Jira ticket immediately.
- Respect quality gates: Never bypass lint, typecheck, tests, or CI checks.
- Test against standards: Explicitly test against WCAG and OWASP compliance standards.
- Trace everything: Include the ticket ID, plan link, and test evidence in PRs.
- Fill the PR template fully: ticket, summary, test evidence, risk, rollback.
What Every Agent MUST Never Do
- Silently deviate from documented architecture, patterns, or standards without flagging it.
- Implement code that contradicts docs without updating the docs first.
- Use
anytypes in TypeScript. Ever. - Hardcode user-facing strings instead of using i18n keys (in localised projects).
- Commit a schema change without an accompanying migration file.
- Push with
--no-verifywithout explicit user approval. - Ignore or suppress pre-existing errors, warnings, or failing tests.
- Force push to protected branches (
main,staging,production). - Disable or skip lint, tests, typecheck, or any CI gate.
- Commit secrets, API keys, credentials, or
.envfiles. - Hard-code credentials or sensitive values in test or application code — read them from environment variables; the only exception is a mocked secrets provider returning fixture values.
- Bypass pre-commit or pre-push hooks.
- Deploy without passing all quality gates.
- Create PRs without running
scripts/verify.sh. - Start work without a ticket (except
chore/branches).
PR Review Standards
These rules apply to all AI-assisted PR reviews on this repo — regardless of which review command, tool, or workflow a developer uses.
Always check conversation history first
Before raising any finding, fetch the full PR conversation:
gh api repos/{owner}/{repo}/pulls/{pr}/comments --paginate
gh api repos/{owner}/{repo}/issues/{pr}/comments --paginate
gh api repos/{owner}/{repo}/pulls/{pr}/reviews --paginateBuild a map of every issue that has been raised before. For each prior finding, determine whether it was:
- Pushed back on — the PR author replied disagreeing, explained why it was intentional, or explicitly rejected the suggestion.
- Accepted and addressed — a fix was committed, or the thread was resolved.
- Still open — raised but not yet discussed.
Never re-raise an issue that was pushed back on. If the author has already reviewed and rejected a suggestion, raising it again is noise. If you believe the pushback was incorrect, note it once in your summary but do not re-list it as a finding.
Verdict and approval rules
| Situation | Verdict |
| No must-fix findings detected | Approve |
| Must-fix findings detected, but all have been pushed back on | Approve — note the outstanding items in the summary for the human reviewer, but do not block the PR |
| Must-fix findings detected and none have been discussed | Request changes |
| Must-fix findings that are new AND genuinely blockers | Request changes |
The goal is to avoid blocking PRs on issues the team has already decided to accept. When in doubt, approve and note — do not block.
A review from a human account counts as a human review, whatever tooling produced it. This is an agentic workflow: reviews and approvals submitted through a coding agent or any reviewer agent are the act of the account owner, who is accountable for them. Never discount, caveat, or re-litigate an approval because its body is attributed to an AI tool, and never tell the user "no human has really reviewed this" on that basis. Only a genuine bot account (user.type of Bot, or a login containing bot/copilot) falls outside this.
Classifying findings
- 🔴 Must fix — bugs, security vulnerabilities, accessibility regressions, broken contracts
- 🟡 Should fix — quality, coverage, convention gaps
- 🔵 Consider — nit, optional improvement
Only 🔴 findings block approval. 🟡 and 🔵 findings are informational — post them, but still approve.
Review comment format
Post findings as a PR comment using gh pr comment:
## AI Review
Reviewed against correctness, TypeScript strictness, OWASP, WCAG AA, test coverage, conventions, docs sync, and performance.
**Conversation history checked** — [N previously discussed items were found; X were pushed back on and are not re-listed.]
### Findings
<list each finding with classification emoji, file:line, and one-sentence description>
_or_ ✅ No findings — all lenses clear.
### Previously discussed — not re-raised
<list any issues found in the diff that were previously raised and pushed back on, with a one-line note: "Raised previously by @reviewer — author pushed back, not re-raised.">
_or_ (omit this section if none)
### Verdict
<Approve / Request changes — and why in one sentence>After posting the review comment — submit the formal GitHub review
This step is mandatory. A gh pr comment does not record a verdict in GitHub's review system. Always follow it with:
gh pr review <pr-number> --approve --body '<one-line verdict summary>'
# or
gh pr review <pr-number> --request-changes --body '<one-line verdict summary>'The body should be a single sentence summarising the verdict (e.g. "No 🔴 findings — approving. One 🟡 noted in the review comment above." or "🔴 must-fix: <brief description> — see review comment above."). This is what shows up in GitHub's review status and counts toward branch protection approval requirements.
Commands for Validation
scripts/verify.sh # Run the full verification suite (same as CI)
npm run lint # ESLint across all packages
npm run typecheck # TypeScript compilation check
npm run test # Unit tests
npm run test:e2e # End-to-end tests
npm run build # Production buildQuality Standards
- Unit test coverage: Must exceed 70%.
- WCAG: AA compliance required. Test with axe-core or equivalent.
- OWASP: Top 10 vulnerabilities must be checked. Use security scanning in CI.
- Mutation testing: Use Stryker (or equivalent) to validate test quality — tests that kill no mutants prove nothing.
- Design integrity: UI work must be checked against the design source (e.g. Figma via MCP).
Observability
- Structured JSON logging from day one.
- trace_id and correlation_id propagated through all API boundaries.
- Error tracking for both frontend and backend.
- Runbooks in
docs/runbooks/for top incident types.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

