magi-mode

MAGI Protocol (Modular Automated Guided Iteration)

This skill implements the "Lean MAGI" protocol, a high-efficiency multi-agent framework designed to resolve complex, high-stakes, or ambiguous software engineering problems. It utilizes a "Verification Loop" of specialized technical modules to enforce invariants, detect conflicts, and synthesize code without human management overhead.

The Two-Path Model

The Orchestrator MUST select an execution path based on the task's complexity and ambiguity:

1. FAST_PATH (Efficiency): Used for low-complexity, low-ambiguity tasks (e.g., surgical bug fixes). Workflow: Scoping (Spec) -> Synthesis (Code) -> Single Auditor (Core Auditor).
2. RIGOR_PATH (Correctness): Used for high-complexity, high-ambiguity, or security-sensitive tasks. Workflow: Scoping (Spec + Scaffold) -> Synthesis (Code) -> Multiple Tier 1 Scanners (Security, Perf, Auditor).

The Core Modules (Execution)

The Orchestrator MUST dynamically select specialized modules best suited for the specific task.

• Scoping: Investigates the initial request, searches the codebase, and writes the project.magi.json specification.
• Synthesis: Writes the actual C++ code by combining technical requirements and adhering to constraints.
• The Scanners (Auditors): Specialized technical mandates (Security, Performance, Auditor, etc.) that perform rigorous, boolean-checklist-based audits of the generated code.

The Auxiliary Modules

To maintain focus and avoid context dilution, specialized tasks are delegated:

1. Consolidation: (Rigor Path Only) Condenses raw feedback from multiple Scanners into a strict list of actionable constraints in constraints.magi.[iteration].json.

2. Training (Manual): A manually-invoked module to capture knowledge or systemic gaps discovered during the process and upgrade the Scanner rulesets. This is NOT automatically called in the default consensus verification loop.

3. Release: A terminal module invoked with a clean context to handle workspace hygiene, formatting, and final staging/upload of CLs.

TONE MANDATE (SIGNAL-TO-NOISE): To eliminate conversational noise, conserve tokens, and maximize parsing stability, the Orchestrator MUST instruct ALL sub-agents (except itself) to adopt a neutral, data-driven tone.

• Zero Preamble/Postamble: Sub-agents MUST NOT use conversational filler, greetings, or explanations of their work.
• Artifacts Only: If an agent's mandate is to generate JSON or C++ code, its entire output MUST consist only of that raw data structure.
• Scanners: Scanners MUST act as rigorous, objective auditors focusing strictly on technical facts and data.

TOOL AGNOSTIC MANDATE: The protocol instructions MUST remain tool-agnostic. Do not assume specific tool names (e.g., update_topic, read_file, write_file). Use generic terms like "read from disk," "save to disk," or "report status."

ENVIRONMENT GROUNDING MANDATE: All sub-agents MUST read project.magi.json#environment immediately upon invocation to ground themselves in the active VCS (JJ or GIT) and Harness (JETSKI or GENERIC_CLI). They MUST adjust their tool usage and command construction natively to match this environment. They MUST also ensure that any interim files generated during execution (e.g., drafts, reviews, logs) are placed in the configured directory specified by project.magi.json#environment/temp_directory (e.g., agents/skills/magi-mode/.temp/) to minimize permission prompts and maintain workspace hygiene.

THE CHECKLIST LIFECYCLE STATE MACHINE: The session's verification integrity is governed by a deterministic boolean checklist state machine. The automated checklist state itself only transitions or is modified during three key steps across the stages:

• Activation (Stage 2, Step 3): The Orchestrator reads all selected rulesets in personas/**/*.json, takes the Union Set of all keys, and initializes the active checklist in state_block.magi.json with all values set to false.
• Assertion (Stage 3, Step 1 & 2): Scanners toggle their domain-specific keys in their ReviewFeedback checklist. The Orchestrator (or Consolidation in RIGOR_PATH) performs a Logical AND consolidation across all reviews. A key in the consolidated state_block.magi.json#checklist only becomes true if ALL scanners that have that specific key defined in their persona asserted true. Any false keys or unlisted_issues_found are translated into strict constraints in constraints.magi.[iteration].json.
• Upgrades (Stage 3, Step 3): Once consensus is reached (all checklist items are true), the Training agent uses unlisted_issues_found history to append new keys to the appropriate personas/**/*.json checklists.

STAGE SIGNALING: The Orchestrator MUST use an appropriate status-reporting mechanism prior to invoking any sub-agents to clearly identify the current stage of the MAGI protocol to the user (e.g., "MAGI Stage 2: Generate").

DECENTRALIZED HANDOFFS: To reduce Orchestrator overhead, agents SHOULD include a next_stage field in their JSON output to signal the intended successor. Note: Scanners and Scoping sub-agents are exempt as their successors are deterministic.

• Implementation / Test Expert: PREPARATION
• Consolidation: SYNTHESIS (if iteration needed) or VALIDATION
• Synthesis: TEST_FILLING (if implementation) or CRITIQUE (if review/audit)
• Training: VALIDATION (if manually invoked)
• Validation: DEPLOYMENT

Workflow Stages

The MAGI protocol runs through four distinct stages. To reduce LLM context size, detailed step-by-step rules for each stage are maintained in separate references:

1. Stage 1: Specify & Investigate: Scoping, environment grounding, and project specifications.
   • Reference: stage1_specify.md
2. Stage 2: Generate: Scaffold generation, test bounds (TDD), parallel implementations, and synthesis.
   • Reference: stage2_generate.md
   • TDD Mandate: To enforce Test-Driven Development, stubbed tests MUST fail by default using ADD_FAILURE() << "NOT IMPLEMENTED".
3. Stage 3: Refine: Multi-agent audits (checklist review), constraint consolidation, conflict resolution, and training.
   • Reference: stage3_refine.md
4. Stage 4: Release: Final validation, workspace cleanup, formatting, and CL deployment.
   • Reference: stage4_release.md

Specialized Modes

• Manual Intervention: If ambiguity_level == "HIGH" or context_resolved == false, the Orchestrator MUST pause for human verification before proceeding to execution.
• Human-in-the-Loop Audit: For critical security changes, the Orchestrator MAY present the final synthesized code and consolidated checklist to the human for a final "PASS/FAIL" before deployment.

Workspace Management & Isolation

• Interim File Isolation: Place all interim files (drafts, reviews, logs) in temp_directory to minimize permission prompts and maintain workspace hygiene.
• Cleanup: Release (or the agent in charge of cleanup) MUST delete the configured temporary directory at the end of the run.
• VCS & Staging Workflows: Sibling modifications to MAGI rulesets (Training) MUST be branched and uploaded as separate changes to Gerrit. For details, consult vcs_isolation.md.

Reference Guides & Drivers

• Production Hardening & Tooling: For coding standards, reclient build guidance, and C++ lifecycle rules, consult tooling_guidance.md.
• Harness & Orchestration Patterns: To understand Centralized (Jetski) vs. Decentralized (MAS CLI) coordination, consult orchestration_patterns.md.

When to Invoke

• When a flaw is hard to resolve without trade-offs.
• When a bug is platform-specific and might impact others.
• When a new feature has significant performance or security implications.

Testing Protocol

To validate MAGI execution and prevent regressions, consult SKILL_TEST_PLAN.md and SKILL_TEST.md for strategy and unit tests.

Skill Resource Map

To satisfy reachability requirements for the multi-agent system, all primary catalogs, test files, and examples are linked below:

• Routing and Specialization: ROUTING.md
• JSON Configuration Contract: EXAMPLES.md