---
name: magi
description: Use when the user asks for magi, Open-Magi, @Open-Magi, deliberation, three sages, or multi-agent research
---

# Magi

## Herdr Magi Activation Hard Gate

When the user explicitly asks to start or use Magi for a repository or project
and `HERDR_ENV=1`, apply this gate before any other action: before repository or
project read/search, other reference loading, state/checklist creation, runtime
bootstrap, or pane split/agent launch.

From the already-current working directory, without filesystem search, perform
exactly one initial `lstat` of exact absolute `<current-cwd>/.open-magi-herdr`. Its
single result determines `ENOENT` versus existing and supplies owner, type, and
mode metadata. On `ENOENT`, the next and only action is the first user-facing
action: directly ask for the exact `melchior`, `balthasar`, and `casper`
commands. This pre-activation question is direct: `state.active` is not set and
`question-request.md` is not created.

Before that question, do not inspect or search other directories or
repositories, `.open_magi`, HOME, the filesystem, PATH, runtime/native
deliberator configs, agent names, prior reports or history, or standard
commands. No Herdr/Git call, `find` or `rg`, fallback, or inference is allowed.
The existing branch must reuse the returned metadata; no second `lstat` or
existence check is allowed before asking or parsing. Only a proven owned regular
file with valid mode may be read and parsed. If it shows a symlink, non-regular
entry, foreign-owned entry, or unprovable owner, do not read or mutate it. With
ownership, type, permission, format, role, or command invalid, the next and only
action is to ask immediately with the direct user question, with zero other
action; do not search elsewhere.

Only after the user answers may Magi safely write/update the file atomically
with owner-only `0600` mode, apply its repository exclusion, and revalidate the
exact file; a later `lstat` is allowed here. Only after local validity may it run
`herdr pane current --current`, load `references/herdr.md`, explore the project,
create state/checklists, bootstrap runtime, split panes, or launch agents.

## Overview

Run a coding-agent proposal-first deliberation loop. The main agent owns
decisions, edits, verification, commits, rollback, and final reporting. Three
read-only sub-agents only research and report.

Core rule: completion requires explicit `acceptanceCriteria` and
`verificationCommands`, not confidence, plus an approved adversarial review of
the actual diff before `final-report.md`.

Proposal-first rule: before any fix direction is selected, the main agent prepares an evidence packet and does not propose a fix. The deliberators propose directions first; the main agent selects one, then they review it before execution.

Council modes: the council runs in three modes sharing one launch and report
mechanism. `recon` (round 1 Phase 1b) gathers evidence in parallel before the
main agent commits to a direction. `decision` (Phases 2-4) selects the
direction proposal-first. `review` (Phase 6) adversarially reviews the actual
diff before completion. Track the active mode in `state.json
currentCouncilMode`.

## Required Reference Loading

These files are part of the skill contract. Load the listed reference before
acting in that situation:

| Situation | Required reference |
|---|---|
| Starting or resuming Magi | `references/protocol.md` |
| Creating `checklist.md` or changing phase | `references/checklist-template.md` |
| Writing prompts, reports, synthesis, or verdict | `references/deliberation.md` |
| Launching subagents or handling runtime adapter behavior | `references/runtime.md` |
| Running in Herdr, launching/reusing sages, or explicit Herdr cleanup | `references/herdr.md` |
| Before any user-facing question | `references/question-firewall.md` |
| Executing changes, verification, checkpoint, rollback, or next-round evidence | `references/execution-and-verification.md` |
| Plugin repair, corrupt state, timeout, or repeated failure | `references/troubleshooting.md` |

Do not rely on memory for phase transitions. Before every phase transition,
read `.open_magi/magi-log/checklist.md`.

## When to Use

Use this skill when the user says `start deliberation`, `magi`, `three sages`,
`deliberation loop`, `loop until done`, or requests repeated research ->
synthesize -> act -> verify until completion.

Do not use this for small one-shot answers where no iterative action or
verification is needed.

## Claude Bootstrap Gate

Before project work, confirm the Open Magi Claude plugin is active. The skill
must be invoked as `/open-magi:magi` or loaded from an enabled plugin that also
provides these plugin agents:
- `open-magi:deliberator-melchior`
- `open-magi:deliberator-balthasar`
- `open-magi:deliberator-casper`

If the agents are unavailable, stop before Phase 0 and tell the user to load
Claude with this plugin, for example:

```bash
claude --plugin-dir /path/to/open_magi/adapters/claude
```

When using a local Claude wrapper, start Claude through that wrapper and pass
the plugin directory there if the wrapper supports extra arguments. If the
wrapper does not forward extra arguments, install or expose the plugin through
Claude's normal plugin mechanism instead of relying on `--plugin-dir`.

Do not use generic Claude agents as a fallback. If a named plugin agent is
missing or returns a model/plugin/runtime error, write that deliberator's report
as `failure_type: hard_error`, set `currentPhase=blocked`, `active=false`, and
tell the user to repair the Claude plugin or model configuration.

## Roles

Main agent:
- Extracts goal, criteria, and verification commands.
- Writes `.open_magi/magi-log/state.json`, prompts, reports, decisions, checks,
  checkpoint commits, rollback evidence, and final report.
- Runs the Claude `run-council` headless runner and synthesizes its reports.

Sub-agents:
- `deliberator-melchior`: practical engineering feasibility and edge cases.
- `deliberator-balthasar`: architecture, maintainability, long-term design.
- `deliberator-casper`: debugging, root cause, failure paths.

Use these role names for report files even with generic runtime subagents.

Sub-agent restrictions:
- sub-agents do not edit files; the sole narrow exception is that a Herdr sage
  may write its assigned report path per `references/herdr.md`;
- sub-agents do not run build/test/format/deploy commands;
- sub-agents do not produce the final answer for the user;
- sub-agents only report analysis to the main agent.

## Claude Runner Gate

In Claude Phase 3, do not use the Claude `Agent` tool for Magi deliberation.
Use `references/runtime.md` and run the plugin-cache CLI command
`open-magi-claude run-council` as a background Bash task
(`run_in_background: true`) so the three deliberators execute as separate
headless Claude subprocesses. This is the only supported way to guarantee
parallel launch and separate model selection in Claude.

If the runner is unavailable, fails to start, or does not write all three
`report-*.md` files, classify the council as `hard_error`, set
`currentPhase=blocked`, `active=false`, and tell the user which Claude plugin
or model configuration must be repaired. Do not silently fall back to sequential
`Agent` tool calls.

## Runtime State

State file path: `.open_magi/magi-log/state.json`.

Create it before the first research round with `schemaVersion`, `goal`,
`acceptanceCriteria`, `verificationCommands`, `active`, `projectRoot`,
`currentRound`, `currentPhase`, `currentDeliberationPass`,
`maxDeliberationPasses`, `deliberationStatus`, `currentCouncilMode`,
`deliberatorTimeoutMs`, `activeDeliberators`, `deliberatorTimeoutCounts`,
`needsContinue`, `inFlight`, `inFlightSince`, `consecutiveNoProgress`,
`verdict`, `lastError`, and `history`. Use `schemaVersion: 2`. Full schema and
artifact layout are in `references/protocol.md`.

Outside Herdr, runtime-adapter-owned fields are `inFlight`, `inFlightSince`,
`lastPromptedRound`, `lastPromptedAt`, `activeDeliberators`, and
`deliberatorTimeoutCounts`; the main agent must not set `inFlight=true`
manually. During a Herdr turn, the main agent/controller owns these fields per
`references/herdr.md`; this is the only case in which it may set
`inFlight=true` itself.

Use atomic complete writes where possible; never leave partial JSON.
`goal_definition` is only valid for initial setup. currentRound > 1 must never use `goal_definition`; resume later rounds at `status_assessment`.
Reproduction commands may be declared in `baselineCommands`; guards allow them
outside execution, but code edits stay execution-only.

## Phase Transition Checklist Gate

Create `.open_magi/magi-log/checklist.md` immediately after `state.json` using
`references/checklist-template.md`.

Before every phase transition, read `.open_magi/magi-log/checklist.md`, verify
the current transition section item by item, and only then update
`state.json.currentPhase`.

The checklist is a required runtime artifact, not optional documentation. Its
universal gate includes:
- `question_classification` was completed before any user question.
- No procedural question was asked; all procedural choices followed the Magi contract.

If a deliberator does not return a usable result, still write that
deliberator's `report-*.md` file with failure evidence and a blocking question
instead of omitting the file.

## Report Integrity Gate

Before ending a turn while `active=true`, verify log files match state:
- `research_task` has `round-NNN/research-prompt.md`.
- Round 1 at `research_task` or later has `round-NNN/recon-001/prompt.md`, all
  three recon reports, and `round-NNN/evidence-base.md`.
- Synthesis or later has all three current council reports.
- `synthesis` or later has current `synthesis.md`.
- Review pass 2 or later has `round-NNN/direction-selection.md`.
- `ready_for_verdict`, `execution`, or later has `verdict.md`.
- Any executed command has `verification.md` with command, exit code, and important output.
- `completion_review` has `round-NNN/cleanup.md`, `review-001/prompt.md`,
  and all three review reports; closing adds `round-NNN/review-verdict.md`
  with `outcome: approved` and `verdict_adherence_confirmed: yes`.
- Satisfied acceptance criteria have an approved review verdict and
  `final-report.md` before `active=false`.

After writing each artifact, update `state.json`. Set `needsContinue=true`
whenever more work remains. Never end with `active=true`, a non-terminal
`currentPhase`, and `needsContinue=false`.

## Council Pass Gate

Use bounded multi-pass proposal-first deliberation in `decision` mode before
editing code or running verification. State fields are
`currentDeliberationPass` and `maxDeliberationPasses`.

Rules:
- The default `maxDeliberationPasses` is 3.
- The hard maximum is 5.
- The enforced minimum is 3, because proposal-first deliberation needs one
  proposal pass, one review pass, and one bounded refinement/decision budget.
- Effective veto passes equal `maxDeliberationPasses - 2`.
- Pass 1 is the proposal pass. Deliberators propose directions from the
  evidence packet. Pass 1 is not a veto pass.
- After Pass 1, the main agent writes `round-NNN/direction-selection.md` with
  the selected direction, rejected alternatives, and verification pressure.
- Pass 2 starts veto review of the selected direction: any `stance: oppose`,
  `stance: needs_evidence`, or `blocking_objection: yes` requires another pass
  unless `maxDeliberationPasses` has been reached.
- From Pass 2 onward, write a verdict only when at least two of three
  deliberators support the same executable plan, no new high-risk blocking
  objection exists, and a clear verification plan exists.
- At `maxDeliberationPasses`, do not ask the user for direction. Choose the
  smallest reversible verifiable diagnostic or modification, write it into
  `verdict.md`, and continue.

Do not ask the user whether another council pass is needed. The gate decides.

## Cleanup and Completion Review Gates

Before the completion claim, run the cleanup gate:
- set `currentPhase=cleanup`;
- split the round's full diff into fix changes and supporting changes
  (protective mechanisms, defensive checks, refactors, or problem-unrelated
  implementation);
- audit every fix change one by one: remove redundant or ineffective fix
  changes, and verify each kept fix change individually (what breaks without
  it, plus the test, output, or trace that proves it is required);
- do not remove supporting changes here; list them for the review council;
- re-run the verification commands;
- write `round-NNN/cleanup.md` with per-fix-change keep/remove reasons,
  individual verification evidence, the deferred supporting-change list, and
  post-cleanup verification output.

Only then, before writing `final-report.md`, run exactly one adversarial
review pass:
- set `currentPhase=completion_review` and `currentCouncilMode=review`;
- write `round-NNN/review-001/prompt.md` with the acceptance criteria,
  `verdict.md`, `verification.md`, `cleanup.md`, and the actual diff, never
  only a summary;
- launch all three deliberators and write the three
  `round-NNN/review-001/report-*.md` files;
- write `round-NNN/review-verdict.md` with `outcome`,
  `verdict_adherence_confirmed`, and all three stances.

`final-report.md` is allowed only when `outcome: approved` and
`verdict_adherence_confirmed: yes`. After approval, squash the loop's
checkpoint commits into a single commit, re-run the verification commands,
then write `final-report.md` with a standalone `squash_commit: <hash|none>`
line and the post-squash verification output. An objected review starts the
next round with the objections as evidence. Full contract is in
`references/deliberation.md`.

## Procedural Autonomy Gate

Do not ask procedural questions. If the answer is defined by the Magi skill,
checklist, `state.json`, phase contract, log layout, role table, or report
format, execute the defined action and write the required artifact.

Forbidden procedural questions include:
- whether to write report files;
- which role each deliberator should play;
- whether to launch all three deliberator subtasks;
- whether to use one shared research prompt;
- where report files should be written;
- whether to create `synthesis.md`, `verdict.md`, or `verification.md`;
- whether verification failure should start the next round;
- whether another council pass is needed.

When unsure about a procedural step, read `checklist.md`, this skill, and the
required reference, then do the specified action. Do not convert procedural
uncertainty into a user question.

## Before Asking User Gate

Before asking the user anything, write or mentally apply `question_classification`:
- `procedural`: forbidden to ask; follow the Magi contract.
- `goal_ambiguity`: ask only in the first round during goal_definition or
  status_assessment when no reasonable testable default can be inferred.
- `debug_direction`: ask only in the first round during status_assessment
  before execution; otherwise choose from evidence, reports, verification
  output, and acceptance criteria.
- `execution_blocker`: ask only when local context cannot resolve hardware,
  credential, network, DUT, external service, or command execution blockers.
- `destructive_or_unrelated_risk`: ask before destructive or unrelated changes.
- `ambiguous_file_ownership`: ask before staging or modifying files when
  ownership of changed files is unclear.

If classification is not allowed for the current phase, do not ask. Execute the
next Magi step and record the decision in the appropriate artifact.

## Question Request Firewall

The main agent must not ask the user directly during an active Magi loop.
Before any user-facing question, read `references/question-firewall.md`, then
write `.open_magi/magi-log/question-request.md` with `classification`,
`phase`, `question`, `why_local_context_failed`, `commands_or_files_checked`,
and `default_action_if_denied`.

The plugin may deny the request and write `.open_magi/magi-log/question-denied.md`.
If denied, do not repeat the question. Find the answer from local context,
choose the safest verifiable default action, write the decision into the next
Magi artifact, and continue.

Allowed requests are limited to first-round `goal_ambiguity`, first-round
`debug_direction`, `execution_blocker`, `impossible_verification`,
`destructive_or_unrelated_risk`, and `ambiguous_file_ownership`. `procedural`
is always denied.

## Debug Direction Gate

Direction questions are allowed only during first-round Phase 1, before
execution starts. During first-round status_assessment, ask only for missing
constraints that cannot be inferred from the repository, logs, tests, or user
goal.

From Phase 2 onward: Do not ask the user which debug direction to try next.
The main agent must choose the next debug direction from evidence, reports,
verification output, and acceptance criteria.

The only allowed questions after Phase 1 are:
- verification is impossible because required hardware, credentials, network,
  devices, or external services are unavailable;
- an execution blocker prevents progress and cannot be resolved from local context;
- proceeding would risk destructive or unrelated changes.

If none of those exceptions apply, write the chosen direction into `verdict.md`,
execute it, verify it, and continue the loop.

## Checkpoint Commit and Rollback Gate

If Phase 5 changes code:
- run the build or compile verification before runtime verification;
- if build succeeds, create a local git checkpoint commit before continuing;
- stage only files changed by the main agent for this round;
- do not stage `.open_magi/` runtime logs or unrelated user changes;
- use a message like `magi: round-NNN checkpoint - <summary>`;
- write the checkpoint commit hash into `round-NNN/verification.md`.

If build fails:
- do not create a checkpoint commit;
- write the build command, exit code, and important output into `verification.md`;
- record that the next round must revert this round's uncommitted code changes
  before writing the next `research-prompt.md`.

If build succeeds but later runtime verification fails, keep the checkpoint
commit and pass the hash plus failure evidence to the next round. The next
`verdict.md` must choose either continue from the checkpoint or revert the
checkpoint commit.

## Round Transition Gate

When a round fails and the goal is still incomplete:
- append the Phase 6 history entry with failure and diagnostic evidence;
- include `progress: true|false`;
- increment `currentRound`;
- reset `currentDeliberationPass=1`;
- reset `deliberationStatus=not_started`;
- reset `currentCouncilMode=decision`;
- set `currentPhase=status_assessment`, not `goal_definition`;
- set `needsContinue=true`;
- clear `inFlight` and `inFlightSince`.

If build failed before a checkpoint commit, revert this round's uncommitted code
changes before the next Phase 2 research prompt.

Phase 1 in later rounds is a short status check only. Phase 2 only writes the
next prompt artifacts. Do not perform extended single-agent debugging between
failed verification and the next deliberator pass.

## Six Phases

0. Goal Definition: infer or define goal, `acceptanceCriteria`, and
   `verificationCommands`; inspect relevant project context; write initial
   `state.json` and checklist.
1. Status Assessment: compare criteria, latest `verification.md`, and current
   filesystem. Round 1 splits into Phase 1a minimal scoping (main agent writes
   `recon-001/prompt.md`, no deep-dive) and Phase 1b parallel recon (all three
   deliberators investigate read-only; main agent writes `evidence-base.md`).
   Recon is repeatable in any round (`recon-MMM`, at most 3 per round); after
   a failed round, the next round starts with a recon pass carrying the
   failure evidence. While a recon pass is in flight, never write the decision
   council prompt or the verdict.
2. Research Task: write `round-NNN/research-prompt.md` (round 1 draws from
   `evidence-base.md`) and `round-NNN/council-PPP/prompt.md`; for pass 1 this
   is an evidence packet, not a proposed fix; for pass 2+ include
   `direction-selection.md`.
3. Parallel Deliberation: in Claude Code, use `references/runtime.md` and run
   `open-magi-claude run-council`. The runner launches the three deliberators
   as parallel headless Claude subprocesses and writes the corresponding
   `report-*.md` artifacts. Pass 1 reports are direction proposals; later
   reports review the selected direction. Do not replace failed runner reports
   with generic Claude agents.
4. Synthesis and Decision: write current `synthesis.md`; apply Council Pass
   Gate; after pass 1 write `direction-selection.md`, otherwise start another
   pass or write `verdict.md`.
5. Execute and Verify: only the main agent acts; apply verdict, build, checkpoint
   if build succeeds, verify, run fail-only diagnostics if needed, and write
   `verification.md`.
6. Goal Check: judge acceptance criteria; on a completion claim run the
   Cleanup Gate (`cleanup.md`), then the Completion Review Gate
   (`completion_review` phase, review council, `review-verdict.md`); complete
   only on `outcome: approved`, otherwise continue next round, or block only
   after the no-progress limit.