An agent can write a good deal of software in one sitting. The trouble starts in the third or fourth sitting. The conversation that held the plan has been cleared or compacted, the decisions made on day two live in a scrollback nobody will read again, and the agent reports a task as finished because a file exists. Over a project of several weeks, the thing most likely to be lost is not the code. It is the plan, and the record of whether the plan was met.
Aloha is the workflow I use for that problem in Claude Code. I published it at github.com/hellojdmiller/aloha on September 20, 2026, as version 1.0.0. This piece describes what it does, why I built it, what it costs to run, and what I would still change.
What Aloha does
Aloha adds a set of /aloha:* slash commands to Claude Code, the workflow prompts behind them, and 15 sub-agent definitions. Together they move a project through a fixed lifecycle and keep the state of that lifecycle in a .planning/ directory inside the project, committed to git by default.
The lifecycle has five steps. You describe the project, and Aloha questions you until it can write a PROJECT.md with the vision and constraints, a REQUIREMENTS.md with numbered requirement IDs, and a ROADMAP.md that breaks the work into phases mapped to those requirements. Each phase is then planned into one or more PLAN.md files, executed by sub-agents, and verified. A STATE.md file carries the project's memory between sessions: where you are, what was decided, and what is blocked.
On a new project, the commands a reader would actually type look like this:
/aloha:new-project
/clear
/aloha:discuss-phase 1
/aloha:plan-phase 1
/clear
/aloha:execute-phase 1
/aloha:verify-work 1
On existing code, /aloha:map-codebase comes first and writes documents on the stack, architecture, conventions, and concerns into .planning/codebase/. At the start of any later session, /aloha:progress reads the files and says where you are and what comes next. For small work that does not deserve a phase, /aloha:quick runs a task with the same atomic commits and state tracking but skips the optional agents.
The agents have narrow jobs. A planner writes plans of two or three tasks each, sized to finish well inside one agent's context, and groups them into waves so that independent plans can run in parallel. A plan checker reviews the plans against the phase goal, in a revision loop of up to three passes. Executors carry out one plan each, commit every task as it finishes, and write a SUMMARY.md. A verifier then checks the phase. Researchers, a debugger, codebase mappers, and UI checkers fill in around them.
Two more pieces hold this together. Each command resolves which Claude model each agent should use from a profile (quality, balanced, budget, or inherit); the default, balanced, gives the planning agents Opus and execution and verification Sonnet. And a small Node CLI, aloha-tools.cjs, with no npm dependencies, does the bookkeeping the prompts should not improvise: loading state, finding phases, editing the roadmap, making commits, and checking that plans and summaries are well formed.
Installing it is a git clone and a short shell script:
git clone https://github.com/hellojdmiller/aloha.git
cd aloha
bash install.sh
install.sh copies the workflows, commands, and agents into ~/.claude and writes a manifest with a SHA-256 hash of every file it installed. Before it writes anything, it checks every destination. If a file exists and was changed after a previous install, or exists and was never installed by Aloha, it stops and lists the files, and it overwrites them only when told to with --force. Files that are byte-identical are skipped, so running it again is safe. uninstall.sh removes exactly the files in the manifest and never touches a project's .planning/ directory.
Synthesis
Why I built it
The short version is in my own words: "I came up with it while I was at a tech conference in Hawaii. It spawned from the idea that you could build out skills for certain build tasks and streamline your app buildout." Hawaii is where the name comes from. The open-source Get Shit Done workflow was the inspiration.
Building an application repeats the same kinds of work: scoping, planning a slice, building it, checking it. Each can be a skill with its own prompt and its own agent, rather than something improvised again in a long chat. The properties I wanted follow from that.
State lives in files and git. Every command reloads what it needs from .planning/, so /clear, a context reset, or a new session costs nothing. The plan does not depend on the agent remembering it.
Verification is against the goal, not the task list. The verifier's instructions say it plainly: it checks that a phase achieved its goal, not just completed its tasks, and it does not trust the summaries, because a summary records what the agent said it did. It works backward from the goal: what must be true, what must exist for that to hold, and what must be wired for those pieces to work.
One commit per task. Every finished task is its own commit, with the phase and plan in the message, so the history reads as a ledger of the plan, and one bad task can be undone without unpicking the rest.
Fresh context per command. The orchestrator passes file paths, not file contents, and each executor reads what it needs in a context of its own. The planner's instructions size each plan to finish within about half a context, because quality falls as a context fills.
Model routing per agent. The default profile reserves Opus for planning, where the architecture decisions are made, and uses Sonnet for the work that follows explicit instructions.
An installer that knows its own files. The Claude Code configuration directory holds other commands and agents too. An installer that records what it wrote can refuse to replace anything else without being told, and can remove itself cleanly.
The clearest example of why this matters is an internal service I built with Aloha this year: a server that lets our IT administrators work the firm's ticket queue through Claude. Its first milestone shipped across nine phases with 172 passing tests. When I let /aloha:autonomous push through the first seven phases, the run stopped short of archiving the milestone and wrote down why: the definition of done was a change in how people worked each morning, which code cannot certify. The milestone audit then found that the overnight automation, which its plan summary claimed as complete, had no way to tell system alerts from requests a person had written, and almost all of the unassigned queue was alerts. The next milestone opened with an alert filter. A task list would have called the first milestone finished. The goal check did not.
What it costs
The /clear discipline. The workflow expects you to clear the conversation between steps. The README calls this deliberate: a fresh context that reloads from .planning/ is cheaper and more reliable than a long one. It is still a habit to learn, and it only works if the files are kept current.
Tokens. Small plans, fresh contexts, a plan checker, a verifier, and optional researchers mean more agents and more reading than one long session would use. The quality profile puts Opus on planning and on execution. I have not measured the difference on my own projects, and I would not claim a number.
Ceremony. The full lifecycle is heavy for a small change. That is what /aloha:quick is for, and choosing between them is a judgment made each time.
The install footprint. Aloha installs 160 files, about 1.6 MB, into the Claude Code configuration directory. It needs Node.js 18 or newer for the CLI, git, and bash for the scripts.
Autonomy can skip the checks. In the service above, the autonomous run left no verification report for any of its first seven phases, and the audit flagged that as a process gap. The tests were passing, so the work was real, but the milestone closed with the test suite standing in for the reports. The autonomous workflow in the published version treats a missing verification report as a blocker. Faster is not the same as verified.
Proposal
When I would let an agent build for weeks
For an operator deciding whether to let an agent build something over weeks, I would set three conditions before the first prompt. Write down what done means in terms someone outside the project could check, including any change in how people work. Keep the plan in the repository, where a context reset cannot reach it. And require a check against that definition at the end of every phase, by something other than the agent that did the work. Aloha is one way to meet those conditions in Claude Code. The conditions matter more than the tool.
Proposal
What I would still change
Some of what I would change is visible in the repository today. /aloha:update looks for an npm package that is not published, so updates go through git pull and the installer instead; the command should say so or be replaced. /aloha:join-discord points to the GitHub issues page because there is no Discord. The 1.0.0 changelog entry lists more agents, more commands, and more runtimes than the README describes, and the two should agree. A few older names survive in places: the rollback command looks for checkpoint tags under a name nothing in the current workflows creates, and the planning reference shows branch templates that differ from the ones the code uses. None of these break the lifecycle, but a tool whose purpose is keeping the record straight should keep its own record straight.
Open question
What a project should keep after it ships
Aloha commits planning documents by default, and that is how a project survives a reset. It also means a repository accumulates research, plans, summaries, and audits that outlive their use. /aloha:cleanup archives old phase directories, but I have not settled how much of that record a small firm should keep, and for how long, once the work has shipped.