btdstudio

Plan it in folders. Build it in folders.

btdstudio is four small Go CLIs for spec-first, AI-assisted software work. The filesystem is the architecture, your approvals are the gates, and any AI harness can follow along. So can you, without one.

go install github.com/btdstudio/zumen/cmd/zumen@latest
go install github.com/btdstudio/tomo/cmd/tomo@latest

Requires Go. tomo add installs kumi and hanga when you first need them.

How it works

From a plan to a pull request.

Each tool works on its own. zumen and tomo connect through one thing, a markdown ticket, with no shared runtime and no service in the middle.

01

Plan behind gates

An initiative moves through intake, spec, architecture and breakdown, with research, explore and synthesis when you need them. You and your AI harness write the files, each phase waits for your approval, and the plan ends in tickets.

$ zumen init plan && cd plan
scaffolded planning ICM workspace in plan
$ zumen repo add webapp git@github.com:acme/webapp.git
added webapp — commit REPOS.json to share it
$ zumen change new "Customer accounts"
created change 1-customer-accounts (source #1)
explore skipped
synthesis skipped
$ zumen gate breakdown approved
zumen: breakdown requires intake to be approved (currently "draft") (pass --force to override)
$ zumen gate intake approved
1-customer-accounts: intake = approved
$ zumen gate research skipped --reason "new app"
1-customer-accounts: research = skipped
$ zumen gate spec approved
1-customer-accounts: spec = approved
$ zumen gate architecture approved
1-customer-accounts: architecture = approved
$ zumen tickets new story "Add password reset" --repo webapp
created S-0001 specs/1-customer-accounts/tickets/S-0001.md
# write the acceptance criteria, then set status: ready
$ zumen gate breakdown approved
1-customer-accounts: breakdown = approved
02

Hand off a ticket

Tickets are the only interface out of a zumen workspace. tomo takes a ready or published ticket as a snapshot and starts one change in one repo. The ticket is plain markdown, so any other harness can pick it up too.

$ tomo init ../build && cd ../build
scaffolded ICM workspace in ../build
$ tomo add kumi webapp --path ../webapp \
    --remote git@github.com:acme/webapp.git github.com/acme/webapp
added webapp from github.com/btdstudio/kumi/cmd/kumi at ../webapp — commit REPOS.json to share it
$ tomo change new --from \
    ../plan/specs/1-customer-accounts/tickets/S-0001.md
created change 1-add-password-reset (ticket S-0001)
03

Land it in the repo

Approvals don't carry over, because tomo approves something different: how this ticket lands in this repo. The change then runs through implement, test, review, security and ship, and ends in a pull request that links the ticket.

$ tomo gate intake approved
1-add-password-reset: intake = approved
$ tomo gate requirements approved
1-add-password-reset: requirements = approved
$ tomo gate design approved
1-add-password-reset: design = approved
$ tomo gate plan approved
1-add-password-reset: plan = approved
$ tomo gate implement in-progress
1-add-password-reset: implement = in-progress
$ tomo status
change:   1-add-password-reset
phase:    implement
status:   in-progress
gates:    intake=approved requirements=approved design=approved plan=approved implement=in-progress test= review= security= ship=
ticket:   S-0001 Add password reset
branch:   s-0001-add-password-reset

Real output from zumen v0.3.0 and tomo v0.8.0, with scaffold lines trimmed and paths shortened. The comment marks a manual step.

The tools

Four CLIs. Use one or all of them.

zumen

図面

blueprint

Plans initiatives that take weeks and often span many repos, and ends in tickets.

  • Research, spec, architecture and breakdown, each behind a gate
  • Approvals committed to git, so they survive a clone
  • Tickets as markdown, which an agent can sync to your PM tool
go install github.com/btdstudio/zumen/cmd/zumen@latest
Read the zumen docs on GitHub

tomo

友

companion

Takes one change in one repo from a ticket to a pull request, for any AI harness or none.

  • Nine phases, including test, review and security
  • Plans stay in the workspace, code in one target repo
  • Scaffolds that repo with tomo add
go install github.com/btdstudio/tomo/cmd/tomo@latest
Read the tomo docs on GitHub

kumi

組

assembly

Scaffolds Go + HTMX + Bootstrap 5 web apps with the unglamorous parts already in place.

  • Auth, password reset, dashboard and settings
  • Catppuccin and other themes
  • Hot reload and migrations with kumi dev and kumi db migrate
go install github.com/btdstudio/kumi/cmd/kumi@latest
Read the kumi docs on GitHub

hanga

版画

woodblock print

A fast static site generator compatible with Jekyll and Octopress. This site is built with it.

  • Liquid templates and Chroma code highlighting
  • Preview server with rebuild on save
  • Deploys to S3, GitHub Pages or (S)FTP
go install github.com/btdstudio/hanga/cmd/hanga@latest
Read the hanga docs on GitHub

The method

The folder is the architecture.

zumen and tomo implement Interpretable Context Methodology (ICM). Instead of keeping process in a framework, the workspace itself holds it: numbered stages, the persona for each stage, templates and a map at the root.

Your harness reads AGENTS.md and follows the structure. Nothing needs to run after scaffolding, and you can read everything it reads.

ICM is described by Jake Van Clief and David McDermott in "Interpretable Context Methodology: Folder Structure as Agentic Architecture".

# a zumen workspace
├── AGENTS.md
├── STATE.json
├── LOG.md
├── REPOS.json
├── 00_intake/
├── 01_research/
├── 02_explore/
├── 03_spec/
├── 04_architecture/
├── 05_breakdown/
├── 06_publish/
└── specs/

Start with a plan.

go install github.com/btdstudio/zumen/cmd/zumen@latest
zumen init my-plan