Bokken encodes the Empathize → Define → Ideate → Prototype → Test loop as an executable, event-sourced, governed process. It runs interactively with you in the loop, or fully autonomously against a governed synthetic persona panel — and records every step, including the paths not taken. Terminal-first, MCP-consumable, written in Python. No GUI.
Test with wood; commit steel when it counts. A bokken is the wooden practice sword: you rehearse with wood until failure is boring, and commit steel only when the risk is understood.
The package ships a complete fictional engagement: Lanzadera, a commuter-shuttle SaaS whose ±6-minute pickup promise is quietly breaking. One command replays the whole loop on it — offline, deterministic, no API key. Every citation resolves to the bundled evidence; every dissent, including a red feasibility veto, is on the record; the verdict is an honest iterate, not a happy ending. The specimen even walks a bundled mock of the product in a real browser — per-feature functional tests, screenshots, and one honest broken finding: the product's own on-time tick contradicts its fine print.
$ uvx bokken demo halt: completed - dossier generated; handoff specs generated; report exported (pptx + html) report (html): …/demo/report/report.html report (deck): …/demo/report/report.pptx you were charged $0.00 - 0 network calls, 0 real tokens; the journaled usage is an illustrative live-run profile: ~$8 list price across 48 calls
10 seconds · $0.00 · 0 network calls · deterministic
Then point it at something real: bokken init --from-repo . drafts the brief from your
own repository (templates remain: SaaS retention, consumer app, internal tool), bokken run states
its cost before spending and prints a receipt at every halt, and bokken pack turns the finished
run into one shareable archive.
The Design Thinking loop is a hand-written state machine: five stage engines, explicit exit criteria, human gates at stage boundaries, and legal loop-back edges when a test contradicts an insight. Every run advances to a halt — gate_pending, input_pending, stopped, or completed — so no call is unbounded.
Underneath sits the Journal: an append-only JSONL ledger with a SHA-256 hash chain. Every utterance, LLM call, facilitation move, idea, decision, and dissent is an event with provenance. Session state is never stored anywhere else — replaying the ledger is the state. Kill the process at any point, bokken run resumes. Tamper with a record, chain verification reports the first broken sequence number.
Facilitation itself is encoded as the Kata — nine named, budgeted moves, every execution (or suppression) journaled with its trigger. Method stops being a scarce craft and becomes a repeatable one.
evidence interview 04 · class: observed seq 0141
"I stopped using the app because re-ordering took four screens."
insight derived · stage: define seq 0158
Repeat purchase fails at navigation cost, not price. Rests on evidence 12, 14, 19; contradicted by none.
decision D-2 · dissent preserved seq 0177
Prototype one-tap re-order. Options weighed: loyalty pricing, subscriptions, navigation redesign. Criterion: riskiest assumption first.
Bokken is a small set of layers around one rule: the Journal is the only source of truth. Everything above it appends events; everything below it derives views.
a human at a terminal · agents & IDEs over MCP
State is a replay of the ledger; every layer appends events or derives views. That is what makes every run crash-safe and resumable by construction. The full picture: docs/architecture.md.
Both modes execute the same state machine, the same exit criteria, the same gates, the same event schema. They differ only in who supplies participation.
--mode founder
An interactive terminal session where you are the counterpart: Bokken interviews you, you pick the winning option, you score the assumptions. Questions surface as input_pending; answer and run again.
gates default: none
--mode dojo
Fully autonomous against a governed synthetic persona panel — cast from your evidence, required to abstain where the evidence runs out, with a protected skeptic and a contamination firewall between ideation and testing.
gates default: stage_boundaries — the run halts before every transition until a human approves
Gate policy is tunable per session: --gates none, --gates stage_boundaries, or only the boundaries you care about (--gates define,test). Sessions are the durable unit — addressable by name across create, run, pause, and resume. The process is disposable; the session is not.
A session starts from tangible material, typed at intake so provenance survives all the way to the Dossier.
The codebase to explore — what the product actually does today, not what the deck says it does.
KPIs, funnels, churn — the numbers that decide which assumption is actually the risky one.
What real people have already said. Grounds the synthetic panel and keeps it honest — personas may not invent evidence.
Without --brief, bokken new <name> runs an interactive intake instead.
$ bokken init brief written to bokken-brief.json # from a template: saas-retention · # consumer-app · internal-tool $ bokken new mars-lander --mode dojo --brief bokken-brief.json \ --repo ./app --metrics data/kpis.csv --discussion research/interviews.md created session 'mars-lander' at .bokken/sessions/mars-lander $ bokken run mars-lander cost framing: a full run typically lands at $20-35 list price; stops at 20,000,000 tokens halt: gate_pending (stage: intake) - gate g-4f2a91c0 guards intake -> empathize receipt: $0.00 across 0 model calls so far $ bokken gate mars-lander approve $ bokken run mars-lander ... halt: completed (stage: complete) finalization: dossier generated; handoff specs generated; report exported (pptx + html) $ bokken dossier mars-lander dossier (complete): dossier/dossier.md # outcomes · process narrative · honesty section dossier/dossier.json # the machine-readable evidence graph $ bokken handoff mars-lander handoff (schedule-publication): handoff/openspec/changes/build-mvp-mars-lander/ # OpenSpec specs for the # validated MVP, evidence-traced, # ready for a coding agent $ bokken export mars-lander report: report/report.pptx # the whole run as a deck: process, intermediate report/report.html # + final outputs, spec appendix — journal-derived $ bokken costs mars-lander total ~$24.8 (list prices) · cache hit rate 91% # per stage × prompt × class $ bokken validate mars-lander --channel twilio --to +34… guide: artifacts/validation/validation_guide.md # research debt → real interview journaled 9 exchange(s) # reported human evidence; register rescored $ bokken library mars-lander · ./app · verdict iterate # learnings compound into the next run $ bokken handoff mars-lander --emit claude-code adapter: handoff/adapters/claude-code/HANDOFF.md # your coding agent executes it $ bokken pack mars-lander --deliverables-only packed: mars-lander.bokken.zip (214 KB, deliverables only) # manifest + report + deck + dossier + specs
Get started in one command — uvx bokken demo shows a whole run for $0.00; bokken doctor checks your environment with a fix per gap; bokken init --from-repo . drafts the brief from your own repo. On Claude Desktop, install natively with the one-click .mcpb bundle. Extras: bokken[ui] for browser tests, bokken[interview] for Twilio interviews, bokken[openai] for the OpenAI provider. Found something? Open a run-feedback issue or join the discussions.
Everything is resumable: Ctrl-C at any point and bokken run continues from the Journal. Watch it live with bokken journal mars-lander --follow; loop back explicitly with bokken back mars-lander define --reason "test contradicted insight-3". Every read verb speaks --json for scripts.
No call is unbounded: bokken run always comes back with one of four halts, and each halt tells you the next move.
| halt | meaning | what you do |
|---|---|---|
| gate_pending | a stage boundary needs sign-off | bokken gate <name> approve — or reject --reason "..."; the run stays in the stage for rework |
| input_pending | Founder mode needs your answer | run bokken run interactively and answer the prompt |
| stopped | budget exhausted, novelty floor, or human stop | raise the budget on resume, or leave it — the stopping reason is a Journal event |
| completed | the loop finished | bokken dossier <name> — finalization has already produced the Dossier, the handoff, and the report |
The lifecycle verbs
Exit codes & finalization
run completes → Dossier → OpenSpec handoff specs, ready for a coding agent
The rules are enforced by code paths with journaled outcomes — none of them can be turned off.
Every synthetic contribution is marked simulated at the record level. Confidence classes — observed | reported | assumed | simulated — propagate to everything derived from them. Simulated research is never laundered into "user insights".
Decisions resting on simulated evidence carry requires real validation. Dojo dossiers always open with the simulated-run banner. Neither can be disabled.
The Dossier states what Bokken did not do: abstentions, research debt, evidence that ran out, the options considered and dropped.
Dojo runs cannot widen their own brief, contact real humans, or publish externally. Client-supplied input paths are confined at the MCP boundary. Budgets and stopping rules terminate runs; the stopping reason is a Journal event.
A validation interview asks for consent first, once, and journals the contact and its outcome before any question goes out. Silence, a timeout, and an ambiguous reply all refuse — only an affirmative starts the interview. Raw phone numbers never enter the ledger.
Test panels never contain personas that ideated. Scoring criteria are frozen before ideation begins. A skeptic seat is protected on every panel. All of it enforced in code, all of it journaled.
bokken serve exposes the harness over MCP (stdio): 14 tools and 4 resources
on the same core the CLI uses, returning the same JSON shapes from one shared contract.
No call is open-ended — run_session always returns at the next halt, so driving
a run is a plain loop an agent can program against.
create_session_toolrun_sessionstep_sessionstop_session
Create with a brief, typed inputs, gates, and budgets; advance to the next halt or by one stage.
resolve_gatesubmit_inputrequest_loopback
Gates, Founder-mode answers, and loop-backs on the legal edges only.
get_statuslist_sessions_toolquery_journal
State and filtered ledger reads, byte-identical to the CLI's --json.
generate_dossiergenerate_handoffexport_reportcost_report
The deliverables and cost report on demand; the handoff refuses killed concepts.
→ run_session {"name": "retention"} {"halt": "gate_pending", "detail": "gate g-4f2a guards intake -> empathize"} → resolve_gate {"name": "retention", "resolution": "approve"} → run_session {"name": "retention"} # ... one gate per boundary ... {"halt": "completed", "finalization": "dossier generated; handoff specs generated; report exported (pptx + html)"}
$ claude mcp add bokken -- bokken serve
Resources: bokken://sessions, per-session status, the full
Journal as JSONL, and the latest dossier.json.
State-changing calls are journaled with actor.kind: agent and the client's
handshake identity — stamped server-side, never read from tool arguments, so it
cannot be forged. bokken journal <name> --actor agent shows everything
agents did.
A bokken (木刀) is the wooden practice sword of Japanese swordsmanship: you rehearse the strike with wood until failure is boring, and commit steel only when the risk is understood. That is the whole philosophy — prototype before you build, simulate before you decide, and let humans commit.
The append-only, hash-chained process ledger — the single source of truth, and the moat.
The facilitation move library: named, budgeted, repeatable — every move journaled.
The autonomous mode: full-contact practice against a governed synthetic panel, no one in the room.
Runs against synthetic participants — practice bouts before anything real is at stake.