How It Works
The technical mechanics of H·AI·K·U — stage loops, hat transitions, DAG-based unit management, persistence adapters, and concrete examples of what happens under the hood.
Elaboration: The Human-AI Handshake
Before any autonomous work begins, human and AI collaborate to define what gets built, why, and how success is measured. This is the most important phase — it determines everything that follows.
What the Human Provides
Describes the problem and desired outcome in natural language. No templates required — just explain what you want to accomplish.
Studio selection, mode choice (continuous/discrete), and review gate approvals. The human controls the “what” and “when” — the AI proposes, the human decides.
Reviews the AI's proposed completion criteria and unit decomposition. Adjusts scope, adds constraints, removes unnecessary work.
What the AI Produces
Explores the codebase, reads documentation, identifies patterns and constraints. Produces a discovery doc that grounds all subsequent work.
Breaks the intent into units with dependencies (a DAG). Each unit has specific, verifiable completion criteria — not vague descriptions, but checkboxes the reviewer can verify.
Proposes the technical approach, identifies risks, and maps units to stages. The human reviews before any building starts.
The Handoff: When Does AI Take Over?
Continuous Mode
Elaboration: Human and AI collaborate interactively — AI proposes, human refines, until criteria are approved.
Execution: AI drives autonomously through the stage pipeline. Each stage runs its own hat sequence (defined in STAGE.md), advancing to the next stage when the review gate passes. Gates set to auto advance immediately.
Human re-enters at: Review gates set to ask (user approves) or external (team reviews). Between gates, the AI runs unsupervised.
Discrete Mode
Elaboration: Same interactive process — AI proposes criteria and decomposition, human validates.
Execution: Human invokes each stage manually with /haiku:run. Within a stage, the AI runs autonomously through that stage's hat sequence (e.g., planner→builder→reviewer for development, or threat-modeler→red-team→blue-team→security-reviewer for security), but it stops after the stage completes.
Human re-enters at: Every stage boundary. The human decides when to proceed, skip stages, or revise previous work. Maximum control over the pipeline.
In both modes, elaboration is always collaborative. The difference is who drives the stage transitions during execution.
The Stage Loop
Every stage — regardless of domain — follows the same four-phase internal loop. This is the fundamental unit of work in H·AI·K·U.
Plan
The planner hat reads the stage definition (STAGE.md), prior stage artifacts, and global knowledge. It decomposes the stage's work into units with verifiable completion criteria.
Units with frontmatter: status, dependencies, criteria
Build
The builder hat picks the next ready unit from the DAG, executes a bolt (one cycle through the hat sequence), and produces artifacts. Multiple bolts may run per unit until criteria are met.
Stage-specific deliverables (code, designs, copy, etc.)
Adversarial Review
A fresh reviewer agent (never the same as the builder) evaluates all work against the completion criteria. This is adversarial by design — the reviewer's job is to find problems.
Pass/fail verdict with specific issues if failed
Review Gate
The gate determines what happens next. Three modes: auto (advance immediately), ask (pause for user), external (block for team review). The studio's stage definition declares which mode.
Advance to next stage, revise within stage, or go back
Loop-back Mechanics
All criteria met. Stage artifacts saved. Move to the next stage in the pipeline.
Review found issues. Loop back within this stage — builder fixes, reviewer re-evaluates. Same stage, new bolt.
Fundamental issue discovered. Return to a previous stage. Rare but supported — e.g., design stage reveals inception was incomplete.
Hats Within Stages
Each stage defines its own hat sequence. Hats are focused roles that constrain what the agent can do. A fresh agent instance is spun up for each hat — no context bleed between roles.
Software Studio — Development Stage
persistence: git | review: ask
Each hat reads the same STAGE.md definition but has different constraints. The planner cannot write code. The builder cannot modify criteria. The reviewer cannot be the same agent that built.
Software Studio — Security Stage
persistence: git | review: external
Different stages have different hat sequences. Security uses red-team/blue-team adversarial patterns. The review gate is “external” — requires human sign-off before advancing.
Why Fresh Agents?
No context drift
Each hat starts with a clean context window loaded only with what it needs — stage definition, prior artifacts, knowledge pool.
Focused constraints
A hat definition specifies what the agent MUST do, MUST NOT do, and what quality gates it must pass before finishing.
Adversarial separation
The reviewer never shares context with the builder. It evaluates work from scratch, catching issues the builder is blind to.
DAG-Based Unit Management
Units are organized as a directed acyclic graph (DAG). Dependencies between units determine execution order. The DAG resolver picks the next “ready” unit — one whose dependencies are all complete.
Example: User Authentication Intent
| Unit | Name | Dependencies | Status |
|---|---|---|---|
| unit-01 | Data model schema | none | done |
| unit-02 | API endpoints | unit-01 | done |
| unit-03 | Auth middleware | unit-01 | active |
| unit-04 | Frontend components | unit-02, unit-03 | blocked |
| unit-05 | Integration tests | unit-02, unit-03, unit-04 | blocked |
The DAG resolver (dag.sh) evaluates unit frontmatter to determine execution order. Unit 03 (auth middleware) is currently active because its sole dependency (unit 01) is complete. Unit 04 is blocked — it needs both unit 02 and unit 03 to finish first.
Unit File Structure
--- status: ready # ready | active | done | blocked depends_on: # DAG edges - unit-01-data-model criteria: # Machine-verifiable - All API endpoints return correct status codes - Response schemas match OpenAPI spec - Rate limiting enforced on auth endpoints - Integration tests pass with >90% coverage --- # Unit 02: API Endpoints ## Description Implement REST API endpoints for user authentication... ## Approach 1. Define route handlers for /auth/* 2. Implement request validation 3. Add rate limiting middleware 4. Write integration tests
The frontmatter is machine-readable. The DAG resolver reads status and depends_on to determine order. The reviewer reads criteria to evaluate completion. The body is human context for the builder.
Persistence Adapters
The studio declares how work is saved. Stages and the core loop don't care — they call a persistence interface. The adapter handles the details.
| Operation | Git Software | Filesystem Ideation (default) | Notion Marketing |
|---|---|---|---|
| Create workspace | git worktree add | mkdir | Create page |
| save | git commit | Write files | Update blocks |
| version | Commit history | Timestamps | Page versions |
| review | Pull request | Export + review | Share + comments |
| deliver | Merge PR | Copy to output | Publish page |
This is what makes H·AI·K·U domain-agnostic. The core loop (plan, build, review) is universal. The persistence layer is the only thing that changes between domains. Git is just one adapter.
Knowledge Architecture
Every stage reads from two layers of accumulated context. This ensures no information is lost between stages or sessions.
Global Knowledge Pool
Project-level. Persists across all intents.
Intent Artifacts
Per-intent. Accumulated as stages complete.
Every stage reads both pools. The development stage has full context from inception, design, and product. No information loss.
Two Commands. That's It.
Everything in H·AI·K·U flows through two commands. Here's what happens under the hood.
/haiku:newCreate an intent and start workingTell the AI what you want to accomplish
humanAI suggests slug, studio, and mode (continuous/discrete)
aiHuman approves — intent container created (intent.md)
humanAI explores codebase, docs, and constraints
aiBreak intent into units with criteria and dependencies
collaborativePropose technical approach, identify risks
aiHuman validates scope, criteria, and approach
humanThe first stage varies by studio — inception for software, research for ideation — but it always does the deep elaboration work: discovery, decomposition, and criteria definition.
/haiku:new creates the intent container and immediately enters the first stage — no separate command needed./haiku:runContinue, resume, or run the next stageReads STAGE.md for hat sequence. Loads prior stage outputs + global knowledge. Resolves units from DAG.
Spawns fresh agents for each hat in the stage's sequence. Each hat works on units, advancing through the DAG. Failed reviews loop back.
All units done. Review gate fires: auto advances, ask pauses for user, external blocks for team.
Full Hierarchy
How the pieces nest together — from studio down to bolt.
Continuous vs Discrete
Two execution styles. Same pipeline, same quality, different levels of human involvement.
Continuous (default)
AI drives the pipeline. Human reviews at gates.
Discrete
Human drives the pipeline. Invokes each stage explicitly.
/haiku:run inceptioninception/haiku:run designdesign/haiku:run productproduct/haiku:run developmentdevelopment/haiku:run operationsoperations/haiku:run securitysecurityReview Modes Explained
Each stage declares a review mode that controls what happens at its boundary. These modes enable everything from fully autonomous pipelines to multi-person handoff workflows.
No human needed
The AI verifies all criteria are met and advances immediately. Used for stages where machines can fully validate quality — tests pass or they don't.
Same user confirms
The pipeline pauses and presents the output for the current user to review. An internal checkpoint — the person driving the work validates before moving on.
Different person or team reviews
The pipeline fully stops and waits for sign-off from someone outside the current session. Enables handoffs — a designer finishes, a tech lead reviews, an engineer picks up the next stage.
Discrete mode and handoffs: In discrete mode, every stage transition is effectively external — the user explicitly invokes each stage with /haiku:run. This naturally supports team workflows where different people own different stages. A designer runs inception and design, then hands off to an engineer who runs development.