chore(agent-guidance): add guidance-building skill

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

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

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

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

AGENTS.md

@@ -45,6 +45,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` |

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.
 - **`pr-quality-contract`** — prepare proof-backed PRs with local checks,
@@ -41,10 +43,12 @@ 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. Use `pr-quality-contract` before opening or marking the PR ready.
-6. 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. Use `pr-quality-contract` before opening or marking the PR ready.
+7. For a health-check of the whole repo, run the ArchitectPlaybook audits.

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
@@ -213,6 +214,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.
@@ -225,6 +227,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.
     pr-quality-contract/    PR proof, CI status, risk, and handoff workflow.
 .husky/                     pre-commit, commit-msg, pre-push gates.
 .github/