Skip to content

AGENTS.md

Latest commit

 

History

History
83 lines (64 loc) · 3.77 KB

AGENTS.md

File metadata and controls

83 lines (64 loc) · 3.77 KB
Raw

AGENTS.md - Instructions

These rules apply to every task in this project unless explicitly overridden. Bias: caution over speed on non-trivial work.

Project Context

This repository contains accessibility artefacts for the xGov Low-Code community.

  • The planned public site is a static GitHub Pages site under site/.
  • Source datasets stay under root data/<subject>/ directories.
  • The first dataset is Power Apps Canvas Controls accessibility guidance at data/canvas-controls/ppcoe_canvascontrols.json.
  • The canonical implementation plan is agent-docs/2026-06-09-github-pages-site-plan.md.
  • The site is work in progress until further notice.
  • Data refreshes automatically each day from the Defra tenant.
  • The Defra Power Platform Service Team and Defra Accessibility Team own the accessibility statement and review process.
  • Screenshots are coming soon, but must not be rendered until static image assets and suitable alt text are available.

Rule 1 — Think Before Coding

State assumptions explicitly. Ask rather than guess. Push back when a simpler approach exists. Stop when confused.

Rule 2 — Simplicity First

Minimum code that solves the problem. Nothing speculative. No abstractions for single-use code.

Rule 3 — Surgical Changes

Touch only what you must. Don't improve adjacent code. Match existing style. Don't refactor what isn't broken.

Rule 4 — Goal-Driven Execution

Define success criteria. Loop until verified. Strong success criteria let Claude loop independently.

Rule 5 — Use the model only for judgment calls

Use for: classification, drafting, summarization, extraction. Do NOT use for: routing, retries, deterministic transforms. If code can answer, code answers.

Rule 6 — Token budgets are not advisory

Per-task: 4,000 tokens. Per-session: 30,000 tokens. If approaching budget, summarize and start fresh. Surface the breach. Do not silently overrun.

Rule 7 — Surface conflicts, don't average them

If two patterns contradict, pick one (more recent / more tested). Explain why. Flag the other for cleanup.

Rule 8 — Read before you write

Before adding code, read exports, immediate callers, shared utilities. If unsure why existing code is structured a certain way, ask.

Rule 9 — Tests verify intent, not just behavior

Tests must encode WHY behavior matters, not just WHAT it does. A test that can't fail when business logic changes is wrong.

Rule 10 — Checkpoint after every significant step

Summarize what was done, what's verified, what's left. Don't continue from a state you can't describe back.

Rule 11 — Match the codebase's conventions, even if you disagree

Conformance > taste inside the codebase. If you think a convention is harmful, surface it. Don't fork silently.

Rule 12 — Fail loud

"Completed" is wrong if anything was skipped silently. "Tests pass" is wrong if any were skipped. Default to surfacing uncertainty, not hiding it.

Astro Site Rules

These rules apply when building or changing the planned static site.

  • The static site lives in site/; source datasets stay in root data/<subject>/.
  • Use Astro with TypeScript.
  • Use govuk-frontend as the only external UI/design package unless explicitly agreed.
  • Do not use GOV.UK crown assets, official GOV.UK headers, or service-style framing.
  • Use astro add for official Astro integrations.
  • Check current Astro docs before using integrations, content collections, actions, sessions, or deployment config.
  • Treat exported guidance HTML as unsafe: sanitise it at build time before rendering.
  • Do not render Dataverse screenshot URLs until screenshots are exported as static assets.
  • Configure and test Astro site and base for GitHub Pages project hosting.
  • Verification should include build, typecheck/data validation, and accessibility smoke checks when available.