From b2ada2b64a6f532fb7a7975959ad3760872b52fb Mon Sep 17 00:00:00 2001 From: BenSheridanEdwards Date: Mon, 29 Jun 2026 11:02:50 +0100 Subject: [PATCH] chore(agent-guidance): add guidance-building skill --- .agents/README.md | 1 + .agents/project/AGENTIC_INFRASTRUCTURE.md | 59 +++++++++++++++ .claude/skills/build-agent-guidance/SKILL.md | 72 +++++++++++++++++++ .../build-agent-guidance/agents/openai.yaml | 4 ++ AGENTS.md | 1 + CLAUDE.md | 14 ++-- README.md | 3 + 7 files changed, 149 insertions(+), 5 deletions(-) create mode 100644 .agents/project/AGENTIC_INFRASTRUCTURE.md create mode 100644 .claude/skills/build-agent-guidance/SKILL.md create mode 100644 .claude/skills/build-agent-guidance/agents/openai.yaml diff --git a/.agents/README.md b/.agents/README.md index c098fb6..ce1abb6 100644 --- a/.agents/README.md +++ b/.agents/README.md @@ -13,6 +13,7 @@ changes — no drift between three half-maintained instruction files. | Path | Read it when… | | --- | --- | +| [`project/AGENTIC_INFRASTRUCTURE.md`](project/AGENTIC_INFRASTRUCTURE.md) | …before changing agent guidance, hooks, workflows, or skills. | | [`project/ARCHITECTURE.md`](project/ARCHITECTURE.md) | …before adding or moving any module. It is the pattern you must follow. | | [`project/CONVENTIONS.md`](project/CONVENTIONS.md) | …while writing code — naming, structure, imports, errors, state. | | [`project/DEFINITION_OF_DONE.md`](project/DEFINITION_OF_DONE.md) | …before you claim a task is finished. The gates enforce this list. | diff --git a/.agents/project/AGENTIC_INFRASTRUCTURE.md b/.agents/project/AGENTIC_INFRASTRUCTURE.md new file mode 100644 index 0000000..579afde --- /dev/null +++ b/.agents/project/AGENTIC_INFRASTRUCTURE.md @@ -0,0 +1,59 @@ +# Agentic Infrastructure + +Agentic infrastructure is the repo-level system that lets agents produce +consistent work: instructions, context, templates, hooks, workflows, and proof. +It is not a README flourish. It is part of the engineering surface. + +## The layer model + +Each layer has one job: + +| Layer | Artifact | Job | +| --- | --- | --- | +| Entry contract | `AGENTS.md` | Tool-agnostic rules every agent follows. | +| Tool adapter | `CLAUDE.md` | Claude-specific skills, hooks, and workflow notes. | +| Project context | `.agents/project/` | Durable standards and facts. | +| Decisions | `.agents/decisions/` | Why the standards exist and when they changed. | +| Templates | `.agents/templates/` | Copyable code and test shapes. | +| Local gates | `.husky/` and `scripts/` | Fast feedback before commit and push. | +| Remote gates | `.github/workflows/` | Clean-checkout proof on every PR. | +| Skills | `.claude/skills/` | Reusable agent workflows for repeated jobs. | + +If a rule appears in the wrong layer, agents either miss it or duplicate it. +Move the rule to the layer that owns it. + +## Build order for a new repo + +1. **Inventory truth.** Read package scripts, workflows, hooks, tests, build + config, dependency tooling, and deployment surfaces before writing guidance. +2. **Write the thin entry points.** `AGENTS.md` says how to work here, where to + read next, what commands matter, and what must never be bypassed. `CLAUDE.md` + adds only Claude-specific skills, permissions, and hooks. +3. **Create project context.** Add architecture, conventions, tech stack, + glossary, Definition of Done, ADRs, and templates under `.agents/`. +4. **Make gates match the claims.** Every "done" rule should be enforced by a + command, hook, workflow, or explicit review check. +5. **Package repeated work as skills.** If agents will perform a workflow more + than once, put the workflow in `.claude/skills/` instead of rediscovering it. +6. **Verify and publish proof.** Run the relevant local gates, then rely on CI as + the clean-checkout proof. + +## Truth rules + +- Do not claim a gate exists unless the hook, script, or workflow exists. +- Do not document commands that fail in a clean checkout. +- Do not describe a future architecture as current fact. Mark it as a target or + create an ADR. +- Do not let root instructions drift from `.agents/`. The root files point in; + `.agents/` carries the detail. +- Do not put private project facts in this public template. + +## What makes it north-star quality + +- Agents can start from `AGENTS.md` and find every relevant standard. +- Tool-specific instructions are isolated and replaceable. +- The Definition of Done maps to executable gates. +- PR proof separates local checks, CI, visual/runtime evidence, and gaps. +- The repo includes skills for the workflows agents repeat. +- A brownfield repo can copy the pattern one layer at a time without adopting a + different product stack. diff --git a/.claude/skills/build-agent-guidance/SKILL.md b/.claude/skills/build-agent-guidance/SKILL.md new file mode 100644 index 0000000..af8dc33 --- /dev/null +++ b/.claude/skills/build-agent-guidance/SKILL.md @@ -0,0 +1,72 @@ +--- +name: build-agent-guidance +description: >- + Create or update repository guidance for agentic engineering. Use when working + on AGENTS.md, CLAUDE.md, .agents/project files, agent instructions, repo + conventions, Definition of Done, or guidance that tells agents how to work in a + codebase. +--- + +# Build Agent Guidance + +Use this skill to make a repository self-explanatory to agents without turning +the root docs into a second codebase. + +## Read First + +- `git status --short --branch` +- `package.json` or the repo's equivalent command manifest +- existing CI workflows, hooks, and scripts +- `AGENTS.md`, `CLAUDE.md`, and `.agents/` +- `.agents/project/AGENTIC_INFRASTRUCTURE.md` when present + +## Process + +1. **Inventory before writing.** Verify real commands, scripts, hooks, + workflows, test runners, formatters, and deployment surfaces from files. Do + not trust stale prose. +2. **Separate layers.** Keep `AGENTS.md` tool-agnostic. Put tool-specific + behaviour in `CLAUDE.md`, `.claude/settings.json`, hooks, and skills. Put + durable project knowledge in `.agents/`. +3. **Keep root docs thin.** `AGENTS.md` should answer: what this repo is, how to + run it, golden rules, where to read next, and safety boundaries. +4. **Make `.agents/` canonical.** Put architecture, conventions, tech stack, + glossary, Definition of Done, and ADRs under `.agents/`. If a rule needs more + than a few lines, it belongs there, not in the root entry points. +5. **Tie claims to gates.** If guidance says "done means X", point to the hook, + script, workflow, or command that enforces X. If no gate exists, either add + one in a separate quality-gate change or state the rule as review-only. +6. **Flag inconsistencies.** If existing code follows one pattern and docs claim + another, do not smooth it over. Update the docs to truth, fix the code, or + record the gap. +7. **Verify the docs.** Run the repo's lightest relevant doc/format gate, then + the full gate suite when guidance changes affect Definition of Done, scripts, + hooks, or workflows. + +## Layer Contract + +- `AGENTS.md`: portable operating contract for any agent or engineer. +- `CLAUDE.md`: Claude-specific adapter, local skills, allowed commands, and + hooks. +- `.agents/README.md`: index for project context. +- `.agents/project/`: durable standards and facts. +- `.agents/decisions/`: ADRs for choices that future agents must understand. +- `.agents/templates/`: copyable patterns for new code and tests. +- `.claude/skills/`: executable workflows for repeated agent jobs. + +## Anti-Patterns + +- Do not duplicate the same rule in three places with slightly different words. +- Do not list tools that are not installed or gates that do not run. +- Do not add private project names, secrets, customer data, or local paths to a + public template. +- Do not add ESLint, Prettier, a second test runner, or another duplicate tool + unless the tech-stack contract changes through an ADR. + +## Done When + +- The guidance describes the current repo accurately. +- Every new or changed instruction has an owner: root contract, tool adapter, + `.agents/` standard, hook, workflow, script, or ADR. +- Skill frontmatter validates with the skill validator when a skill changed. +- Verification commands and any remaining gaps are reported explicitly. diff --git a/.claude/skills/build-agent-guidance/agents/openai.yaml b/.claude/skills/build-agent-guidance/agents/openai.yaml new file mode 100644 index 0000000..59f89cb --- /dev/null +++ b/.claude/skills/build-agent-guidance/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Build Agent Guidance" + short_description: "Create truthful AGENTS and CLAUDE guidance." + default_prompt: "Use $build-agent-guidance to update AGENTS.md, CLAUDE.md, and .agents." diff --git a/AGENTS.md b/AGENTS.md index 3b58ee9..dc799fa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -43,6 +43,7 @@ pnpm e2e # the end-to-end behaviour map | Need | File | | --- | --- | +| How the agentic infrastructure is layered | `.agents/project/AGENTIC_INFRASTRUCTURE.md` | | The pattern to follow | `.agents/project/ARCHITECTURE.md` | | Naming, imports, errors | `.agents/project/CONVENTIONS.md` | | When am I done? | `.agents/project/DEFINITION_OF_DONE.md` | diff --git a/CLAUDE.md b/CLAUDE.md index 1bd9107..fe08d82 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -19,6 +19,8 @@ the Claude-Code-specific layer on top. This repo commits its own skills under `.claude/skills/`: +- **`build-agent-guidance`** — create or update `AGENTS.md`, `CLAUDE.md`, + `.agents/`, and agent-facing repo standards from current evidence. - **`run-e2e-tests`** — map a behaviour to a Playwright test and run it. - **`write-unit-tests`** — Jest + React Testing Library, behaviour-first. @@ -39,9 +41,11 @@ fails, fix the cause. ## The workflow for a change -1. Read `.agents/project/ARCHITECTURE.md` + `CONVENTIONS.md`. -2. Use the `run-e2e-tests` / `write-unit-tests` skills; copy from +1. Read `.agents/project/AGENTIC_INFRASTRUCTURE.md` before changing guidance, + hooks, workflows, or skills. +2. Read `.agents/project/ARCHITECTURE.md` + `CONVENTIONS.md`. +3. Use the `run-e2e-tests` / `write-unit-tests` skills; copy from `.agents/templates/`. -3. Run `pnpm verify` and `pnpm e2e` until green. -4. Commit with a Conventional Commit message. -5. For a health-check of the whole repo, run the ArchitectPlaybook audits. +4. Run `pnpm verify` and `pnpm e2e` until green. +5. Commit with a Conventional Commit message. +6. For a health-check of the whole repo, run the ArchitectPlaybook audits. diff --git a/README.md b/README.md index c593cc2..2fd0dd0 100644 --- a/README.md +++ b/README.md @@ -40,6 +40,7 @@ to do: - [`CLAUDE.md`](CLAUDE.md) is the Claude-specific layer. It defers to `AGENTS.md` and adds skills and the audit commands. - [`.agents/`](.agents) is the single source of detail. It holds the + [agentic infrastructure layer model](.agents/project/AGENTIC_INFRASTRUCTURE.md), the [architecture pattern](.agents/project/ARCHITECTURE.md) agents must follow, the [conventions](.agents/project/CONVENTIONS.md) for naming, imports, errors, and state, the [Definition of Done](.agents/project/DEFINITION_OF_DONE.md), the @@ -206,6 +207,7 @@ pass. ``` AGENTS.md / CLAUDE.md Agent contract. Thin entry points into .agents/. .agents/ The repo's knowledge (read before writing). + project/AGENTIC_INFRASTRUCTURE.md How guidance, gates, workflows, and skills fit together. project/ARCHITECTURE.md The pattern agents must follow. project/CONVENTIONS.md Naming, imports, errors, state. project/DEFINITION_OF_DONE.md "Done" means these gates are green. @@ -217,6 +219,7 @@ AGENTS.md / CLAUDE.md Agent contract. Thin entry points into .agents/. settings.json Permission allowlist and PreToolUse hook. hooks/block-gate-bypass.sh Refuses --no-verify. Gates are not optional. skills/ This repo's own packaged processes. + build-agent-guidance/ Build truthful AGENTS.md, CLAUDE.md, and .agents context. .husky/ pre-commit, commit-msg, pre-push gates. .github/ dependabot.yml Weekly npm and GitHub Actions updates.