arizuko › concepts › how it’s built

how it’s built

A change to arizuko is an agent’s work, kept as files: the same parts that route a Slack message — specs, skills, file-based memory, ephemeral turns — are the ones used to add a feature. This page is the build process, not the runtime — for the parts themselves see primitives, the ant, and skills.

Agents do the work

The work is done by arizuko-shaped agents: Claude Code sessions with durable file memory and bounded subagents. Non-trivial changes — a migration, a cross-package refactor — run in a git worktree-isolated subagent so parallel work doesn’t collide. Edits to the shared tree go one at a time, the same serialization a turn gives a single folder.

The build loop

Each step is a concrete artifact on disk:

• Design is a spec. It lands as a file under specs/ with a tracked status: (draft, partial, ready, shipped) — reviewable and diffable, not buried in a chat log.
• A second opinion is one command. codex exec asks an independent model to check a non-obvious design before it’s committed.
• The decision is written down. /diary records it to .diary/<date>.md at the moment it’s made.
• The next session remembers. /recall-memories reads the diary and a file-based memory store to recover context — the same durable state primitive an agent uses in production, files rather than a context window.

ship, then harden

The first cut is small and lands fast; the same agents then harden it with repeated passes:

• Two adversaries read the change. codex exec hunts the finished code for bugs the author missed, and assess attacks the change from a fixed adversarial role — a CEO, CTO, or CISO hunting for the worst weakness.
• One change ripples, so a sweep re-aligns it. sweep-fix-verify walks every call site and reference at once — renaming the spec phases re-pointed roughly sixty files in a single sweep, so nothing is left dangling.
• Refine cuts until there’s nothing to cut. /refine runs improve and simplify together to kill duplication and minimize the diff, and runs again until a pass finds nothing to change.
• A bug found mid-task waits its turn. It lands in bugs.md, a review queue, and is fixed when it’s prioritized — not opportunistically in the middle of unrelated work.

Built on the four layers

The primitives → components → daemons → products stack is the build path, not only the architecture. A concept starts as a spec (a primitive made explicit), becomes a Go package (a component), bundles into a daemon, and surfaces as an installable product. The tool-level secret broker began as a spec, became the secret-resolution code in store and ipc, ships inside routd, and shows up as folder- and user-scoped secrets a product can declare.

So a new requirement is a spec edit, a package, and a route — files on a host you control, changed with an edit and a commit, not a vendor ticket.