ai-os-init
Scaffolds the five-layer AI Operating System structure into any project
directory. Non-destructive by design: existing files are never touched,
hook entries are never duplicated, source trees are never imposed.
No dependencies — needs only Python 3 and bash, both already present on any
machine running Claude Code. The hooks that call formatters or type checkers
(ruff, prettier, tsc, mypy, …) degrade silently when those tools aren't
installed, so nothing ever breaks.
The Five Layers It Wires Up
| # |
Layer |
What gets created |
| 01 |
Memory |
CLAUDE.md — always-loaded project map, conventions, links |
| 02 |
Knowledge |
.claude/skills/new-adr/ + .claude/skills/clean-tests/ — on-demand skills |
| 03 |
Guardrails |
.claude/hooks/ — six PreToolUse/PostToolUse hooks (see below) |
| 04 |
Delegation |
.claude/agents/docs-auditor.md — read-only docs drift subagent |
| 05 |
Docs |
docs/ architecture + decisions (ADR log) + runbooks |
Hooks installed (wired into .claude/settings.json)
| Hook |
Event |
What it does |
guard-secrets.sh |
PreToolUse (Edit/Write) |
Blocks writes to secret-looking files (.env, keys, credentials) |
branch-guard.sh |
PreToolUse (Bash) |
Blocks force-push and direct commit/push to protected branches; runs CI before push |
auto-format.sh |
PostToolUse (Edit/Write) |
Formats the edited file (ruff/black/prettier/gofmt/rustfmt), best-effort |
typecheck.sh |
PostToolUse (Edit/Write) |
Surfaces type errors (tsc/mypy) if the project is configured for them |
n+1-guard.sh |
PostToolUse (Edit/Write) |
Warns on likely N+1 query patterns (DB call inside a loop) |
audit-log.sh |
PostToolUse (Bash) |
Silently appends every bash command to .claude/command-audit.log |
Two of these change git/agent behaviour out of the box: branch-guard.sh
will block commits on main/master/develop/staging/production and force
pushes, and audit-log.sh logs every command. Tell your team these are
active, or drop the hooks you don't want from templates/.claude/hooks/
before sharing.
How to Run
Tell Claude to run the scaffold on the current project:
python3 "${CLAUDE_PLUGIN_ROOT}/skills/ai-os-init/scaffold.py"
# or for a specific path:
python3 "${CLAUDE_PLUGIN_ROOT}/skills/ai-os-init/scaffold.py" /path/to/project
Report the created/skipped/merged summary to the user.
Non-Destructive Contract
- File exists → skip it, report it as "already present"
- File missing → create it from the template
.claude/settings.json → load and merge; append each hook entry only
if a hook with the same command isn't already there — then write back
preserving all existing keysCLAUDE.md exists → leave it byte-identical; note which recommended
sections are absent so the user can fill them in- No
src/ imposed — if the project has src/, lib/, or app/ but
no nested CLAUDE.md, suggest adding one; never create source dirs
What to Do After Scaffolding
After running, guide the user through:
- Fill in
CLAUDE.md — project name, conventions, key commands
- Fill in
docs/architecture.md — tech stack, components, data flow
- Try
new-adr: say "create an ADR about [decision]"
- Try
clean-tests: say "clean up the tests"
- Try
docs-auditor: say "audit the docs"
guard-secrets is already active — it blocks writes to secret-looking files
Template Source
All templates live alongside this skill in templates/. To customise what gets
created in future projects, fork the repo and edit the templates there (editing
the installed plugin cache directly gets overwritten on the next update).
1---2name: ai-os-init3description: Scaffolds an "AI Operating System" project structure into any project, non-destructively — adds only missing pieces, never removes or overwrites anything that already exists. Creates: CLAUDE.md (memory layer), docs/architecture.md + docs/decisions/ + docs/runbooks/ (documentation), tools/scripts/ and tools/prompts/ (utilities), and .claude/ with two example skills (new-adr, clean-tests), six hooks (guard-secrets, branch-guard, auto-format, typecheck, n+1-guard, audit-log), and a read-only docs-auditor subagent — all wired via .claude/settings.json. Requires only Python 3 and bash; no external dependencies. Use when asked to "init Claude Code project structure", "scaffold the AI-OS layers", "add CLAUDE.md hooks subagents to this project", "set up the Claude Code layers", "initialize ai-os", "add the AI operating system structure", "scaffold this project for Claude Code", or "add skills hooks agents here". Safe to re-run — idempotent. Not for non–Claude-Code agents (it scaffolds Claude Code's .claude/ layer) an4---56# ai-os-init78Scaffolds the five-layer AI Operating System structure into any project9directory. **Non-destructive by design**: existing files are never touched,10hook entries are never duplicated, source trees are never imposed.1112**No dependencies** — needs only Python 3 and bash, both already present on any13machine running Claude Code. The hooks that call formatters or type checkers14(ruff, prettier, tsc, mypy, …) degrade silently when those tools aren't15installed, so nothing ever breaks.1617## The Five Layers It Wires Up1819| # | Layer | What gets created |20|---|---|---|21| 01 | **Memory** | `CLAUDE.md` — always-loaded project map, conventions, links |22| 02 | **Knowledge** | `.claude/skills/new-adr/` + `.claude/skills/clean-tests/` — on-demand skills |23| 03 | **Guardrails** | `.claude/hooks/` — six PreToolUse/PostToolUse hooks (see below) |24| 04 | **Delegation** | `.claude/agents/docs-auditor.md` — read-only docs drift subagent |25| 05 | **Docs** | `docs/` architecture + decisions (ADR log) + runbooks |2627### Hooks installed (wired into `.claude/settings.json`)2829| Hook | Event | What it does |30|---|---|---|31| `guard-secrets.sh` | PreToolUse (Edit/Write) | **Blocks** writes to secret-looking files (.env, keys, credentials) |32| `branch-guard.sh` | PreToolUse (Bash) | **Blocks** force-push and direct commit/push to protected branches; runs CI before push |33| `auto-format.sh` | PostToolUse (Edit/Write) | Formats the edited file (ruff/black/prettier/gofmt/rustfmt), best-effort |34| `typecheck.sh` | PostToolUse (Edit/Write) | Surfaces type errors (tsc/mypy) if the project is configured for them |35| `n+1-guard.sh` | PostToolUse (Edit/Write) | Warns on likely N+1 query patterns (DB call inside a loop) |36| `audit-log.sh` | PostToolUse (Bash) | Silently appends every bash command to `.claude/command-audit.log` |3738> Two of these change git/agent behaviour out of the box: **`branch-guard.sh`**39> will block commits on `main/master/develop/staging/production` and force40> pushes, and **`audit-log.sh`** logs every command. Tell your team these are41> active, or drop the hooks you don't want from `templates/.claude/hooks/`42> before sharing.4344## How to Run4546Tell Claude to run the scaffold on the current project:4748```bash49python3 "${CLAUDE_PLUGIN_ROOT}/skills/ai-os-init/scaffold.py"50# or for a specific path:51python3 "${CLAUDE_PLUGIN_ROOT}/skills/ai-os-init/scaffold.py" /path/to/project52```5354Report the created/skipped/merged summary to the user.5556## Non-Destructive Contract5758- **File exists →** skip it, report it as "already present"59- **File missing →** create it from the template60- **`.claude/settings.json` →** load and merge; append each hook entry **only61 if** a hook with the same command isn't already there — then write back62 preserving all existing keys63- **`CLAUDE.md` exists →** leave it byte-identical; note which recommended64 sections are absent so the user can fill them in65- **No `src/` imposed** — if the project has `src/`, `lib/`, or `app/` but66 no nested `CLAUDE.md`, suggest adding one; never create source dirs6768## What to Do After Scaffolding6970After running, guide the user through:711. Fill in `CLAUDE.md` — project name, conventions, key commands722. Fill in `docs/architecture.md` — tech stack, components, data flow733. Try `new-adr`: say "create an ADR about [decision]"744. Try `clean-tests`: say "clean up the tests"755. Try `docs-auditor`: say "audit the docs"766. `guard-secrets` is already active — it blocks writes to secret-looking files7778## Template Source7980All templates live alongside this skill in `templates/`. To customise what gets81created in future projects, fork the repo and edit the templates there (editing82the installed plugin cache directly gets overwritten on the next update).
OmarSaleh506