Home

How host works

host is a single instruction file. Point an agent (or a patient human) at it and follow it, and a repository becomes an agentic project — and stays upgradable as the methodology moves. The repository's README.md is the literal, step-by-step procedure; this page explains the model behind it: what the pieces are and why they fit together.

Thought and action

An agentic project is the externalized thought about a piece of software — its plans, decisions, specifications, the people it serves, and the rules you work under. The software itself is the action, and it lives beneath the project as a bare store with worktrees. You write thought in the project and action in the worktree, and you keep the two separate.

The five rooms

Every kind of file has one room, one per question you ask about any piece of work:

Question	Room	What goes there
Who	cast/	personas — the people (human or agent) the software serves
What	plan/<milestone>/spec/	specifications: behaviour (.allium), timing (.tla)
When	plan/	the milestone index and one folder per milestone
Where	<software>/	the hosted software — a bare store with worktrees
Why	call/	decisions, in MADR format
How	CLAUDE.md + tools/	the operating manual and the verification tools

Two namespaces

• host-* — the methodology's reusable artifacts: host-lint, host-lifecycle, host-grammar, host (this process file), and host-template (the scaffold).
• agentic-* — concrete projects: agentic-host (the project that develops the host-* tooling) and adopters such as agentic-acme.

Process vs techniques — why it stays upgradable

The work is split so that one half is stable and the other half versions:

• host owns the process — the adopt / migrate / upgrade procedure. It is stable and rarely changes.
• host-template owns the techniques — the CLAUDE.md spine, the room scaffold, and the pinned tools — and the revision-keyed upgrade ledger (UPGRADING.md).

An agentic project records the template revision it adopted in a .host stamp at its root. Because the churning part (the ledger) lives with the techniques that generate it, the process file never has to change when the methodology advances — you always run the latest host against your recorded stamp.

Adoption — two independent axes

Pick the case first (how governance is established), then the mode (how much you change, and whether history moves):

• Case — (a) no CLAUDE.md → drop the manual in and record the repo's own conventions; (b) a foreign CLAUDE.md → merge it with the spine (human ruling on conflicts); (c) a .host stamp → upgrade by diffing template revisions.
• Mode — Preview (report only, always first), Shallow PR (default; live files only; history untouched), Staged (Shallow across several PRs), Deep rewrite (opt-in; archive-first, then rewrite history). History is immutable by default; Deep is chosen only when its coherence is worth more than the disruption, and never on history carrying provenance you do not control.

Upgrade

The .host stamp keys it. host-lifecycle upgrade <dir> prints every ledger entry newer than the stamp (by git ancestry); you apply each, re-apply the spine changes across the span, then re-stamp. A ledger entry can gate itself on a minimum tool version (e.g. requires = host-lifecycle v0.5.0).

Verification lanes

Each claim is routed to the lane that can prove it:

1. Hygiene — host-lint: catches naming tells (ordinal labels, bare numerals) leaking into commits, headers, and comments. Runs as a git hook.
2. Requirements — allium: property-based testing of the behaviour a spec states.
3. Timing and concurrency — Specula: TLA+ model checking.

The tools

Three are the methodology's own (public domain):

• host-grammar — the shared rules for valid names and numbers (a library).
• host-lint — the checker: reads text and flags naming tells.
• host-lifecycle — the generator: allocates numbers, scaffolds rooms, decisions, and personas, writes and reads the .host stamp, materialises the Where room, and drives upgrades — all without spending model tokens on mechanical work.

Because the generator and the checker share host-grammar, what host-lifecycle emits is exactly what host-lint accepts.

The host-* artifacts we maintain

The methodology's reusable artifacts:

• host — this process file (adopt / migrate / upgrade).
• host-template — the scaffold: the CLAUDE.md spine, the room layout, the pinned tools, and the UPGRADING.md ledger.
• host-lint — the naming-hygiene checker (runs as a git hook).
• host-lifecycle — the generator/migrator: scaffolds rooms, writes the .host stamp, drives upgrades.
• host-grammar — the shared name/number rules both tools depend on.

The reference agentic project

• agentic-host — the agentic-* project that develops the host-* family above. It is adopter zero: it dogfoods the methodology, treating the host-* tooling as the software it hosts.

What we use

External tools we reference, not ours — each pinned as a submodule:

• allium (JUXT) — requirements and property-based testing.
• Specula — TLA+ model checking for timing and concurrency.