Guildhall

A gathering place for adventurers.

A TDD-ordered coding agent harness for Claude Code, with a portable skill for Claude and Codex. Mordain uses the model configured for the parent session.

The guild

Mordain the Keeper — the Guildmaster — is embodied in the /quest command itself. He is not a dispatchable adventurer. When you issue a quest, Mordain is the one planning, picking mode, dispatching adventurers, and verifying their handoffs. His Write access is scoped narrowly to the quest's plan file at docs/guildhall/plans/*.md — a forcing function that keeps him from doing the adventurers' code-writing work.

The eighteen adventurers:

These Model entries mirror native Claude frontmatter defaults. Explicit supported user model choices can override dispatch settings.

Plus one diagnostic: model-echo — requested on a model different from its frontmatter to collect an unverified hint. Its self-report cannot establish which model executed or which host setting took precedence. Trusted host metadata is required; otherwise observed identity stays unknown.

Full character sheets in CHARACTERS.md.

Installation

Version 0.19.0 adds collaborative planning review. Optional Jev-assisted routing and its setup skill, removed in 0.18.0, remain absent. The installation guide covers this repository's Codex, Claude and standalone routes, updates and removal. The separate marketplace below is not updated by this change.

From the marketplace (recommended)

Guildhall is distributed through the grillergeek-plugins marketplace. Run these once inside any Claude Code session:

/plugin marketplace add GrillerGeek/skills
/plugin install guildhall@grillergeek-plugins

From a local clone

# Replace <path-to-repo> with the directory where you cloned guildhall
claude --plugin-dir <path-to-repo>/plugin

Keeping up to date

Restart Claude Code to pick up the latest version. If using --plugin-dir, pull first:

cd <path-to-repo>
git pull

Flow at a glance

For a feature quest, Mordain runs: model-echo diagnostic → (optional Aldric) → Seraphine → Bruga → (optional Tink) → parallel fan-out (Oriana + Cassian always; Vance / Thalia / Cassia / Garran / Ysolde / Vera / Lior gated by trigger) → Rook — with a committed plan.md opening the quest and a PR draft closing it. The plan file's ## Reviewers selected section records which gated reviewers fired and why.

Prototype mode skips to Pip. Debug mode starts with Kael.

Issuing a quest

/quest <task description>

Examples:

/quest Build a Python CLI that polls Recreation.gov availability for a campground ID.
/quest Implement the reservation feature from spec docs/specs/2026-04-18-reservations.md
/quest The /api/reservations endpoint is returning 500s — figure out why.

The orchestrator picks the mode (prototype / feature / debug) and dispatches the right worker(s) in TDD order.

Quests on a schedule

/quest composes with Claude Code's loop primitives — no extra configuration needed:

# Babysit a PR: re-run every 30 minutes until you cancel
/loop 30m /quest Address new review comments on PR #12 and fix any failing CI.

# Recurring maintenance as a scheduled cloud routine
/schedule a nightly routine that runs: /quest Apply patch-level dependency bumps and verify the full suite stays green.

Two rules of thumb keep scheduled quests cheap and safe:

1. Give the task text a verifiable stop condition ("until CI is green", "only patch-level bumps") — Mordain's gates handle correctness within a run, but the loop needs to know when a run has nothing to do.
2. Match the interval to how often the underlying state actually changes. A PR that gets one human review a day does not need a five-minute loop.

Docs-fast-lane and debug quests loop cheaply. Full feature quests on a schedule are best reserved for well-defined recurring work (dependency upgrades, triage sweeps) — the spec-or-route-to-spec-author rule still applies on every iteration.

Design principles

1. Each adventurer has ONE job. No multi-purpose coder.
2. Prototype-mode ≠ feature-mode. Different ceremony, different bars.
3. Independence as a guardrail. test-author is independent of feature-implementer. debug-investigator does NOT fix.
4. Consume IDD artifacts directly. test-author and feature-implementer both read IDD Spec files (Expectations, Boundaries) as first-class inputs.
5. Literal-friendly for Opus-tier models. Prompts state the contract explicitly — inputs, outputs, in-scope, out-of-scope. No hand-waves. (The prompt style was tuned on Opus 4.8 and carries forward.)
6. Hard rules get hooks, not just prose. Mordain's plan-file-only Write rule is enforced by a deterministic plugin hook, not only by instructions (see below).

Hooks the plugin installs

Installing Guildhall registers two small hooks (plugin/hooks/), both stdlib-Python and both inert outside quests:

• quest_flag.py (UserPromptSubmit) — marks the session "quest in flight" when you submit /quest (or /guildhall:quest), and clears the mark on your next non-quest prompt.
• quest_write_guard.py (PreToolUse on Write) — while a quest is in flight, denies any main-agent Write outside docs/guildhall/plans/*.md, with a message steering Mordain to dispatch an adventurer instead. Adventurers (subagents) are never touched — their write access is governed by each agent's own tool list.

This is the deterministic backstop for the design rule that Mordain plans and dispatches but never writes code himself. Ordinary (non-quest) sessions are unaffected. Hooks load at session start, so the guard first takes effect in the next session after installing or updating the plugin.

Integration with IDD-framework

Guildhall is the implementation-side complement to the IDD-framework plugin. IDD handles specs (Intentions → Expectations → Spec → review); Guildhall handles code (plan → test → implement → refactor) from those specs. For how the two map onto the broader seven-stage AI coding workflow (Grill → Research → Prototype → PRD/Plan → Issues/Tasks → Implement → Review), see How Guildhall fits the AI coding workflow.

Cost posture

The orchestrator inherits the parent session model. The roster supplies native worker defaults; Fable remains forbidden for Claude adventurers. Assess model changes by completed-task quality, retries and measured usage, not token price alone. Plan records retain evidence, but requested settings and model self-reports do not establish execution identity or billing. Missing usage/cost stays unknown; subscription usage cannot be converted into an assumed API bill.

Supported explicit per-dispatch user selections take precedence over role model choices and native roster/frontmatter defaults. Portable workers use supported host/user settings without inventing equivalents for Claude aliases. Host settings may override or substitute a request; record trusted observed settings separately or unknown. Model-echo self-reports are diagnostic hints, not proof of execution identity or cost.

Portable quest skill

Version 0.19.0 ships skills/guildhall-quest/SKILL.md for capable non-Claude hosts. It bundles its role references and uses host-native independent workers. The Claude command/agent/hook route documented above is preserved; standalone installation does not register those native Claude components.

Collaborative planning review

Mordain discovers review tools available in Cassian's actual worker context. Prefer a native Claude artifact or editable Codex Space Page, then the optional OpenCode/Pi local companion, then portable Markdown/HTML plus conversation. An Artifact allowlist entry does not establish account access. Missing tools must be reported; no native feature or hook equivalence is inferred.

Cassian's explicit review-document mode receives bounded approved inputs, named outputs, creation permission and the selected surface/authority. It owns those review documents and hosted output; its post-green mode stays separate. Mordain still writes only the plan. The helper is scoped bookkeeping/transport, not an adventurer or a way around that rule. Portable role scopes remain instructions unless the host actually enforces them.

One stable, private-by-default workspace accompanies each plan. Review prose, standalone HTML and bounded decision records live beside it; runtime tokens, bindings, request journals and raw logs stay outside the repository. Reconcile on save/proceed, handoff, resume and closure. Preserve conflicts and partial saves; an uncertain hosted save never authorizes creating another Page.

Only the designated owner, otherwise the initiating user, supplies acceptance. AI replies and controls are proposals; checkpoint completion means synchronization. Changed IDD inputs return to their authoring/review workflow. Keep review HTML, solution proposals and Page chats out of Seraphine's Spec/API/test handoff.

Native supported file/host tools can save the portable record without Python. The optional POSIX Python helper, limits and recovery procedure are documented in installation and the canonical contract. Review-specific live acceptance for all four hosts remains pending; synthetic transports and packaging checks establish only their recorded scope.