Dw Init

dw-init — scaffold a repo for the solo lane

Everything the loop assumes a repo has, written in one gated pass: the .ai/ state the skills read and write, the durable homes they promote into, the guardrail hooks, and a settings file whose allow-list is derived from the project rather than guessed.

What it writes

| Path | Tracked? | Purpose | | ----------------------------------- | ----------------- | -------------------------------------------------------- | | .ai/work/ | tracked | one folder per change (dw-shape writes CHANGE.md) | | .ai/README.md | tracked | what .ai/ is and who owns it | | .ai/backlog/ + its README.md | tracked | one file per follow-up, between changes | | .ai/archive/ + its README.md | tracked | landed change docs — history, not guidance | | docs/decisions/ + its README.md | tracked | durable decision records (dw-land promotes here) | | CONTEXT.md | tracked | the project's glossary — terms only | | AGENTS.md | tracked | the one always-loaded file: rules, commands, Task Router | | CLAUDE.md | tracked | a symlink to AGENTS.md — never a second copy | | scripts/check-agents-docs.mjs | tracked | the gate on that file's budget, router and commands | | .claude/settings.json | tracked | permissions (ask + deny + derived allow) and hook wiring | | .claude/hooks/*.sh | tracked | the guardrail scripts those settings reference | | .worktreeinclude | tracked | gitignored files a fresh worktree should carry in | | .gitignore | tracked | a managed marker block for the personal files | | .husky/ + .lintstagedrc.json | tracked, optional | the pre-commit twin of the hooks — only when opted in |

Deliberately absent: .ai/verify/ and .ai/handoffs/ — the solo lane has one thin closing pass that writes no artifact, and no one to hand off to. Also absent: CLAUDE.local.md. Agent memory is tracked AGENTS.md, because a gitignored file survives neither a fresh clone nor a git worktree, and a second always-loaded file forks the corpus in two — docs/decisions/ in a scaffolded repo carries the record. Personal, cross-project notes belong in ~/.claude/CLAUDE.md. .gitignore still names CLAUDE.local.md so a stray one is never committed, and the hooks still read it when they find one, so a repo scaffolded before this keeps working untouched.

Also absent: an empty docs/agents/. The Task Router ships with rows for what the scaffold actually creates, and the topic layer grows only when dw-land promotes into it — a new topic file and its router row in the same commit.

Templates come from ${CLAUDE_PLUGIN_ROOT}/templates/ — this lane's own payload; the guardrail hooks in it are vendored copies of the team repo's canon. (${CLAUDE_PLUGIN_ROOT} is the env var Claude Code substitutes to this plugin's install dir.)

Workflow

1. Detect — never assume the stack

• Repo root (git rev-parse --show-toplevel) and default branch

(git symbolic-ref --short refs/remotes/origin/HEAD, else init.defaultBranch, else main).

• Test / lint / typecheck commands from the manifests actually present — package.json scripts,

Makefile, pyproject.toml, go.mod. Read the real commands; don't invent them. Keep this list — it becomes the permissions.allow entries in step 4, and a command you didn't find here must not appear there.

• Pre-commit signals for step 5: formatter and linter deps/configs, a test/typecheck script —

the detection table in references/precommit.md.

• What already exists: AGENTS.md, CLAUDE.md (a real file? a symlink? to what?), a legacy

CLAUDE.local.md, .claude/settings*, .gitignore, CONTEXT.md, docs/. This is rarely a greenfield tree, and step 3 must diff against reality. A repo already carrying a real CLAUDE.md with content is the case to slow down on — it becomes AGENTS.md plus a symlink, which is a rename the user has to approve at the gate, not a clobber.

2. Pick the hooks

Five are always offered because they're stack-agnostic: block-dangerous-commands, block-env-access, enforce-commit-hygiene, credential-leak-guard and large-file-guard. Add the JS/TS ones only where that stack is actually present: block-non-pnpm, lint-on-edit, typecheck-on-stop. On a stack with no lint or typecheck hook, offer the five alone and say the rest are stack-specific rather than silently writing nothing.

guard-plugin-canon is shape-specific, not stack-specific — offer it only where step 1 found a plugins/ directory whose entries are symlinks back into the tree. It refuses an edit aimed through one of those links and names the canon instead, so on a repo with no such layout it is a hook that can never fire.

3. HARD STOP — show what you're about to write

List every path, marked tracked or ignored, with a diff for anything that already exists. Add three things that aren't paths: the permissions.allow list derived in step 1, so what the agent may run without asking is approved rather than assumed; the optional pre-commit offer (step 5), so the one gate covers it; and, when the repo already has a real CLAUDE.md, the git mv CLAUDE.md AGENTS.md rename it needs, spelled out — that one moves a file the user wrote and must never be inferred from silence. Wait for explicit confirmation. Scaffolding mutates the repo and a wrong clobber is expensive — this gate is not optional even though the rest of the lane is light.

4. Write

• mkdir -p .ai/work .ai/backlog .ai/archive docs/decisions; seed .ai/work with .gitkeep (the

other three get READMEs). Remove a .gitkeep that a README now supersedes — an earlier version seeded docs/decisions/.gitkeep, so a repo scaffolded then and re-run now keeps a redundant one beside the README, and the next reader cannot tell which is the convention.

• .ai/README.md — copy ${CLAUDE_PLUGIN_ROOT}/templates/work-README.md verbatim. It states the

lifecycle a reader gets wrong: a CHANGE.md leaves work/ at merge — archived, never deleted.

• .ai/backlog/README.md, .ai/archive/README.md and docs/decisions/README.md — copy

${CLAUDE_PLUGIN_ROOT}/templates/backlog-README.md, ${CLAUDE_PLUGIN_ROOT}/templates/archive-README.md and ${CLAUDE_PLUGIN_ROOT}/templates/decisions-README.md verbatim. Existing entries in any of the three dirs are left alone — they carry real content from earlier changes. A legacy single-file .ai/BACKLOG.md, if present, is named at the gate: offer to split it into per-file entries, never clobber or silently keep it.

• CONTEXT.md — if absent, create it with a one-line purpose statement (this project's glossary;

terms only, no implementation detail) and nothing else. If it exists, leave it alone.

• ${CLAUDE_PLUGIN_ROOT}/templates/settings.json → .claude/settings.json; prune the hook

entries not selected, add the permissions.allow list (below), then confirm the file still parses as valid JSON.

• AGENTS.md — if absent, render ${CLAUDE_PLUGIN_ROOT}/templates/AGENTS.md, substituting

{{PROJECT_NAME}} {{DEFAULT_BRANCH}} {{STACK}} {{TEST_COMMAND}} {{LINT_COMMAND}} {{TYPECHECK_COMMAND}} {{COMMIT_PATTERN}} {{COMMIT_TRAILER}} {{HOOKS_INSTALLED}} {{AGENTS_CHECK_COMMAND}}. Every placeholder gets a value or the line goes — a {{…}} left in the file is read as content by the next session and evaled as a command by the hooks, which is why they carry an explicit guard against exactly these tokens.

• The commands come from step 1 verbatim; none where the manifests had none. Write none,

not a plausible guess and not _(none detected)_: the hooks read none as "skip", and a command that doesn't exist fails on every edit.

• {{COMMIT_PATTERN}} and {{COMMIT_TRAILER}} are policy, not detected commands, so ask rather

than probe: derive the pattern from the log the repo already has (git log --format=%s -30) and propose it, and write none for the trailer unless the user says every commit must carry one. Both defaults live in enforce-commit-hygiene.sh — Conventional Commits for the pattern, none for the trailer — so an honest none is always a safe answer here.

• {{LINT_COMMAND}} is the per-file form (pnpm exec eslint --fix, ruff check --fix), since

lint-on-edit appends one path to it — not the whole-project script, which would re-lint the tree on every edit. Where the project only has the whole-project form, say so at the gate and write none rather than wiring a slow hook.

• Prune the Task Router row for anything this run didn't create. The template ships a row

pointing at .claude/hooks/, and that directory only exists if step 2 selected a hook — so a scaffold that declined them all fails its own agents:check on its first run, because path sync requires every routed path to exist. Same rule for any row whose target you skipped. A row is a promise that the file is there.

• Idempotency is per-section: if AGENTS.md already exists, leave it alone and report which of the

template's sections it is missing. Never merge a rendered template into a file someone wrote.

• scripts/check-agents-docs.mjs — copy ${CLAUDE_PLUGIN_ROOT}/templates/check-agents-docs.mjs

verbatim. Zero dependencies, Node built-ins only, and it finds the repo root by walking up from its own location to the nearest AGENTS.md — so scripts/ is the conventional home, not a required one. It checks five things: the declared budget, that no {{…}} placeholder survived, Task Router coverage and path sync, that every pnpm named in AGENTS.md exists, and that CLAUDE.md is a symlink. It checks nothing under docs/decisions/ — those records are editorial, and a validator over them turns a durable layer into a build gate.

• {{AGENTS_CHECK_COMMAND}} is how AGENTS.md's own header names its enforcement. With a

package.json, add "agents:check": "node scripts/check-agents-docs.mjs" to scripts and render pnpm agents:check; where the repo has an aggregate gate script (check, verify), add it to that too. Without a package.json, render the bare node scripts/check-agents-docs.mjs — and say at the gate that the checker needs Node even where the project does not.

• CLAUDE.md — ln -s AGENTS.md CLAUDE.md. A symlink, never a copy: the harnesses load

CLAUDE.md, the file is AGENTS.md, and a materialized second copy is the fork this whole layout exists to prevent. If a real CLAUDE.md with content is already there, it was approved at the gate as a rename — git mv CLAUDE.md AGENTS.md, then link — and its content stays; reconcile it against the template's sections afterwards rather than overwriting.

• The selected ${CLAUDE_PLUGIN_ROOT}/templates/hooks/*.sh → .claude/hooks/, chmod +x each.
• .worktreeinclude — if absent, copy ${CLAUDE_PLUGIN_ROOT}/templates/worktreeinclude.txt

verbatim. If it exists, leave it alone. Every line ships commented out, so it copies nothing until the user names a file; that is deliberate, because an uncommented guess would copy a secret nobody asked for. Tracked, and it earns its keep twice: Claude Code reads it for claude -w worktrees, worktree.sh create reads it for the loop's own. Say at the gate that it starts empty and the user should add their .env line.

• Append ${CLAUDE_PLUGIN_ROOT}/templates/gitignore-block.txt to .gitignore between its markers.

Idempotent: if the markers are already there, replace the block in place, never duplicate it.

The permissions.allow list — derived, never invented. The template ships ask and deny only, so nothing is pre-approved and every check waits on a prompt unless a global setting happens to cover it. This is the difference between a lane that runs and one that idles, so build the list from what step 1 actually found:

• The project's own checks, exactly as detected. Match the wildcard style already used in the

template's ask list — a bare entry plus an argument form, e.g. Bash(pnpm test) and Bash(pnpm test *). Never allowlist a script that isn't in the manifest: an entry for a command that doesn't exist is worse than no entry, because it reads as verified.

• The read-only git surface this lane uses — git status, git diff, git log,

git rev-parse, git symbolic-ref, git branch --list, git worktree list, in the same two forms.

Write nothing that overlaps ask or deny. Don't reason about which list wins — just never add an entry that could match git commit, git push, anything in the template's ask list, or anything touching .env. Adding write or network commands here is not a speed optimisation; it removes the gate the rest of the lane is built around.

Seed .ai/backlog/ and .ai/archive/ with their READMEs and nothing else — no example entry, no TODO, nothing standing in for one. On the next read a placeholder is indistinguishable from real queued work, and a backlog you have to first decide isn't real is one you stop opening. The copied backlog-README.md states the entry shape; entries arrive later, from dw-land.

5. Optional — wire the pre-commit

Only when opted in at the gate. pnpm add -D husky lint-staged, pnpm exec husky init, then write .husky/pre-commit and .lintstagedrc.json from the shapes in references/precommit.md — globs matched to the formatter and linter step 1 actually detected, never to a tool that isn't installed. Typecheck and test lines are separate opt-ins: both run the whole project per commit. agents:check is not an opt-in — it goes in uncommented and unguarded, because it reads a handful of files rather than building the project, and the reference explains why a staged-paths guard on it leaks. On a repo that's partly wired, fill the gaps and show diffs — never overwrite blind; the re-run rules are in the reference. Worth having even solo: it catches the commits made outside a session, where no hook fires.

Where the repo has no package.json and so no husky, say what that leaves uncovered rather than inventing a gate: AGENTS.md can then drift past its budget until someone runs the checker by hand.

6. Reconcile tracking

The split is the whole point, so enforce it after writing: .ai/, docs/decisions/, CONTEXT.md, AGENTS.md, CLAUDE.md, .claude/settings.json and .claude/hooks/ (plus .husky/ when written) must not be ignored — remove any pre-existing rule that ignores them. CLAUDE.local.md and .claude/settings.local.json must be ignored: nothing writes the first any more, and the rule is what keeps a stray one from being committed.

git add the CLAUDE.md symlink and confirm git recorded it as one — git ls-files -s CLAUDE.md must show mode 120000. A repo with core.symlinks=false stores the link as a text file holding the target's name, which reads as a one-line CLAUDE.md and silently un-forks nothing; say so rather than leaving it.

7. Report

List what was written and which paths to git add. If the pre-commit was declined, say what that leaves uncovered: commits made outside a session run with no formatter and no guardrails. Name the _(…)_ placeholders left in AGENTS.md for the user to fill — the template ships the sections, only they know this pr

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dominikwozniak
• Source: dominikwozniak/dw-solo-skills
• License: MIT

Install and usage instructions live in the source repository linked above.