micheleromano/agent-scaffold

Answer a few questions about a project and get a working Claude Code setup: instructions, permissions, path-scoped rules, a review skill, subagents and safety hooks.
uv run agent-scaffold init path/to/project
## What it writes
| File | Purpose |
| AGENTS.md | Project overview, stack, commands, architecture, conventions and working principles, in the open AGENTS.md format other coding agents read too |
| CLAUDE.md | Imports AGENTS.md (@AGENTS.md), then adds what's specific to Claude Code |
| CLAUDE.local.md | Your machine-specific notes; gitignored |
| .claude/settings.json | Allows your test/lint/dev commands, denies reading .env, wires up hooks |
| .claude/rules/.md | Code-style and testing rules scoped with paths: to the files they cover, plus conventions for the project's role (see below) |
| .claude/skills//SKILL.md | /plan before building, /review the current diff, /ship (checks, review, then commit and PR once you confirm), /ci (a GitHub Actions workflow and status badge, using the action versions current when it runs), and /choose-stack when the stack isn't decided |
| .claude/rules/humane-design.md | Always: the Center for Humane Technology's principles as concrete guardrails (see below) |
| .claude/agents/humane-design-reviewer.md | Always: reviews a diff against all seven principles |
| .claude/agents/.md | Optional code reviewer, security auditor and test writer subagents |
| .claude/hooks/.py | Always: block destructive shell commands. With a formatter: format each file after Claude edits it |
| .gitignore | Adds CLAUDE.local.md and .claude/settings.local.json (merged, never replaced) |
Formats follow the current Claude Code docs. Custom commands now live in skills, and hooks are configured in settings.json, so there is no separate commands/ directory.
## One file for every agent
The project context lives in AGENTS.md, so Codex, Cursor and other agents that read the format get the same instructions as Claude. CLAUDE.md starts with @AGENTS.md, which Claude Code needs: it skips a standalone AGENTS.md whenever a CLAUDE.md or CLAUDE.local.md exists (docs). If your project already has a CLAUDE.md, the CLI offers to move it into AGENTS.md and add the import for you.
## How agents work
AGENTS.md includes six working principles. The first four are adapted from Andrej Karpathy's notes on LLM coding mistakes, as collected in andrej-karpathy-skills; the fifth comes from the humane design principles below, and the sixth keeps dependencies current:
1. Think before coding: state assumptions, surface ambiguity, ask when unclear.
2. Keep it simple: the least code that solves the problem.
3. Make surgical changes: every changed line traces back to the request.
4. Work toward a verifiable goal: turn tasks into checks and loop until they pass.
5. Keep people in control: ask before irreversible or outward-facing actions; report what was and wasn't verified.
6. Use current, compatible dependencies: look up the latest stable versions when adding or upgrading packages, check they work together, and keep versions only in the package file and lockfile.
## Humane design guardrails
Every project gets guardrails adapted from the Center for Humane Technology's Principles of Humane Technology. The seven principles are values, so the rule turns each one into something Claude can act on: