init-codebase

name

init-codebase

description

Initialize ANY codebase for agent-driven development in one command. Scaffolds the loop-engineer knowledge-base model (ARCHITECTURE.md, signals/, domains/, LOG.md, docs/ schema), updates CLAUDE.md with Operating Context and Knowledge base section, installs .claude/ harness skills (new-loop, setup-codebase-harness, dev-local-setup, e2e-setup, pr) and workflows (ship-change.js), and optionally updates AGENTS.md. Use when: (1) onboarding a new/unfamiliar repo to agent-driven development, (2) setting up a fresh project for autonomous loop-based work, (3) the user says 'make this repo agent-ready', 'harness this codebase', 'setup the codebase harness'. Does NOT overwrite existing CLAUDE.md knowledge base section — gives guidance for manual update instead.

Init Codebase — Make any repo agent-ready

Scaffold the full loop-engineer harness into a target codebase in one command.

Quick start

# From the target repo directory:
bash <skill-dir>/scripts/scaffold-codebase.sh /path/to/your/repo

# Or with git check bypass:
bash <skill-dir>/scripts/scaffold-codebase.sh /path/to/your/repo --force

Where <skill-dir> is the directory this SKILL.md lives in (find it with dirname $(realpath ${BASH_SOURCE[0]}) or just tell the user to run from within the skill).

What the scaffold does

Action	What it creates/modifies
Knowledge-base model	ARCHITECTURE.md — the artifact/domain model
Global work log	LOG.md — append-only per-bulk journal
Evidence signals	signals/README.md — schema for deduped observations
Workstream loops	domains/README.md — schema for loop domains
Docs schema	docs/README.md — adds kind: doc frontmatter schema
CLAUDE.md	Creates from template ({{PLACEHOLDER}}s) or warns if KB section missing
.claude harness	Copies skills (new-loop, setup-codebase-harness, dev-local-setup, e2e-setup, pr) + workflows (ship-change.js)

What it does NOT do

• Does NOT overwrite an existing CLAUDE.md that has a Knowledge base section — it only warns
• Does NOT modify AGENTS.md automatically (too project-specific; give guidance below)
• Does NOT modify .gitignore to un-ignore .claude/ (your choice)
• Does NOT add files to git or commit

After scaffold — manual steps

1. CLAUDE.md — add Knowledge base section

If the target repo already has a CLAUDE.md without a Knowledge base section, add one:

## Knowledge base (full model: `ARCHITECTURE.md`)

This repo is both the code workspace and the agent's knowledge base. Artifacts are organized
by **kind** (what they are), with `domain:` as a frontmatter field.

| kind | folder | what it is |
|---|---|---|
| **signal** | `signals/` | Raw evidence: feedback, ideas, observations |
| **doc** | `docs/` | Durable knowledge: analyses, decisions, learnings |
| **domain** | `domains/*/` | Workstream loops — each has a README + optional metrics |

**Rules:** One concept = one home; link via [[slug]]; body + Timeline; LOG.md per bulk.
Default to `doc` or `signal`. Domains link artifacts, don't contain them.

2. AGENTS.md — add conventions

If the project has an AGENTS.md (or equivalent agent instructions), update:

• File Conventions — add rows for signals, doc frontmatter, domain README, LOG.md
• Canonical References — add ARCHITECTURE.md (knowledge-base model) to the priority list
• Worktree Discipline — add isolation/cleanup rules for parallel agent sessions

3. .gitignore

.claude/ is typically gitignored (per-developer config). If you want skills tracked in the repo, remove .claude from .gitignore. This is optional — .claude/settings.json and credentials are local, but skills/ and workflows/ can be shared.

4. Spin up the first loop

# In Claude Code in the target repo:
/new-loop

Name it, describe its goal and cadence. The skill scaffolds domains/<name>/README.md, does one test run, and logs it.

5. Commit

git add ARCHITECTURE.md LOG.md signals/ domains/ docs/README.md
git commit -m "feat: init loop-engineer knowledge base and agent harness"

Architecture reference

Read references/template-architecture.md for the full knowledge-base model design — the two-kind artifact system, domain lifecycle, earning new kinds, and design rationale.

Scaffold script reference

The script lives at scripts/scaffold-codebase.sh. It:

• Copies template files (ARCHITECTURE.md, LOG.md, signals/, domains/, docs/)
• Patches existing docs/README.md to add schema header
• Warns if CLAUDE.md needs a Knowledge base section
• Installs .claude/skills/ and .claude/workflows/ from the asset bundle
• Non-destructive: never overwrites existing files unless specified