An archetype for creating governed, multi-repo workspaces where AI agents (Claude Code, Codex, or others) operate under shared policy, hooks, and knowledge management. No application code lives here — this repo coordinates child repos that contain it.
- Clone this archetype and run
init-project.shto scaffold a new governance root - A log repo is created automatically inside
repos/for session logs, notes, and handoffs - Register child repos — your actual application code — under this root
- AI agents read
AGENT.md(engine-neutral) for operating instructions, then engine-specific pointers (CLAUDE.md,CODEX.md) wire hooks and skills
- bash, git, python3, jq
- Optional: GitHub CLI (
gh) for session PRs and user detection
# Create a new governed project (in-place, after cloning the archetype)
git clone <archetype-url> my-project && cd my-project
./init-project.sh my-project
# Or with child repos and guided wizard
./init-project.sh my-project \
--repos "api:/path/to/api,web:/path/to/web" \
--guided
# Copy mode (scaffold into a different directory)
./init-project.sh my-project --copy-to /path/to/target
# Custom log repo location (default: repos/<name>-logs/)
./init-project.sh my-project --log-repo /path/to/custom-logs
# Register more repos later
scripts/repos/register-repo.sh my-lib /path/to/my-lib --purpose "shared library"Quick mode scaffolds the full structure and you configure manually.
Guided mode (--guided) also drops a .needs-init marker — on the next
agent session, the init wizard walks through repo registration, maintainer setup,
hook selection, knowledge seeding, and role customization interactively.
├── AGENT.md # Engine-neutral agent instructions (primary)
├── CLAUDE.md # Claude Code engine wiring (generated, gitignored)
├── CODEX.md # OpenAI Codex engine wiring (generated, gitignored)
├── MAINTAINERS.json # Who can modify protected files
├── agents/
│ ├── shared/ # Cross-cutting policy (constraints, standards, workflows)
│ ├── roles/ # Role overlays (6-section schema per role)
│ └── skills/ # Engine-neutral skill definitions + catalog
├── scripts/
│ ├── hooks/ # All hooks (5 default, 8 optional) + lib/
│ ├── validate/ # Governance validators
│ ├── session/ # Session lifecycle
│ ├── repos/ # Child repo management
│ └── utils/ # Logging, analysis, generation
├── knowledge/
│ ├── wiki/ # Master wiki (maintainer-curated)
│ └── research/ # Master research intake (promoted from member intake)
├── logs/ # Stub — actual data in log repo
├── notes/ # Stub — actual data in log repo
├── repos/
│ ├── <project>-logs/ # Log repo (logs, notes, handoffs, per-member wikis + research)
│ └── <child-repo>/ # Registered application repos (symlink or physical)
├── secrets/ # Protected paths (contents gitignored)
└── local/ # Per-machine customization (gitignored)
Note:
CLAUDE.md,CODEX.md, and.claude/are generated byscripts/utils/generate-engine.sh(called duringinit-project.sh) and are gitignored. OnlyAGENT.mdis committed.
Every initialized project gets a dedicated log repo at repos/<project>-logs/.
This is a separate git repository with no branch protections, so all team members
can push session logs freely — even when the root repo has required reviews or CI gates.
The log repo contains:
| Directory | Contents |
|---|---|
logs/audit/<user>/ |
Per-user audit trails |
logs/progress/<user>/ |
Daily session progress reports |
logs/agent_audit.log |
Append-only audit trail (JSONL) |
notes/<user>/handoffs/ |
Work tracking documents (active/completed) |
notes/<user>/research/ |
Per-member research intake (promoted to master by maintainers) |
notes/<user>/facts.md |
Cross-session facts cache |
wiki/<user>/ |
Per-member wiki compilations |
The log repo is registered as a child repo and discovered via
.archetype-manifest.json → log_repo_name → repos/<name>.
Hooks enforce policy during agent sessions. Five are wired by default in
.claude/settings.json:
| Hook | Trigger | Purpose |
|---|---|---|
session-start.sh |
SessionStart | Resolve user, branch, load context |
session-end.sh |
SessionEnd | Write progress, push to log repo |
check_secrets_read.sh |
PreToolUse (Read) | Block reads of protected paths |
check_filesystem_path.sh |
PreToolUse (Write) | Prevent writes outside project |
post-tool-use-audit.sh |
PostToolUse | Append-only audit trail |
Eight more ship in scripts/hooks/ but are not wired by default (edit guard,
schema enforcement, correction detection, etc.). Enable them via
.claude/settings.json or the init wizard. See scripts/hooks/README.md.
All hook commands use the ${CLAUDE_PROJECT_DIR:-.}/ prefix for reliable path
resolution regardless of working directory.
Root-archetype ships defensive measures so that any clone has a working
agent-safety baseline before customization. Full reference:
docs/guides/security.md.
| Layer | Mechanism | Where |
|---|---|---|
| Read-side secret protection | Block agent reads of protected paths | scripts/hooks/check_secrets_read.sh (default-on) |
| Write-side filesystem boundary | Prevent writes outside the project tree | scripts/hooks/check_filesystem_path.sh (default-on) |
| Pre-write secret scan | Scan staged content for credential patterns | scripts/hooks/pre-edit-guard.sh + lib/secret-patterns.txt |
| Tool pinning | Hooks resolve git/jq/python3/… via pinned absolute paths instead of $PATH |
scripts/hooks/lib/tools.lock + hook_resolve_tool |
| Hook/validator drift detection | sha256-locked tree of scripts/hooks/ + scripts/validate/; tampering fails CI |
HOOKS.lock + scripts/validate/validate_hooks_lock.sh |
| Dry-run / argv mode | Print the launch chain (paths, env, tools, planned writes) without side effects | session-start.sh --argv, session_init.sh --argv |
| Append-only audit trail | Every tool call logged | scripts/hooks/post-tool-use-audit.sh + scripts/utils/agent_log.sh (default-on) |
| Bounded test execution | Caps for parallelism/timeouts on agent-issued test runs | scripts/hooks/check_test_safety.sh |
| Schema/structure invariants | Agent role + skill + doc-drift validators | scripts/validate/*.py |
| Session isolation | Each session runs on its own branch; identity persisted to .session-identity |
scripts/hooks/session-start.sh |
| Per-user log/notes scoping | Cross-session writes routed under notes/<user>/, logs/progress/<user>/ |
lib/log-repo.sh, hook_ensure_log_dirs |
| Strict mode escape hatch | ARCHETYPE_HOOK_TOOLS_STRICT=1 makes unpinned tools fail hard |
env var, see hook_resolve_tool |
One-time setup after cloning:
scripts/hooks/lib/tools-init.sh # generate per-installation tools.lock
scripts/validate/update_hooks_lock.sh # generate HOOKS.lock for this checkoutAfter upgrades or hook edits, treat both as security events — re-run them deliberately and review the diffs before committing.
Skills are reusable methodology definitions that agents load on demand.
Canonical definitions live in agents/skills/, with a catalog at
agents/skills/DISCOVERY.md.
| Skill | Trigger |
|---|---|
project-wiki |
"lint KB", "compile wiki", "what do we know about X" |
research-intake |
"research intake", "ingest this" |
safe-commit |
"safe commit", "commit with checks" |
simplify |
"simplify", "review code", "clean up" |
new-skill |
"create a skill", "scaffold skill" |
new-handoff |
"new handoff", "track work item" |
init-wizard |
Automatic when .needs-init exists |
wrap-up |
"wrap up", mid-session save, checkpoint progress |
Knowledge flows through a two-tier pipeline. All team members produce into the log repo — notes, progress, research intake. Maintainers curate and promote into the root repo's master wiki and research database.
Log Repo (any team member) Root Repo (maintainer-curated)
┌─────────────────────────────┐ ┌──────────────────────┐
│ notes/<user>/handoffs/ │ │ │
│ notes/<user>/plans/ │──┐ │ │
│ notes/<user>/research/ │ │ │ │
│ logs/progress/<user>/ │ │ │ │
└─────────────────────────────┘ │ │ │
v │ │
┌──────────────────────┐│ │
│ /project-wiki compile││ │
│ --user <username> ││ │
└──────────┬───────────┘│ │
v │ │
┌─────────────────────────────┐ │ │
│ wiki/<user>/ │──┐ │ │
│ (per-member wiki) │ │ │ │
└─────────────────────────────┘ │ │ │
v │ │
┌──────────────────────┐│ knowledge/wiki/ │
│ /project-wiki compile│├─>(master wiki) │
│ --master ││ │
│ (maintainer only, ││ knowledge/research/ │
│ auto when member │├─>(master research) │
│ compiles own wiki) ││ │
└──────────────────────┘└──────────────────────┘
- Write to:
<log-repo>/notes/<your-username>/,<log-repo>/logs/progress/<your-username>/ - Research intake:
/research-intake→<log-repo>/notes/<username>/research/ - Per-member wiki:
/project-wiki compile --user <name>→<log-repo>/wiki/<name>/ - Master wiki + research:
/project-wiki compile --master→knowledge/wiki/+knowledge/research/(maintainer, auto-triggered)
knowledge/wiki/ is the project's compiled reference
documentation for anyone cloning root-archetype to build a new root repo.
Each page indexes the source-of-truth files in this repo (scripts/,
agents/skills/, docs/guides/) and links external references where useful.
| Page | Topic |
|---|---|
| Project Initialization & Setup | init-project.sh quick / guided modes, the init-wizard skill |
| Engine-Neutral Architecture | how the same scaffold runs under Claude Code, Codex, or future engines |
| Hook System & Governance Enforcement | hook events, default vs optional, CWD-independent invocation |
| Security & Hardening | tool pinning, drift detection, dry-run mode, threat model |
| Agent Roles & Engineering Standards | 6-section role schema, instruction budget, harness patterns |
| Documentation & Governance Hygiene | AGENT.md / README conventions, KB linting, drift validators |
| Knowledge Compilation Pipeline | two-tier flow from per-user logs/notes to compiled wiki |
| Operations: Logging, Audit, and Log Push | audit trail, agent_log.sh, push-logs.sh worktree pattern |
| Multi-Repo Coordination & Child Repos | registering, syncing, discovering agents across governed children |
| Skills Framework & Design Patterns | progressive disclosure, trigger-spec descriptions, adding new skills |
The full index lives at knowledge/wiki/README.md.
The root repo governs child repos hierarchically. Shared policy, roles, and knowledge flow downward. Each child repo stays self-contained — the root adds cross-repo awareness, not coupling.
┌─────────────────────────┐
│ root-archetype │
│ shared policy & roles │
│ knowledge/wiki/ │
│ agents/registry.json │
└──┬────────┬────────┬────┘
│ │ │
┌─────┴──┐ ┌───┴────┐ ┌─┴──────┐
│ api/ │ │ web/ │ │ infra/ │
│AGENT │ │AGENT │ │AGENT │
│.md │ │.md │ │.md │
└────────┘ └────────┘ └────────┘
child repo child repo child repo
scripts/repos/register-repo.sh <name> <path> # Register a child repo
scripts/repos/register-repo.sh <name> <path> \
--no-scaffold # Register without agent scaffolding
scripts/repos/scan-agents.sh # Discover agents across repos
scripts/repos/sync-repos.sh # Pull all registered reposRegistered repos get a seeded CLAUDE.md and agent role file if they don't
already have one (unless --no-scaffold is passed). Repos inside repos/ are
detected as physical directories; external repos are symlinked.
python3 scripts/validate/validate_agents_structure.py # Role file schema
python3 scripts/validate/validate_document_drift.py # Structural integrity
python3 scripts/validate/validate_claude_md_consistency.py # Instruction file refs
python3 scripts/validate/validate_skills.py # Skill standardsMIT