A starting point for running a lights-on software factory with Claude Code. Based on the setup developed for Votito, where the orchestrator reduced token spend compared to bare-bones Claude workflow execution by around 80%.
The purpose of this repository is to act both as a simple boilerplate setup for new projects, and as an educational demonstration of the core concepts of software factories:
The workspace directory contains Claude code setup and a trivial example project.
.
├── README.md this file
├── GETTING-STARTED.md first setup and a first change
├── SETTINGS.md what settings.local.json wires up
├── LINTER-HOOK.md the lint hook and custom lint rules
├── REGULATOR.md the Bash-command regulator
├── ORCHESTRATOR.md how the orchestrator works inside
├── WORKFLOW.md the user flow, from an idea to a finished run
├── CONTAINER.md the container image and the root goals
├── LICENSE
├── makefile container goals: docker-image, init, claude, shell, test, lint, root
├── vm/Dockerfile the container image (Alpine, Node.js, make, git, ...)
├── .gitignore
├── .claude-home/ git-ignored; Claude Code login and history of the container
└── workspace/ the project; `make claude` starts Claude Code here
├── CLAUDE.md includes CONTRIBUTING.md for Claude Code
├── CONTRIBUTING.md workspace layout, commands and rules
├── .claude/
│ ├── settings.local.json hooks, env, permissions, preferences
│ ├── agents/ workflow-worker, workflow-gate, workflow-check
│ ├── commands/ impact-analysis, plan-execution, execute, regulator
│ └── workflow/
│ ├── README.md plan notation and generator reference
│ ├── package.json {"type": "module"} for the tooling
│ ├── bin/ hook entries and command-line tools
│ ├── src/
│ │ ├── regulator/ regulator engine, rules.js, rules/
│ │ ├── generator/ plan validator and workflow generator
│ │ ├── lint/ eslint plugin, two rules, lint hook logic
│ │ └── transient-dir.js
│ └── tests/ tests for all of the tooling
├── plans/ plans, sidecars and progress records
├── src/format-greeting.js sample module (replace it)
├── tests/format-greeting.test.js
├── eslint.config.js
├── makefile init, test, lint and the two workflow gate goals
├── package.json
├── package-lock.json
└── .gitignore