Agent Project Scaffold: a project tree that carries its own rules
by PaperChaseWebb
Stop re-explaining your project to every new agent session. One command lays down a project tree with a short AGENTS.md (purpose, scope, the approval rule, where things live, what done means), one-concern rule files, one-job agent files, a pre-done hook and a project-only .mcp.json. A read-only check runs 23 tests on any project, new or old, and fails on a missing approval rule, an agent with no limits or a secret sitting in a file.
- Price
- $19
- Difficulty
- Beginner
- Setup
- 5 min
- Format
- .md file
agent-project-scaffold-a-project-tree-that-carries-its-own-rules.md · 21 KB · instant download after checkout
Want this built for you instead? We can build it for you.
What you end up with
Every agent that opens the project reads the same short rules, and a check tells you the moment they go missing.
What you get
- scaffold.py init: the whole tree in an empty folder, refuses to overwrite
- scaffold.py check: 23 read-only checks with codes S01 to S23, exit 1 on any high finding
- A short AGENTS.md template and a one-line CLAUDE.md import so the rules never drift
- Starter rules, a review command, builder and reviewer agents, a pre-done hook and a Grok Bot standing order
- A secret scan and .mcp.json checks for literal keys and whole-disk grants
- 29 tests, with a planted fault for every check
Who it is for
Anyone who wants one set of project rules every agent reads, and a check that keeps them honest.
Works with
Solid chips: the agent is named in this listing's own tools list. Dashed chip: Plain Markdown, so it also pastes into other agents such as Grok Bot, Hermes, OpenClaw or Muse. We list those as compatible by format only, not as tested.
Tools needed
Cost to run: The kit is the only purchase. Runs locally with Python.
Time to result: A checked project tree in about 5 minutes
How it works
Create the tree
Run python3 desk/scaffold.py init with your folder, name, owner and purpose.
Expected: 14 files created.
Check it
Run python3 desk/scaffold.py check on the folder.
Expected: scaffold OK: 0 findings.
Open it in your agent
Claude Code reads CLAUDE.md, Codex and Hermes read AGENTS.md, and Grok Bot takes the standing order.
Expected: The agent quotes your approval rule back when asked.
Check an old project
Run check on a project you already have and fix the high findings first.
Expected: A list of gaps by code, highest risk first.
Sample prompts, free to use
Run python3 desk/scaffold.py check on this folder. Group the findings by HIGH, MED and LOW, explain each in one line and propose fixes. Do not edit the Approval rule or any secret; tell me what to change instead.
Prompt 1 of 3.
AGENTS.md is too long. Move detail into rules/ files with one concern each, keep the five core sections in AGENTS.md, and show me the diff before writing.
Prompt 2 of 3.
Free preview of the file
# Agent Project Scaffold
**Stop re-explaining your project to every new agent session. Put the rules in the folder, and check that they are still there.**
Version 1.0, 2026-11-01. By PaperChaseWebb Inc. Works with Grok Bot, Claude Code, Codex and Hermes.
## The problem
Most agent projects keep their rules in someone's head or in last week's chat. A new session, a new teammate or a different agent starts from zero, and the rule that mattered most (do not send, do not deploy, ask first) is the one that gets lost. A single giant rules file is not the fix either: nobody reads 600 lines, agents included.
## The idea
The project tree itself carries the rules. One short `AGENTS.md` with purpose, scope, the approval rule and what done means. Detail lives in small files, one concern each. Each agent file names one job and what it may not do. A hook checks the tree before work is called done. Every major coding agent reads `AGENTS.md` (Claude Code through a one-line `CLAUDE.md` import), so one set of rules covers all of them.
## The tree
```
your-project/
AGENTS.md purpose, scope, approval rule, where things live, done means (under 120 lines)
CLAUDE.md one line: @AGENTS.md
settings.json config, kept apart from instructions
.mcp.json tool connections for this project only, secrets as ${VAR}
rules/ one concern per file (style, testing, data)
commands/ repeat jobs, one file each
skills/ oneTest record
- Date
- Nov 1, 2026
- What was run
- tests/test_scaffold.py (27) and tests/test_mini.py (2) on Linux with Python 3.8, 3.9, 3.11, 3.12 and 3.13; the generated pre-done hook run on a fresh tree.
- Result
- 29 passed, 0 failed on all five versions; every one of 23 planted faults caught by its own code; clean tree and ${VAR} references not flagged.
- Not run
- A live Grok Bot, Claude Code, Codex or Hermes session. macOS or Windows.
Copied from this item's dated test notes. What was not run stays in.
Worth knowing
- A rules file guides an agent; it is not a lock. Pair it with your agent's own permission settings.
- The secret scan catches common key shapes, not every secret.
- The files were checked by the script, not loaded inside a live session of each agent for this release. Tested on Linux only.
- On 2026-11-01: 29 tests passed on Python 3.8, 3.9, 3.11, 3.12 and 3.13, including one planted fault for each of the 23 checks.
Questions
How is this different from the AGENTS.md starter files?
The starter files give you rule text to paste. This kit lays down the whole project tree and adds a check that runs 23 tests on any project, so you find out when an approval rule, an agent limit or a hook goes missing.
Will it overwrite my project?
No. init writes only into an empty folder, and check only reads.
Why one short AGENTS.md instead of one big file?
Long rule files get skimmed by people and agents alike. The core five sections stay short; detail lives in small files, one concern each.
Does it work with my existing CLAUDE.md?
Yes. The check flags a long CLAUDE.md that does not import AGENTS.md, so you can merge them into one set of rules.
Details
Version 1.0 · Updated Nov 1, 2026 · Markdown version of this page
License: Use for yourself, your team or your clients. Do not resell or republish the kit itself. Download terms
Related
Agent Project Scaffold: the five-section AGENTS.md and a six-check scan (free sample)
The five sections every AGENTS.md needs (purpose, scope, approval rule, where things live, done means) and a read-only script that checks one AGENTS.md for length, missing sections and secret keys.
AGENTS.md, CLAUDE.md and Cursor rules starter files
Six fill-in instruction files for coding agents (base, Next.js plus Supabase, FastAPI, browser game, CLAUDE.md pointer, scoped Cursor rules), an Approvals section that makes the agent stop and wait for your yes, a table of what Grok Bot, Claude Code, Codex, Hermes and Cursor each read, a read-only checker for your rule files and 9 prompts to write, trim and test your own.
Stack-specific AGENTS.md and CLAUDE.md: twelve stacks the starter files do not cover
Ready AGENTS.md files for Go, Rust, Chrome extensions, Electron, Tauri 2, Expo, SvelteKit, Astro, Django, Rails, Laravel and Flutter, each with real commands, stack rules and the one file agents most often break, a one-line CLAUDE.md pointer, five prompts and stack_check.py, ten read-only checks that the file fits the repo it sits in.
Agent Skills Workshop: write, test and run SKILL.md skills for Hermes, Claude Code and Codex
A bot template and teaching guide for building your own agent skills instead of collecting other people's. A skill card, a three-skill split for long jobs, a corrections-to-skills loop, an intake check for skills you did not write, four action classes, a SKILLS.md register, an overnight run sheet, eight skill drills, a rules block and 14 prompts. Includes skill_check.py, AGENTS.md with six owner stops, two skills and templates.
Ask-first rules for AI agents: hard nos, approval cards and a test set
Paste-in rules that make an agent ask before it sends, spends, posts or deletes, define what a real yes is, and stop retries after a no, plus 12 test scenarios to check it.
Extension Lockfile: pin your editor extensions and check for persistence after a bad update
Write down the editor extensions you trust at the versions you reviewed, turn off silent updates, and check every machine against that list with a read-only script. Take a baseline of SSH keys, startup entries, crontab and shell files on a quiet day, so when the next bad extension update is announced you can see what changed in one command. Includes an indicator file and runbook for the 2026-10-29 Claude Code extension incident.