# Agentic Repo Scaffold

> Scaffold a repo's agent-maintainability contract: AGENTS.md architecture contract + executable verify harness (boundary / giant-file / generated-clean checks) + a single `make verify` / `pnpm verify` + `.agent/` ledgers. Stack-aware. Use on "scaffold AGENTS.md", "set up the agent contract", "add a verification harness", "make this repo agent-maintainable", "wire up make verify", or starting/hardening a repo for long-horizon agent maintenance. Distinct from /init (docs CLAUDE.md): this writes the CONTRACT + executable gates.

- Skill: `xingfanxia/agentic-repo-scaffold` (Agent Skill, multi-file: 17 files)
- Install (CLI): `npx skillmds@latest add xingfanxia/agentic-repo-scaffold`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xingfanxia/agentic-repo-scaffold/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: xingfanxia (https://skillmd.com/u/xingfanxia)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xingfanxia/agentic-repo-scaffold

---


# agentic-repo-scaffold

Turns the agentic-repo-architecture framework into committed, executable artifacts in a target repo.

**Core principle:** instruction files are context, not enforcement. Every architecture rule this skill writes into `AGENTS.md` must have a matching deterministic check in `tools/verify/` and CI, or it will be violated under context pressure.

## When to use / not use

- **Use** for: a new repo, or hardening an existing one toward agent-safe boundaries; adding the verify harness; wiring `make verify`; standing up `.agent/` ledgers for a long refactor.
- **Don't use** for: writing a codebase-walkthrough doc (that's `/init`), or a one-file change. This is repo-infrastructure scaffolding.

## Procedure

Create a todo per step.

### 1. Detect stack and existing surface
- Read `package.json` / `go.mod` / `pyproject.toml` / `Cargo.toml`, the build scripts, and the top-level tree.
- Classify: **frontend/full-stack** (Next.js/React), **backend/service** (API/worker/RPC/events), or **general** (CLI/SDK/lib/monorepo/infra). Monorepo → classify per package.
- Inventory what already exists: `AGENTS.md`, `CLAUDE.md`, any `tools/verify` or check scripts, `.agent/`, `.cursor/rules`, a `verify` command, CI workflow. **Never clobber a richer existing file** — extend it, or write a `.proposed` sibling and diff.
- Load the matching stack reference (bundled in this skill) for the authoritative layer rules / contract tables / acceptance matrix:
  - frontend → `references/frontend.md`
  - backend → `references/backend.md`
  - general → `references/general.md`

### 2. Write `AGENTS.md` (the architecture contract)
- Start from `templates/AGENTS.template.md`. Fill in: real architecture map (use the ACTUAL directory names in this repo — don't impose `core/application/ports/adapters` names if the repo already has a working, legible convention; map the *roles* onto its real paths), import rules, contract rules, file limits, the verify command, and the done-definition.
- Enrich the stack-specific sections (layer table, boundary rules, backend contract list) from the matching reference file's §6/§8. Keep it a routing map, not a knowledge dump — link to deeper docs rather than inlining them.
- If `CLAUDE.md` is absent, drop the thin pointer from `templates/CLAUDE.pointer.md`. If it exists and is substantive, leave it; just ensure it references `AGENTS.md`.

### 3. Install the verification harness
- Copy from `templates/`, adapting globs/paths to the repo:
  - `check-giant-files.mjs` (language-agnostic LOC gate; or `check-giant-files.py` for non-JS repos)
  - `check-boundaries.mjs` (forbidden-import / purity check — set the layer regexes to the repo's real paths)
  - `check-generated-clean.sh` (regenerate + `git diff --quiet`; skip if the repo has no generated code)
- Wire ONE canonical command running the full gate set. Match the repo's runner:
  - JS/TS → a `verify` script in `package.json` (typecheck → lint → unit → contract → e2e/visual where present → architecture checks).
  - Go → a `make verify` target (`go vet` → `golangci-lint` → `go test ./...` → arch/giant-file checks).
  - Python → `make verify` (`ruff`/`mypy` → `pytest` → checks).
- Use `templates/Makefile.fragment` or `templates/package.verify.json` as the starting shape.

### 4. Stand up `.agent/` ledgers (only for genuine long-horizon work)
- Create `.agent/PROGRESS.md`, `.agent/EVIDENCE.md`, `.agent/DECISIONS.md` from `templates/agent-ledgers/`.
- These are repo-committed ledgers for *multi-session refactors* — not session-handoff scratch files. Name them PROGRESS/EVIDENCE/DECISIONS, commit them, and skip this step for a fresh repo with no active long refactor.

### 5. Optional: Cursor rules
- If the repo uses Cursor, drop the scoped `.cursor/rules/*.mdc` from the matching reference §8 (boundaries rule + verification rule). Skip otherwise.

### 6. Optional: CI gate
- If a CI workflow exists, add a job that runs the canonical verify command. If not, offer `templates/ci-verify.yml` (GitHub Actions). A check that isn't in CI is advisory only.

### 7. Verify the harness actually runs
- Run each new check script and the verify command. They must execute (even if they report pre-existing violations — that's signal, surface it). A scaffold that doesn't run is not done.
- Report: what was created/extended, which checks pass vs. flag existing debt, and the exact `verify` command. Do **not** mark done from inspection — show command output.

## Notes
- Templates and the `references/` blueprint ship inside this skill, so the package is self-contained.
- Be surgical: in an existing repo, adapt to its conventions rather than imposing the reference's directory names. The *roles* (pure core, orchestration, ports, adapters, isolated generated, thin transport) are the invariant; the *names* are the repo's.