# Architecture

How one owner, review, evidence, host adapters, and Git-local state fit together in Zimster 0.7.2.

## Workflow model

One capable root agent owns a coherent change from the initial request through implementation and final verification. Planning, TDD, debugging, delegation, and review are workflow steps. They become separate agent contexts only when isolation or independent judgment is useful.

The root owner integrates delegated work and decides whether it is accepted. Reviewers review; they don't become replacement implementers.

## Workflow profiles

The amount of planning, verification, and review changes with risk.

- **Micro:** one local, deterministic, low-risk slice. Focused owner verification can be enough.
- **Standard:** ordinary subsystem or multi-component work. Independent review is concentrated at the important seam or integration point.
- **High risk:** security, public compatibility, concurrency ownership, destructive migration, native boundaries, broad architecture, or another hard trigger. High-risk work can use an early review while there is still time to change course. Final integration review waits for the stable candidate.

## A run from request to completion

Most non-trivial runs follow the same basic shape. The owner stays with the change; review and delegation are added only where they help.

```text
Read -> Plan -> Build -> Prove -> Review -> Stable head -> Finish

Review finding:
  fix once -> same reviewer rechecks once

Load-bearing problem remains:
  circuit breaker -> one new strategy -> second cycle -> BLOCKED if it still fails
```

Micro work can skip independent review. High-risk work can add an early review while there is still time to change the approach.

A strategy restart does not erase review history. The same seam keeps its review, correction, recheck, and proof record. Renaming the attempt or candidate does not buy another cycle.

## Skill set

The 12 canonical skills cover workflow selection, design, planning, owner-driven development, TDD, parallel agents, debugging, risk-adaptive review, review handling, verification before completion, Git worktrees, and branch finishing.

The set is intentionally small enough that an agent can select what applies without loading a catalog of overlapping roles.

## Host adapters

The core skills stay portable. Each coding agent adds only the host-specific pieces it needs:

- **Codex:** a generated marketplace plugin with the skills, operational scripts, configuration, schemas, templates, and metadata.
- **Claude Code:** the canonical skills plus four agents and one SessionStart hook.
- **Grok:** the standards-based root Agent Plugin manifest and canonical skills; no extra Grok-specific layer is required.
- **OpenCode:** a small project adapter that registers the packaged skills and bootstrap.
- **Pi:** npm package metadata, the Zimster skills, and a TypeScript extension. If Pi cannot enforce Zimster's two-agent limit, the work stays with the owner.
- **Kimi Code:** a native plugin manifest with canonical skill paths and one session bootstrap.

Cursor remains an ancillary skills-only path and is not one of the six v0.7 release hosts.

## Run state

Longer work keeps compact state beneath `git rev-parse --git-path zimster`. It records where the run is, what has been decided, what has been checked, open findings, review history, limits, and the next action.

Detailed logs and transcripts stay separate. A context renewal carries forward only the information needed for the next slice, so logical ownership can continue without copying the entire session history.

Review history stays attached to the same seam through correction, recheck, and the one allowed strategy restart. Changing labels does not reset it.

## Review and completion

Zimster tracks several different questions separately:

- **Owner verification:** what the implementation owner checked.
- **Checkout integrity:** whether the tree changed while a reviewer was working.
- **Independent review:** whether a reviewer approved the candidate and the important interfaces for that risk level.
- **Evidence coverage:** whether current proof actually covers the named requirements and claims.
- **Completion:** whether the checks, review, evidence, and final Git state are enough to finish.

An unchanged checkout only says the reviewer did not alter the tree. It is not a review verdict. A passing command proves only what that command actually checked.

Missing proof stays missing. Zimster records unavailable services, hardware checks, human acceptance, and authorization blockers instead of calling them passes. If required review or evidence is missing, the run stops short of `CANDIDATE_COMPLETE`.

HTML version: https://www.zimster.dev/docs/architecture.html