agentleFS
GavinGreenwoodGavinGreenwood/agentic-workflow-template/AGENTS.md

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

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
  1. Distinctive:

    Before starting any task, read the relevant context files.

    line 75
  2. Distinctive:

    If a task spans multiple areas, read all relevant files.

    line 85
  3. Distinctive:

    Before coding: Read the relevant docs. Your implementation must align with what's documented.

    line 99
  4. Distinctive:

    If you need to deviate from the docs: STOP. Do not silently diverge.

    line 101
  5. Distinctive:

    Ask whether we should update the docs to reflect the new direction.

    line 103
  6. Distinctive:

    Default: update the docs first, then implement.

    line 104
  7. Distinctive:

    After coding: Check if any docs need updating to reflect what was built.

    line 106
  8. Distinctive:

    New features or significant changes: Update architecture docs if the system shape changed.

    line 107
  9. Distinctive:

    If docs are stale or contradictory, flag it.

    line 111
  10. Distinctive:

    When writing any code always refer to @docs/development/engineering-standards.md for best practices, patterns, and conventions.

    line 115
  11. Distinctive:

    Read back PROGRESS.md and identify which docs need updating.

    line 131
  12. Distinctive:

    Update the relevant docs (feature docs, architecture, ADRs, etc.).

    line 132
  13. Distinctive:

    Delete PROGRESS.md and start fresh for the next feature.

    line 133
  14. Distinctive:

    Every test must be observed failing for the right reason before it counts.

    line 149
  15. Distinctive:

    Test after: write the test, then break the implementation to prove the test goes red, and restore.

    line 154
  16. Distinctive:

    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 …

    line 160
  17. Very specific:

    Every task needs a Jira ticket: No work without a ticket. Exception: chore/ branches (dependency bumps, test maintenance, config …

    line 168
  18. Distinctive:

    Read context first: Read all relevant documentation files before starting any task.

    line 181
  19. Distinctive:

    Keep docs in sync: Update documentation in the same PR as code changes.

    line 182
  20. Distinctive:

    Flag deviations: If implementation needs to differ from documented standards, flag it explicitly and discuss before proceeding.

    line 183
  21. Distinctive:

    Docs before code: Create or update documentation before coding when work is non-trivial.

    line 184
  22. Distinctive:

    Observed red: Every test is seen failing for the right reason before it counts (see TDD Workflow above).

    line 185
  23. Distinctive:

    Small changes: Keep changes small and focused.

    line 186
  24. Distinctive:

    Tests with features: Every feature or fix includes tests.

    line 187
  25. Very specific:

    Run verification: Run scripts/verify.sh before opening a PR.

    line 189
  26. Distinctive:

    Close tickets on merge: When a PR merges, close the corresponding Jira ticket immediately.

    line 192
  27. Distinctive:

    Respect quality gates: Never bypass lint, typecheck, tests, or CI checks.

    line 193
  28. Very specific:

    Use any types in TypeScript.

    line 202
  29. Distinctive:

    Commit a schema change without an accompanying migration file.

    line 204
  30. Very specific:

    Commit secrets, API keys, credentials, or .env files.

    line 209
  31. Very specific:

    Create PRs without running scripts/verify.sh.

    line 213
  32. Very specific:

    Start work without a ticket (except chore/ branches).

    line 214
  33. Distinctive:

    Before raising any finding, fetch the full PR conversation:

    line 222
  34. Distinctive:

    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.

    line 236
  35. Distinctive:

    Only 🔴 findings block approval.

    line 257
  36. Distinctive:

    Unit test coverage: Must exceed 70%.

    line 313
  37. Distinctive:

    Mutation testing: Use Stryker (or equivalent) to validate test quality — tests that kill no mutants prove nothing.

    line 316

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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 scripts

Workflow 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 pickup skill for PROJ-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 toolconsultant role
ContextThe full conversation, every tool call and resultOn 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
GroundingWhatever is already in the transcriptCan read this contract, the relevant docs/, and the implementation — under the ADR reading policy below
TimingThe model calls it when it wants; Claude Code prompts it to call before substantive work and before declaring doneYou delegate explicitly, at a decision point you chose
GuaranteeServer-side, guidance onlyA pinned model on all three runtimes; a read-only tool list only where the adapter enforces one
RuntimesClaude Code onlyAll 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.

AreaFiles to Read
AlwaysAGENTS.md, CONTRIBUTING.md
Architecture / design decisionsdocs/architecture/, docs/adr/
Engineering patternsdocs/development/engineering-standards.md
Quality / testingdocs/development/quality-strategy.md
Feature workThe 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.

  1. Before coding: Read the relevant docs. Your implementation must align with what's documented.
  2. If your implementation matches the docs: Proceed. No action needed.
  3. 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.
  4. 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.
  5. 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:

  1. Progress tracking — proxy for progress against the plan.
  2. Knowledge capture — temporary home for discoveries during implementation.
  3. 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 the pr workflow 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:

  1. 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.
  2. 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.

  1. Every task needs a Jira ticket. No work without a ticket. Exception: chore/ branches (dependency bumps, test maintenance, config housekeeping) are exempt — use a chore/<short-description> branch name and a chore: commit prefix. All feat/ and fix/ work still requires a ticket.
  2. Every code change needs a feature branch — named per CONTRIBUTING.md (<ticket-id>-<short-description>, or chore/<short-description>).
  3. Merge = Close — Close the Jira ticket immediately when the PR merges.
  4. Never commit a schema change without a migration file — Schema and migration travel together, always.
  5. ADRs are immutable — Never edit the body of an accepted ADR. The only permitted change is updating its status line to Superseded by ADR-XXXX and adding the corresponding blockquote pointer. All decision changes require a brand new ADR. See CONTRIBUTING.md § Architecture Decision Records.
  6. Never push with --no-verify without explicit user approval.
  7. Never ignore pre-existing errors — Fix them, don't bypass them.
  8. Never use any types — Strict TypeScript only. Use unknown and narrow with type guards if the type is genuinely uncertain.
  9. Always use i18n keys (if the project is localised) — Never hardcode user-facing strings.
  10. 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 any types. Use strict mode, proper generics, and type guards.
  • Run verification: Run scripts/verify.sh before 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 any types 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-verify without 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 .env files.
  • 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 --paginate

Build 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

SituationVerdict
No must-fix findings detectedApprove
Must-fix findings detected, but all have been pushed back onApprove — 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 discussedRequest changes
Must-fix findings that are new AND genuinely blockersRequest 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 build

Quality 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.