create-factory

Scaffold an autonomous, safe Claude Code agentic development factory into any repo.

The factory enforces one loop — Plan → Reflect → Implement → Test → Review → Handover — and runs with the human out of the loop by default, made safe by two machine gates: an opus reflector that reviews every plan before code is written, and deterministic hooks + a thin deny floor that make dangerous actions impossible and reversible ones cheap.

Usage

# scaffold into a new or existing repo (interactive)
npx create-factory ./my-app

# non-interactive with sensible defaults
npx create-factory ./my-app --yes

# refresh ONLY the invariant core in an existing factory repo (never touches your project layer)
npx create-factory update ./my-app

Flags: --yes (defaults, no prompts) · --force (overwrite an existing .claude/, preserving project files) · --no-customize (scaffold only).

What you get

Everything the factory owns lives in one harness-agnostic folder, .factory/. .claude/ is a thin Claude Code adapter holding only what the harness can only discover there.

.claude/agents/      planner reflector implementer tester reviewer debugger refactorer doc-writer infra orchestrator wiki-curator
.claude/skills/      conventions code-review test-authoring commit-and-pr dependency-hygiene db-migration handover project-customizer wiki
.claude/commands/    /feature /fix /refactor /backfill-tests /review /handover /wiki-ingest /wiki-query /wiki-lint
.claude/settings.json  autonomy permission profile + hook wiring
.factory/hooks/      secret-scan block-dangerous require-plan format typecheck test-gate
.factory/docs/       conventions.md (real defaults) · architecture.md (generic example) · stack-profiles/
.factory/decisions/  ADR log
.factory/plans/PLAN.md  memory + task tracking
.factory/tools/      MCP notification servers (slack/telegram) + generated elevate.sh
.factory/scripts/    check-update.sh — pull the latest core from npm · wiki-lint.sh — mechanical wiki checks
.factory/wiki/       LLM-maintained project wiki (index.md + log.md seeds; committed to git)
CLAUDE.md            root: @-includes .factory/docs; project + core blocks
scripts/             test/lint/typecheck/build/format — the single source of truth for "verify"

Project wiki

Every scaffolded repo carries a self-maintaining knowledge base at .factory/wiki/ — the synthesized, queryable layer above raw sources (code, ADRs, git history), kept current by the mandatory loop. Small cross-linked markdown pages (subsystems / entities / flows / decisions / footguns), routed by index.md, committed to git so it travels with the repo and shows up in PRs.

• /wiki-ingest [source|--backfill] — the wiki-curator agent (the wiki's sole writer) distills how-the-system-works knowledge into pages; handover ingests each session's diff, and --backfill builds the initial wiki (also run by /customize).
• /wiki-query <question> — cited answers from the wiki; planning reads index.md first.
• /wiki-lint — .factory/scripts/wiki-lint.sh for mechanical checks (broken [[refs]], orphans, index drift, staleness) plus an opus semantic review; fixes go back through the curator.

Ownership stays crisp: nested CLAUDE.md holds invariants, ADRs hold decisions, the wiki holds the evolving map, code comments hold line-local gotchas (table in .factory/docs/layout.md). The curator + skill + commands + script are core (existing repos get them via update and bootstrap with --backfill); the wiki content itself is project-owned and never clobbered.

Core vs project layer

• Core (invariant, versioned): agents, skills, commands, .factory/hooks/, the autonomy profile, and the CORE: block in CLAUDE.md. create-factory update rewrites only these.
• Project (yours): stack profiles, the PROJECT: block in CLAUDE.md, scripts/* contents, .factory/docs/architecture.md module map, nested CLAUDE.md, ADRs. Never overwritten by updates.

Sandbox (on by default)

• The shipped settings.json enables Claude Code's OS-level Bash sandbox (sandbox.enabled: true) with autoAllowBashIfSandboxed for full autonomy inside the boundary, a starter network allowlist (npm/pypi/go/crates/github), and denyRead for secrets. Bash and its children are confined to the repo + /tmp; the deny-floor hooks still apply regardless.
• failIfUnavailable is false so the factory still runs where the sandbox is unsupported (native Windows, WSL1, or no bubblewrap) — the hook deny-floor remains the guarantee there. Harden unattended runs by setting it true.
• Extend per stack/developer in .claude/settings.local.json (gitignored, merged over core, never clobbered by update) — add cache dirs to sandbox.filesystem.allowWrite or hosts to sandbox.network.allowedDomains. Don't edit the core settings.json block.

Notes / caveats

• auto permission mode can't be granted by the repo (ignored since Claude Code v2.1.142) — enable at launch.
• Plugin-distributed subagents drop permissionMode/hooks frontmatter, which is why this ships files into .claude/ rather than as a plugin.
• The optional orchestrator agent is for harnesses without a strong native loop (Pi, some Codex/Cursor modes); on Claude Code leave it disabled. Pi specifics are unverified.