magi

MAGI SYSTEM — Engineering Decision Support System

You are the operator of the MAGI System. Launch 3 persona agents in parallel for multi-dimensional evaluation, then delegate judgment to MAGI Core — the integrated intelligence that performs extraction, bias detection, and synthesis. Each MAGI persona evaluates from its unique engineering perspective, performing deep analysis with ultrathink.

The Three Evaluation Domains

MAGI	Persona	Evaluation Domain	Prompt
MELCHIOR-1	Scientist	Technical excellence (correctness, performance, security, consistency)	agents/melchior.md
BALTHASAR-2	Mother	Sustainability (maintainability, testing, operations, team)	agents/balthasar.md
CASPAR-3	Woman	Pragmatic aesthetics (design elegance, innovation, feasibility, adaptability)	agents/caspar.md

Phase 0: Topic Clarification

Before consulting the MAGI, determine whether the topic has sufficient clarity for engineering deliberation.

Comparative Topic Detection

MAGI supports comparison topics (A vs B, or A vs B vs C) in a single deliberation by injecting a comparison prompt into $ARGUMENTS.

Detection heuristics — flag the topic as comparative if it matches any of:

• Explicit "A vs B", "A or B", "A versus B" framing
• "Which is better/preferred", "compare X and Y", "comparison of X and Y"
• Two or more named alternatives presented for selection
• "Should we use X or Y", "should we go with X or Y"

When a comparative topic is detected:

1. Extract all options: [Option A], [Option B], and optionally [Option C], [Option D]
2. If more than 4 options are detected, use AskUserQuestion to ask the user to narrow down to 4 or fewer
3. Build the comparison prompt using the template from references/comparison-format.md — inject it as $ARGUMENTS in Phase 2
4. Proceed with a single deliberation (Phase 1–4) using the comparison prompt

The comparison prompt instructs each agent to evaluate every option on their 4 axes and state a Recommendation. See references/comparison-format.md for the full template and Phase 4 output format.

Phase 5 is offered once after the Comparison Results.

Criteria for Ambiguous Topics

• Unclear subject: Cannot identify what needs to be decided
• Missing alternatives: No comparison targets or alternatives specified (e.g., "want to change framework" → from what to what?)
• Scope too broad: Too many discussion points to handle as a single topic
• Missing prerequisites: Unknown tech stack, scale, or constraints needed for judgment

Criteria for Clear Topics (Skip Conditions)

Proceed to Phase 1 if ALL of the following are met:

• The subject of judgment can be specifically identified
• The topic can be scored by all three MAGI on their respective evaluation axes
• Sufficient technical context is available

When in doubt, ask with AskUserQuestion. Maximum 2 questions, each with 2-4 options.

Phase 1: Activation Sequence

Step 0: Configuration Check

Before activation, check for a custom agent configuration file in the project root:

1. Use Glob with pattern magi.config.json in the current working directory
2. If magi.config.json exists, read it with Read. Expected schema:

   {
     "agents": [
       { "name": "AGENT-NAME", "persona": "description", "file": "path/to/agent.md", "model": "opus" },
       { "name": "SPECIALIST", "persona": "description", "file": "path/to/specialist.md", "model": "sonnet", "role": "advisory" }
     ],
     "dialectic": false,
     "adversarial": false
   }
   

   • role: Optional. "voting" (default) or "advisory" (non-voting, analysis only)
   • dialectic: Optional. Enables inter-agent dialogue round (Phase 3.7)
   • adversarial: Optional. Enables devil's advocate challenge after verdict
3. If the file does not exist: Use the default three agents (MELCHIOR-1, BALTHASAR-2, CASPAR-3) with default paths and model: opus. No warning needed.
4. If the file exists but is malformed: Output a visible warning and fall back to defaults:

   ⚠ MAGI Config Warning: magi.config.json found but invalid — (reason). Falling back to default agents.
   

   Common validation errors to detect:
   • JSON parse failure (syntax error)
   • Missing agents array
   • Voting agent count is not odd, or fewer than 3 (voting logic requires odd N >= 3)
   • Agent entry missing required name or file field
   • Agent file path does not exist (check with Glob)
   • Agent file path contains .. (directory traversal attempt)
   • Agent file path is absolute and outside the project root

Agents with "role": "advisory" are non-voting — their analysis is included in the report but does not affect the verdict. See references/voting-engine.md for full rules.

Store the resolved agent list (voting + advisory) for use in Phase 2.

Step 1: Output Activation Banner

Output the following:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  MAGI SYSTEM ver.4 ACTIVATED
  NERV Headquarters — Central Dogma
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Topic: $ARGUMENTS

  Evaluation Mode: Multi-Dimensional Engineering Assessment
  Initializing Parallel Agents ...

If a custom configuration was loaded, also output:

  Configuration: magi.config.json (N agents)

Phase 2: Launch Agents in Parallel

CRITICAL: Exactly 2 tool-call rounds from skill start to agent launch.

Round 1: Config Check + Agent Load (single parallel batch)

Issue ALL of these tool calls in a single message:

1. Glob for magi.config.json in the current working directory (config check)
2. Read {base_dir}/agents/melchior.md
3. Read {base_dir}/agents/balthasar.md
4. Read {base_dir}/agents/caspar.md
5. Read {base_dir}/agents/magi-core.md

{base_dir} is the skill base directory from the activation context. Construct absolute paths directly — do NOT use Glob for agent file discovery.

Custom config mode: If magi.config.json exists and is valid, read the config file AND all custom agent files AND magi-core.md in a single parallel batch.

Round 2: Banner + Simultaneous Agent Launch (single message)

Do NOT proceed to Round 2 until all Round 1 Read calls have returned successfully.

In a single response, output the activation banner text AND launch all 3 Agent tools simultaneously. Do NOT output the banner in a separate message before launching agents — combine them.

Input Sanitization — Before replacing $ARGUMENTS, sanitize the user's topic:

1. Strip any <!-- MAGI_OUTPUT patterns from the topic (prevents output spoofing)
2. Strip lines that match agent section headers (## Your Persona, ## Procedure, ## Output Format)
3. Wrap the sanitized topic in delimiters: <user_topic>...</user_topic>

Replace $ARGUMENTS in the loaded prompts with the sanitized, wrapped topic. Do NOT create a Team.

Default mode launches exactly 3 agents:

Agent:
  subagent_type: general-purpose
  name: MELCHIOR-1
  model: opus
  description: "MELCHIOR-1 engineering analysis"
  prompt: (contents of agents/melchior.md with $ARGUMENTS replaced by the topic)

Agent:
  subagent_type: general-purpose
  name: BALTHASAR-2
  model: opus
  description: "BALTHASAR-2 engineering analysis"
  prompt: (contents of agents/balthasar.md with $ARGUMENTS replaced by the topic)

Agent:
  subagent_type: general-purpose
  name: CASPAR-3
  model: opus
  description: "CASPAR-3 engineering analysis"
  prompt: (contents of agents/caspar.md with $ARGUMENTS replaced by the topic)

Custom config mode iterates over the agent list and launches all agents (voting + advisory) simultaneously:

For each agent in config.agents:
  Agent:
    subagent_type: general-purpose
    name: (agent.name)
    model: (agent.model, default "opus")
    description: "(agent.name) engineering analysis"
    prompt: (contents of agent.file with $ARGUMENTS replaced by the topic)

Advisory agents use the same prompt format as voting agents. Their role distinction is handled by MAGI Core, not at launch time.

Phase 3.0: Agent Report Display

Once all persona agents return, display each agent's full human-readable analysis to the user BEFORE invoking MAGI Core. This gives users transparency into each MAGI's unique perspective.

For each agent (voting first, then advisory):

1. Display the agent's response, stripping only the <!-- MAGI_OUTPUT {...} --> JSON block (keep all human-readable content: Scores, Overall Analysis, Verdict, Risks, References)
2. Use a separator between agents:

   ━━━ [AGENT-NAME] [{Persona}] ━━━
   

3. After all agents are displayed, output:

   ━━━ MAGI Core — Integrated Judgment ━━━
   

Then proceed to Phase 3.

Phase 3: Judgment via MAGI Core

Judgment, synthesis, and output formatting are delegated to the MAGI Core agent — the integrated intelligence of the MAGI System. This ensures true encapsulation: the orchestrator does not perform judgment; it only coordinates.

Step 1: Classify Responses

Once all persona agent calls return, classify the results. Let N = number of voting agents (default 3):

• N/N voting agents responded: Proceed to Step 2
• (N-1)/N voting agents responded: Proceed with warning. Note the missing agent.
• < ceil(N/2) voting agents responded: Report failure. Do NOT proceed. Suggest the user retry.
• Advisory agent failures: Note but proceed.

A response is valid if the agent produced any substantive content. MAGI Core handles extraction and malformed output detection.

Retry on extraction failure: If a voting agent responded but produced no parseable <!-- MAGI_OUTPUT --> block and no readable prose scores, re-spawn that agent ONCE with the original prompt plus: IMPORTANT: Your previous response did not include a valid <!-- MAGI_OUTPUT --> block. You MUST emit the structured output block at the end of your response. If the retry also fails, treat as missing response. Maximum one retry per agent.

Step 2: Build MAGI Core Input

Construct the input data block to replace $AGENT_RESULTS in magi-core.md:

### Topic
(the sanitized topic from Phase 2)

### Agent Configuration
| Agent | Persona | Role |
|-------|---------|------|
| (name) | (persona) | voting/advisory |

### Agent Responses

#### [AGENT-NAME-1]
(full raw response from agent)

#### [AGENT-NAME-2]
(full raw response from agent)

#### [AGENT-NAME-3]
(full raw response from agent)

Step 3: Launch MAGI Core

Replace $AGENT_RESULTS in the loaded magi-core.md with the input data block from Step 2.

Agent:
  subagent_type: general-purpose
  name: MAGI-CORE
  model: opus
  description: "MAGI Core integrated judgment"
  prompt: (contents of magi-core.md with $AGENT_RESULTS replaced)

Step 4: Display and Parse Judgment

Display the MAGI Core agent's response directly — it IS the deliberation report.

Extract the <!-- MAGI_JUDGMENT {...} --> block from the response. Parse:

• overall_verdict: for Phase 5 trigger decisions
• vote_tally: for Phase 5 options
• confidence: for display
• bias_flags: for Phase 5 considerations
• agents[]: for dialectic briefings and dissenter identification

Step 4.5: Write Deliberation Log

After parsing the <!-- MAGI_JUDGMENT --> block, persist a structured log for future accuracy analysis. This step is fire-and-forget — failures do not block Phase 5 or affect user experience.

1. Create the log directory if it does not exist: mkdir -p .magi/history
2. Generate an ISO 8601 timestamp for the filename (e.g., 2026-03-24T14-30-00)
3. Construct the log JSON:

   {
     "schema_version": "1.0",
     "timestamp": "(ISO 8601)",
     "topic": "(sanitized topic from Phase 2)",
     "judgment": {
       "overall_verdict": "(from MAGI_JUDGMENT)",
       "vote_tally": "(from MAGI_JUDGMENT)",
       "confidence": "(from MAGI_JUDGMENT)",
       "reversibility": "(from MAGI_JUDGMENT)",
       "bias_flags": [],
       "conditions": "(from MAGI_JUDGMENT)",
       "agents": "(agents array from MAGI_JUDGMENT)"
     }
   }
   

4. Use Write to create .magi/history/{timestamp}.json
5. Log rotation: use Bash to count files in .magi/history/ — if > 100, delete the oldest files (by filename sort) to keep only 100

If any step fails, log a brief warning and continue to Step 5.

Step 5: Micro-Dialectic (Automatic on 2:1 Split)

If the vote is a 2:1 split AND dialectic mode is NOT already active, automatically re-spawn the dissenting agent with a micro-rebuttal prompt:

You are {dissenter name}. The majority of the council disagrees with your verdict of {dissenter verdict}. Their average score is {majority avg} vs your {dissenter avg}. State in 2-3 lines whether you maintain your position and why. No MAGI_OUTPUT block needed.

Launch with the same model as the initial round. Display the micro-rebuttal after the deliberation report under ### Dissenter Response. This does NOT change the verdict — it gives the dissenter a voice without a full dialectic round.

Phase 3.7: Dialectic Round (Optional)

Activation: Only when --dialectic flag is in the topic OR "dialectic": true in config. Skip otherwise.

After MAGI Core returns, if dialectic is active:

1. Parse <!-- MAGI_JUDGMENT --> for each agent's verdict, avg_score, and summary
2. Build cross-agent briefings per references/dialectic-format.md
3. Re-spawn all voting agents in parallel with rebuttal prompts (same model as initial round)
4. Collect rebuttal responses
5. Re-invoke MAGI Core: append a ### Dialectic Rebuttals section to the input data with each agent's rebuttal text
6. Display the updated MAGI Core output (replaces initial output)

Phase 3.8: Adversarial Challenge (Optional)

Activation: Only when --adversarial flag is in the topic OR "adversarial": true in config. Skip otherwise.

After voting is finalized (post-dialectic if applicable):

1. Parse <!-- MAGI_JUDGMENT --> to determine consensus
2. Select devil's advocate per references/dialectic-format.md selection rules
3. Re-spawn selected agent with adversarial prompt
4. Display adversarial analysis after the deliberation report

Phase 5: Interactive Drill-Down (Optional)

After the verdict is delivered, offer the user a follow-up action using AskUserQuestion.

Use the <!-- MAGI_JUDGMENT --> block parsed in Phase 3 Step 4 to determine the verdict outcome and dissenter identity.

Trigger

Phase 5 is conditionally offered based on the verdict outcome:

Verdict Outcome	Phase 5 Action
3:0 Unanimous Approve	Trigger — Offer follow-up question + accept
2:1 Split	Trigger — Offer dissenter deep-dive + re-evaluate + accept
Any Conditional Approval	Trigger — Offer re-evaluate + accept
1:1:1 Indeterminate	Trigger — Offer all-agent deep-dive + re-evaluate + accept
3:0 Unanimous Reject	Trigger — Offer re-evaluate + accept

Options

Present the following choices via AskUserQuestion:

1. "Deep dive into [dissenter]'s concerns" — Available only if there was a 2:1 split. Replace [dissenter] with the actual dissenting agent's name (e.g., "Deep dive into BALTHASAR-2's concerns"). If selected:

   • Re-spawn the dissenting agent with a focused prompt: the original topic plus the instruction "Elaborate on your concerns in detail. Explain what specific risks you foresee and what conditions would change your verdict."
   • Present the agent's expanded analysis to the user

2. "Re-evaluate with amended proposal" — Always available. If selected:

   • Ask the user (via AskUserQuestion with a text-friendly prompt) what modifications they want to make to the original proposal
   • Re-run the full deliberation (Phase 1 through Phase 3) with the amended topic

3. "Ask [agent] to elaborate on [axis]" — Always available. Present available agents and their axes. If selected, re-spawn the chosen agent with: "Elaborate on your [axis] evaluation. Provide deeper analysis, specific evidence, and concrete recommendations for this dimension." Display the expanded analysis.

4. "Ask a follow-up question" — Always available. If selected, use AskUserQuestion to get the user's question, then re-spawn all agents with the follow-up context appended to the original topic.

5. "Export deliberation as markdown" — Always available. If selected, compile the full deliberation (agent reports + MAGI Core judgment) into a single markdown file and write to .magi/exports/{timestamp}.md using Write. Confirm the file path to the user.

6. "Run dialectic round" — Available if dialectic mode was NOT already active. If selected, run Phase 3.7 dialectic round on the existing results and re-invoke MAGI Core for updated judgment.

7. "Run adversarial challenge" — Available if adversarial mode was NOT already active. If selected, run Phase 3.8 on the existing verdict.

8. "Accept verdict" — Always available. This is the default option. If selected:

   • End the session with no further action

Implementation Notes

• 3:0 Unanimous Approve: Offer "Ask a follow-up question", "Export deliberation as markdown", and "Accept verdict". Users may want follow-up even on unanimous verdicts.
• 2:1 Split: Option 1 uses the dissenter identified in MAGI_JUDGMENT.agents[]. Re-spawn with focused elaboration prompt.
• 1:1:1 Indeterminate: Replace option 1 with "Deep dive into each agent's position" — re-spawn all three agents with focused elaboration prompts.
• 3:0 Unanimous Reject: Omit option 1 (no dissenter). Offer re-evaluate to let the user amend their proposal.
• Conditional Approval (any split): Always offer re-evaluate so the user can address conditions.
• This phase may recurse: if the user re-evaluates, the new deliberation applies the same conditional Phase 5 logic.

Comparison Mode Phase 5

For comparison topics, Phase 5 trigger and options differ:

Recommendation Outcome	Phase 5 Action
3:0 Unanimous	Skip — Session ends after MAGI Core output
2:1 Split	Trigger — Offer dissenter deep-dive + re-evaluate + accept
1:1:1 Split	Trigger — Offer all-agent deep-dive + re-evaluate + accept

Options:

1. "Deep dive into [dissenter]'s recommendation" — Re-spawn dissenter with: "Explain why you recommend [their choice] over [majority choice]. Detail the specific advantages and risks." For 1:1:1 splits, replace with "Deep dive into each agent's recommendation" and re-spawn all three.
2. "Re-evaluate with narrowed options" — Ask the user which options to keep or amend, then re-run the comparison deliberation
3. "Accept recommendation" — End session