darkmill

A lights-out factory for AI-coded software. Disciplined workflow: brainstorm → CEO interrogation → design doc → walking skeleton → autonomous TDD implementation.

Composes existing skills from Superpowers, Iterative Development, and gstack via Archon workflows. Skills are vendored project-local at pinned versions.

---

Quick start

You just created this project from the template (via "Use this template" on GitHub or gh repo create --template ...). Two commands and you're ready:

# 1. Vendor the skill packs at the versions pinned in .claude/skills.lock.yaml (~30s–2min)
./scripts/update-skills.sh

# 2. Start the design phase
claude

In Claude:

Use archon to run project-charter

---

What you get

Four Archon workflows for the full lifecycle:

Workflow	When	Output
project-charter	Greenfield — starting from zero	docs/CHARTER.md + walking-skeleton roadmap
feature-pitch	Adding a feature to a project that already has a charter	docs/features/{slug}/pitch.md
iterate	Autonomous implementation of any approved spec	code, tests, atomic commits, PR
fix-blocker	Resume a halted iterate run after a task got blocked	resolved task(s), back to pending

Three of project-charter's nodes are interactive (intake, CEO interview, final approval); the rest run autonomously. When you APPROVED at the final gate, you'll have:

• docs/CHARTER.md — the founding design doc
• docs/charter/roadmap.md — walking skeleton + iteration roadmap
• CLAUDE.md — project conventions wired to your stack
• .claude/HARNESS.md — hard rules for autonomous runs
• scripts/verify.sh — wired up with real lint + typecheck + test for your stack

Then ship:

Use archon to run iterate

If a task gets stuck:

Use archon to run fix-blocker

For features later:

Use archon to run feature-pitch
# then:
Use archon to run iterate

---

Prerequisites

• Claude Code
• Archon CLI — bun install -g archon or via the Archon setup wizard
• GitHub CLI — used by the phase-pr step
• python3 and git — used by update-skills.sh
• Optional: Codex CLI — enables the cross-model second-opinion step in iterate

---

How each workflow composes existing skills

The workflow YAMLs are mostly glue — the discipline is in the vendored skills.

project-charter

problem-and-idea           interactive — 2-question intake
brainstorm                 → superpowers:brainstorming
ceo-interview              → gstack:office-hours (premise-challenging interrogation)
community-research         web_search + web_fetch (custom)
proposal                   custom synthesis
ceo-review                 → gstack:plan-ceo-review (4 modes: expand/hold/reduce/selective)
cross-model-challenge      adversarial pass — uncomment `assistant: codex` to use a different model
refine-and-borrow          custom — proposal v2 + borrow table
write-charter              custom synthesis → docs/CHARTER.md
walking-skeleton           → iterative-development:scoping-the-simplest-core
project-conventions        custom — generates CLAUDE.md, settings.json, verify.sh for your stack
human-approval             interactive loop until APPROVED

feature-pitch

precondition-check         bash — CHARTER.md + CLAUDE.md must exist
feature-intake             interactive — 4-question intake (incl. Shape Up appetite)
pitch-interview            → gstack:office-hours, framed for "feature in existing system"
prior-art                  Grep + Read in codebase + web search
pitch-draft                custom — Shape Up structure
eng-review                 → gstack:plan-eng-review
design-review              → gstack:plan-design-review (skipped if no UI surface)
human-approval             interactive loop until APPROVED

iterate

precondition-check         bash — spec exists, tree clean, verify.sh ready, skills vendored
extract-requirements       → iterative-development:extracting-requirements
                             produces stories + behavior scenarios + coverage ledger
scope-walking-skeleton     → iterative-development:scoping-the-simplest-core (skipped if charter has roadmap)
iteration-loop             LOOP, fresh_context per iteration:
                             → iterative-development:running-an-iteration
                               → iterative-development:implementing-tasks per task
                                 → superpowers:test-driven-development (RED-GREEN-REFACTOR)
                                 → superpowers:verification-before-completion
audit-iteration            → iterative-development:auditing-progress (PAR three-tier)
codex-second-opinion       → gstack:codex (skipped if Codex CLI not installed)
finish                     → superpowers:finishing-a-development-branch

fix-blocker

detect-blockers            bash — finds all `status: blocked` entries in docs/
select-blocker             interactive — pick which to address
gather-context             fresh — task + spec + code + scenario + verify.sh log + recent commits
diagnose                   fresh → superpowers:systematic-debugging
                             classifies into SPEC | SCOPE | IMPLEMENTATION
propose-fix                interactive — APPROVE / REJECT / REVISE
apply-fix                  fresh — applies fix per classification
verify-no-regression       bash — ./scripts/verify.sh must still pass
resume-prompt              interactive — prompts user to re-run iterate

---

What's enforced

Rule	Where	Enforced by
One task = one commit	.claude/HARNESS.md + iterate.yaml	Agent prompt + verify.sh blocking partials
RED before GREEN	superpowers:test-driven-development	Skill, mandatory invocation
No drive-by edits	Task frontmatter files: [...] + HARNESS rule	iterative-development:auditing-progress at iteration boundary
Lint + typecheck + tests pass	scripts/verify.sh	Run after every task
No Co-Authored-By	.claude/settings.json attribution.commit: ""	Deterministic — Claude Code respects it
No model drift mid-run	Pinned model in .claude/settings.json	Deterministic
Behavior evidence per story	iterative-development:auditing-progress Tier 1	PAR — paired auditors
Sentinel regression catch	iterative-development:auditing-progress Tier 3	Re-run curated subset every iteration
Cross-model second opinion	gstack:codex in iterate.yaml	Optional but high-value if you have Codex
Skill version pinning	.claude/skills.lock.yaml + update-skills.sh --check	Drop --check in a pre-commit hook
Project-local skill resolution	.claude/skills/ overrides ~/.claude/skills/	Claude Code prefers project-local

---

Customizing per-stack

scripts/verify.sh aborts until you've configured it for your stack. The project-conventions node in project-charter should write a wired-up version, but always sanity-check what it generated.

After wiring, mark it ready:

chmod +x scripts/verify.sh
touch .verify-configured

Common customizations:

• Node + TypeScript: npm run lint && npm run typecheck && npm test -- --run
• Python (uv + ruff + mypy + pytest): uv run ruff check . && uv run mypy . && uv run pytest -x
• dbt: dbt build --select state:modified+ --warn-error

---

Updating skills

When you want to bump skill versions in your project:

# Either bump `ref:` for a skill, or clear its `sha:` to fetch latest of current ref
$EDITOR .claude/skills.lock.yaml

./scripts/update-skills.sh           # vendors fresh, pins new SHAs back into the lockfile
git diff .claude/skills.lock.yaml    # review what changed
git add .claude/skills.lock.yaml
git commit -m "chore(skills): bump <skill> versions"

To verify your local vendored skills match the lockfile (good as a pre-commit hook):

./scripts/update-skills.sh --check

---

Repo structure

.archon/workflows/
├── project-charter.yaml
├── feature-pitch.yaml
├── iterate.yaml
└── fix-blocker.yaml
.claude/
├── settings.json             # model pinned, allowed tools
├── HARNESS.md                # hard rules + skill routing table
├── skills.lock.yaml          # pinned skill SHAs (committed)
└── skills/                   # vendored skill packs (NOT committed; populate with update-skills.sh)
docs/                         # generated by workflows
scripts/
├── verify.sh                 # quality gate (you customize per-stack)
└── update-skills.sh          # vendoring tool
CLAUDE.md                     # regenerated by project-charter

State lives in YAML frontmatter on disk, not in a database. git log is the audit trail.

---

License

MIT for the skeleton glue. Vendored skills (under .claude/skills/ after running update-skills.sh) carry their own licenses, preserved in .PROVENANCE files:

• obra/superpowers — MIT
• prime-radiant-inc/iterative-development — Apache 2.0
• garrytan/gstack — MIT