mahou

魔法 — mahou is Japanese for "magic".

A portable set of opencode slash commands that enforce disciplined software engineering workflows — debugging, review, brainstorm, orchestration, and project lifecycle management.

No plugins, no MCP servers, no npm dependencies. Just markdown command files and reference docs.

Table of Contents

• Background
• Install
• Usage
• Quick Reference
• Commands
• Workflows
• Architecture
• Repository Structure
• Contributing
• License
• Changelog

Background

opencode ships built-in plan and build agents that do the work. mahou commands enforce how the work is done — root cause before fix, verify before report, design before code, ship after verify.

The framework operates across three layers:

• Project layer — initialize projects, research approaches, map existing codebases. Produces PROJECT.md, ROADMAP.md, and map.md for cross-feature context.
• Feature layer — brainstorm specs, orchestrate implementation, review code, verify against spec. The core build cycle with feedback loops.
• Lifecycle layer — resume sessions, ship PRs. Closes the loop between implementation and delivery.

How it works

Each command is a markdown file with YAML frontmatter. opencode reads the frontmatter to register the slash command, route it to an agent, and assign a model. The body becomes the command's prompt.

• Tool access is enforced at the agent level, not requested. The agent: frontmatter routes read-only commands (ask, review, verify, secure, resume, ship, orchestrator) to the mahou-readonly agent, which denies edit/write and destructive bash at the tool level. Design/project commands (brainstorm, new-project, init, postmortem) run under mahou-planner, which denies every file write outside ./.mahou/**. opencode's command frontmatter does not support a tools: field — enforcement comes from these agents.
• Role subagents carry their own enforcement. The orchestrator dispatches implementer, spec-reviewer, code-quality-reviewer, and integration-reviewer subagents; review dispatches issue-verifier. Each is a real opencode agent with tool-level permission config (reviewers deny edit/write), not just a prompt template. The orchestrator's own agent restricts the Task tool to exactly these subagents via permission.task.
• Reference docs load via @-includes. Command bodies use @{{MAHOU_HOME}}/skills/<name>/SKILL.md to pull in technique guides. The same skills are also installed to ~/.config/opencode/skills/ for the native skill tool (on-demand, permission-gated per agent).
• Zero structural token cost. Nothing auto-injects on every prompt. All context loads only when a command is invoked. Heavy data (web pages, large file reads) stays inside subagent disposable context.
• No runtime dependencies. Everything is static markdown, one TypeScript plugin (compaction persistence), and one TypeScript tool (vision fallback). Nothing is downloaded from the internet. No MCP servers, no telemetry.

Install

Prerequisites

• opencode installed and working
• That's it. No npm dependencies, no plugins, no MCP servers.

Windows (PowerShell)

cd mahou
.\install.ps1

macOS / Linux (bash)

cd mahou
chmod +x install.sh
./install.sh

After install, restart opencode for the new commands to appear.

Upgrading from magic-pi

mahou was previously named magic-pi-opencode. The installer does not remove the old global files. If you upgraded, clean up the legacy install once:

# Windows (PowerShell)
Remove-Item "$env:USERPROFILE\.config\opencode\magic-pi" -Recurse -Force
Remove-Item "$env:USERPROFILE\.config\opencode\command\magic*.md" -Force

# macOS / Linux (bash)
rm -rf ~/.config/opencode/magic-pi
rm -f ~/.config/opencode/command/magic*.md

Existing project artifacts live in ./.magic-pi/; rename the folder to ./.mahou/ so the rebranded commands can find them:

mv ./.magic-pi ./.mahou

What the installer does

1. Copies commands/*.md to ~/.config/opencode/commands/, replacing {{MAHOU_HOME}} with the resolved absolute path (for @-include compatibility).
2. Copies agents/ to ~/.config/opencode/agents/ (permission-enforced agents), skills/ to ~/.config/opencode/skills/ and ~/.config/opencode/mahou/skills/ (skill-tool discovery + @-include), plugins/ to ~/.config/opencode/plugins/, and tools/ to ~/.config/opencode/tools/.
3. Copies references/ to ~/.config/opencode/mahou/references/ (subagent prompt templates + scripts).
4. Cleans up legacy singular-dir installs (~/.config/opencode/command/).
5. Nothing is downloaded from the internet. No dependencies required.

Uninstall

.\install.ps1 -Uninstall      # Windows

./install.sh --uninstall       # Unix

Usage

Typical workflow

/mahou-new-project I want to build an e-commerce platform with React + Node + Postgres
/mahou-research --explore e-commerce architecture patterns
/mahou-brainstorm auth subsystem
/mahou-orchestrator ./.mahou/plans/<uuid>.md
/mahou-verify
/mahou-ship

If verify returns REPLAN, go back to brainstorm. If FIX_FORWARD, use /mahou-debug.

Quick start (single feature)

If you already have a project and just want to build one feature:

/mahou-brainstorm I want to add a webhook system for real-time notifications
/mahou-orchestrator ./.mahou/plans/<uuid>.md
/mahou-verify
/mahou-ship

Resume after restart

/mahou-resume
/mahou-orchestrator ./.mahou/plans/<uuid>.md  ← resumes from last task

Quick Reference

Command	Purpose	Access
/mahou	List all mahou commands	read-only
/mahou-new-project	Initialize project — PROJECT.md + ROADMAP.md	full (.mahou/ only)
/mahou-init	Generate codebase map for existing projects	full (.mahou/ only)
/mahou-research	Internet research — explore, diagnose, or lookup	full (webfetch)
/mahou-ask	Answer questions / explain code without changes	read-only
/mahou-debug	Systematic root-cause debugging (4 phases)	full
/mahou-review	Code review of existing scope (discover, triage, verify, report)	read-only
/mahou-brainstorm	Design to spec to implementation plan	spec/plan writable
/mahou-designer	Design and ship production-grade frontend interfaces	full
/mahou-orchestrator	Execute a plan task-by-task via subagents with two-stage review	read-only (delegates)
/mahou-ultracode	Max-effort execution via large-scale parallel subagent waves	full
/mahou-verify	Verify implementation against spec — PASS, FIX_FORWARD, or REPLAN	read-only
/mahou-secure	Security verification of a change — PASS, FIX, or ESCALATE	read-only
/mahou-resume	Resume work from previous session with reconciliation	read-only
/mahou-ship	Push branch, create PR, filter .mahou/ artifacts	read-only + bash
/mahou-postmortem	Write a post-mortem for a resolved incident	.mahou/ only

Commands

/mahou-ask

What it does: Answers questions and explains code without making any changes.

When to use: When you want to understand how code works, trace logic, or explore a codebase without risk of accidental edits.

Process: Direct answer — no phases. Reads the relevant code and explains with specific file:line references. If the question is ambiguous, asks for clarification first. If you ask it to make changes, it redirects you to /mahou-debug, /mahou-brainstorm, or the build agent.

Tools & access: Read-only — read, bash, grep, glob. No edit or write tools are available.

Examples:

/mahou-ask How does the retry logic in the HTTP client work?
/mahou-ask What does the PaymentService class depend on?

/mahou-debug

What it does: Systematic root-cause debugging. Finds and fixes the root cause, not the symptom.

When to use: Any technical issue — test failures, bugs, unexpected behavior, performance problems, build failures, integration issues.

Process: Four phases, each completed before the next:

1. Root Cause Investigation — read error messages carefully, reproduce consistently, check recent changes (git diff, git log, git bisect), gather evidence at component boundaries, trace data flow backward to where bad values originate.
2. Pattern Analysis — find similar working code in the codebase, compare against the reference implementation, identify every difference.
3. Hypothesis & Testing — form a single hypothesis, test the smallest possible change, verify before continuing. If it doesn't work, form a new hypothesis — don't stack fixes.
4. Implementation — create a failing test case, implement a single fix at the root cause, verify with the verification-before-completion discipline (run the failing repro AND the relevant suite, report the evidence), then harden with defense-in-depth and a regression test.

If systematic investigation reveals a genuinely environmental/timing/external issue, document what was investigated, add graceful handling (retry, timeout, error message) and monitoring — but 95% of "no root cause" cases are incomplete investigation.

Iron law: No fixes without root cause investigation first. If you haven't completed Phase 1, you cannot propose fixes.

Tools & access: Full — read, write, edit, bash, grep, glob, agent. Investigation (Phases 1-3) is read-only; fixes (Phase 4) use edit/write.

Subagents: Dispatches explore subagents (read-only) for Phase 1-2 investigation — locating failing code paths, mapping data flow, finding working examples. Runs independent research questions in parallel.

Examples:

/mahou-debug The auth tests are failing intermittently after the refactor
/mahou-debug Payment webhook returns 500 for amounts over $1000

/mahou-review

What it does: Code review of an existing scope. Finds real issues, verifies them independently, and reports only what survives verification.

When to use: When you want to review a module, feature, directory, or PR. For a single specific bug, use /mahou-debug instead.

Process: Four phases:

1. Discovery — parse the scope, find relevant files, read each one, identify key responsibilities and dependencies. Dispatches explore subagents for broad areas. Detects UI surfaces and loads UI critique methodology if applicable.
2. Triage — lists potential issues across categories: Correctness (logic bugs, race conditions, dead code), Security (injection, auth bypass, secrets), Performance (N+1 queries, memory leaks, quadratic algorithms), Architecture (circular dependencies, god modules, tight coupling), and UI/UX (interaction states, cognitive load, AI slop, accessibility) when UI is in scope. No style or formatting nits.
3. Verification — for each issue, an independent general subagent reads the actual code and returns CONFIRMED, REFUTED, or UNDETERMINED. Verifiers are read-only by instruction. Dispatched in parallel. UI issues use two-assessment synthesis (design review + code inspection).
4. Final Report — reports only confirmed issues with evidence and fix suggestions. Refuted and undetermined issues are listed separately.

Tools & access: Read-only — read, bash, grep, glob, agent. No edit or write tools are available.

Examples:

/mahou-review src/services/payment/
/mahou-review Review the auth module for security issues

/mahou-brainstorm

What it does: Turns a vague idea into a validated design spec and a detailed implementation plan through collaborative dialogue — without touching the codebase.

When to use: When designing a new feature or subsystem before implementation.

Process: A 13-step checklist:

1. Explore project context — reads PROJECT.md, ROADMAP.md, prior dependent specs, research briefs, codebase map, relevant files, and recent commits.
2. Scope check — flag if the request spans multiple independent subsystems.
3. Ask clarifying questions, one at a time, multiple choice preferred.
4. Propose 2-3 approaches with trade-offs.
5. Present the design in sections, getting approval after each. Enumerate key states for UI features (default, empty, loading, error, success, edge cases). Run AI slop test for visual direction.
6. Write the spec to ./.mahou/specs/<uuid>.md. Adaptive depth: compact form for clear requests, full structured form for ambiguous ones.
7. Spec self-review (unfilled tokens, consistency, scope, ambiguity).
8. User reviews the spec.
9. Write the implementation plan to ./.mahou/plans/<uuid>.md.
10. Plan self-review.
11. User reviews the plan.
12. Update ROADMAP.md — set feature status to planned.
13. Hand off to /mahou-orchestrator or the build agent.

Hard gate: No code, scaffolding, or implementation action until the design is presented AND approved. This applies to every request regardless of perceived simplicity.

Replan support: If returning from /mahou-verify with a REPLAN verdict, appends to the spec's revision log (round N+1) without overwriting prior rounds. Revises only affected sections.

Tools & access: Full tool access in frontmatter (read, write, edit, bash, grep, glob, agent). The command's prompt enforces read-only behavior on the codebase — it may ONLY use write/edit on spec, plan, and ROADMAP documents under ./.mahou/.

Example:

/mahou-brainstorm I want to add a webhook system for real-time notifications

Output is spec and plan files under ./.mahou/, not code changes.

/mahou-orchestrator

What it does: Executes an implementation plan task-by-task via subagents, with two-stage review after each task.

When to use: When you have a plan (typically from /mahou-brainstorm) and the tasks are mostly independent. For a single focused change, use the build agent instead.

Process: Per-task cycle:

0. Baseline verification gate — before any task, run the test suite and build once and record the result in state.json. A red baseline stops the orchestration (routes to /mahou-debug); implementing on a red baseline makes every later failure uninterpretable.
1. Capture the BASE_SHA (git rev-parse HEAD).
2. Dispatch an implementer subagent with the full task text pasted into the prompt (the subagent never reads the plan file).
3. Handle the implementer's status: DONE, DONE_WITH_CONCERNS, BLOCKED, or NEEDS_CONTEXT. On external unknowns, dispatches a research subagent with webfetch access.
4. Dispatch a spec compliance reviewer — verifies the implementer built what was requested, nothing more, nothing less. Loop until it passes.
5. Dispatch a code quality reviewer — verifies the implementation is clean, tested, and maintainable. Loop until Approved.
6. Mark the task complete, update state.json and ROADMAP.md.
7. Every N tasks (default 3): dispatch an integration reviewer to check seam bugs between tasks.

Review loops re-dispatch the same implementer with the receiving-code-review discipline (fix, don't argue; push back only with code evidence; re-verify; report deltas). Implementers must verify before reporting DONE — the verification-before-completion discipline.

After all tasks: a final code review for the entire implementation, then branch finish guidance.

Two-stage review: Spec compliance runs first (did they build what was asked?), then code quality (is it well-built?). The order is mandatory — code quality review does not start until spec compliance passes.

Tools & access: Read-only orchestrator — read, bash, grep, glob, agent. No edit or write tools. Subagents handle all writes and commits. May write to state.json and ROADMAP.md via bash.

Model selection: Uses ./.mahou/models.json (task/role -> model mapping) if present; otherwise the session's model — the opencode default. See "Model selection" below.

Example:

/mahou-orchestrator ./.mahou/plans/<uuid>.md

Integration: Upstream from /mahou-brainstorm (produces the plan). Downstream to /mahou-verify after all tasks pass review.

/mahou-new-project

What it does: Initializes a new project with deep context gathering, producing PROJECT.md (project context, architecture, conventions, decisions log) and ROADMAP.md (feature breakdown, dependencies, build order, status tracking).

When to use: Once per project, before any feature brainstorming. This creates the project layer that all subsequent features reference.

Tools & access: Full — read, write, bash, grep, glob, agent. Writes ONLY to ./.mahou/PROJECT.md and ./.mahou/ROADMAP.md.

Example:

/mahou-new-project I want to build an e-commerce platform with React + Node + Postgres

/mahou-init

What it does: Generates a codebase map (./.mahou/map.md) for an existing project. Maps modules, responsibilities, dependencies, patterns, and entry points. Does NOT generate AGENTS.md files (preserves zero structural token cost).

When to use: Once per existing codebase, before working on features in it. For new projects from scratch, use /mahou-new-project instead.

Tools & access: Full — read, write, bash, grep, glob, agent. Writes ONLY to ./.mahou/map.md.

/mahou-research

What it does: Internet-connected research using Yahoo/Bing search via the native webfetch tool. Three modes:

• --explore (default): broad comparative research. Dispatches 3-5 subagents in parallel, each fetching 2-3 pages. Returns a synthesized brief saved to ./.mahou/research/<uuid>.md.
• --diagnose: narrow deep-dive. Dispatches 1 subagent for a specific question (3-5 pages). Returns a targeted answer saved to ./.mahou/research/<uuid>.md.
• --lookup: quick factual lookup. Direct fetch in main context (1 page, inline answer, no file saved).

When to use: Before /mahou-brainstorm to research approaches, or during /mahou-debug to check how upstream code works.

Tools & access: Full — read, bash, grep, glob, agent, webfetch. Heavy fetching happens inside isolated subagents (explore/diagnose) to keep main context lean.

Examples:

/mahou-research --explore compare Drizzle vs Prisma for Postgres
/mahou-research --diagnose why does SQLite WAL mode cause lock errors
/mahou-research --lookup what port does Express default to

/mahou-verify

What it does: Verifies implementation against spec. Dispatches verifier subagents per UAT criterion, synthesizes verdicts, and produces a routing verdict: PASS, FIX_FORWARD (route to /mahou-debug), or REPLAN (route to /mahou-brainstorm).

When to use: After /mahou-orchestrator completes all tasks for a feature. This is the gate between implementation and shipping.

Tools & access: Read-only — read, bash, grep, glob, agent.

/mahou-resume

What it does: Restores session context after restart. Reads state.json, identifies the last in-progress task, runs git-diff reconciliation to detect manual changes, and routes back to the orchestrator.

When to use: After restarting opencode mid-orchestration.

Tools & access: Read-only — read, bash, grep, glob.

/mahou-ship

What it does: Pushes branch, creates PR with auto-generated body sourced from spec, plan, state, and verification report. Filters .mahou/ planning artifacts from the PR diff.

When to use: After /mahou-verify returns PASS.

Process: Runs a test gate before pushing — the project's test suite must pass or the ship stops and routes to /mahou-debug. Never push a red branch.

Tools & access: Read-only + bash — read, bash, grep, glob.

/mahou-designer

What it does: Designs AND ships production-grade frontend interfaces to a studio bar — not prototypes. Runs the impeccable design discipline: read the room, shape before build, build to the bar, inspect and iterate, with the two-altitude AI slop test, absolute bans (side-stripe borders, gradient text, glassmorphism-as-default, hero-metric template, eyebrow labels), and brand/product registers. Critique is an intent inside the command (report-only unless asked to fix).

When to use: Frontend interface work — design, redesign, polish, or critique of websites, landing pages, dashboards, product UI. Not for backend-only work.

Tools & access: Full (designs AND builds). Runs on the session's model (see "Model selection"). Loads mahou-design-craft skill for the craft and critique framework.

Example:

/mahou-designer Redesign the settings page with a better information hierarchy

/mahou-ultracode

What it does: Max-effort execution for work too large for one context window: codebase-wide audits, large migrations, multi-file refactors, cross-checked research. Fans out subagent waves (≤16 concurrent) via the Task tool, runs adversarial verification passes, fix-until-green loops, and multi-angle planning, then returns one coordinated, verified answer.

When to use: 50+ files, 100+ items, whole-repo sweeps. For vague or green-field projects it defers to /mahou-brainstorm or the plan agent first, and confirms scope before fanning out writers.

Tools & access: Full. Loads mahou-ultracode-patterns skill for the wave patterns and budget rules.

Example:

/mahou-ultracode Audit the entire codebase for missing auth checks and fix them

/mahou-secure

What it does: Security verification gate before shipping. Reviews the change's diff against 7 categories (secrets, injection, authz, data exposure, input validation, dependencies, crypto), verifies each triaged issue via independent subagents (CONFIRMED / REFUTED / UNDETERMINED), and produces a verdict: PASS (→ /mahou-ship), FIX (→ /mahou-debug), or ESCALATE (→ /mahou-brainstorm). Writes a report to ./.mahou/verify/secure-<uuid>.md.

When to use: After /mahou-verify returns PASS and the change is security-sensitive (auth, payments, user data, secrets, network input).

Tools & access: Read-only via the mahou-readonly agent.

Example:

/mahou-secure <feature name or commit range>

/mahou-postmortem

What it does: Produces a post-mortem for a resolved bug or incident — timeline, root cause analysis, the fix, defense-in-depth applied, and monitoring follow-ups — written to ./.mahou/postmortems/<uuid>.md. The codebase stays untouched.

When to use: After a bug is fixed and verified (typically after /mahou-debug), to preserve the learning.

Tools & access: Runs under the mahou-planner agent — writes ONLY to ./.mahou/postmortems/ (tool-enforced).

Example:

/mahou-postmortem The intermittent auth test failure we just root-caused

Model selection (model orchestrator)

Mahou never hardcodes a provider or model ID. Which model a command runs on resolves in this order:

1. Project config — a repository can set its own default by adding an opencode.json in the repo root with "model": "provider-id/model-id". It overrides everything below and is safe to commit.
2. Global config — ~/.config/opencode/opencode.json "model" is the machine-wide default.
3. Session — whatever model the current session uses (set via /models or opencode run --model ...). With no config, opencode uses its own default.

.mahou/models.json (routing)

For per-role model routing during orchestration, a repository can provide .mahou/models.json (schema below; a local example lives at .mahou/models.json.example). It maps task categories and subagent roles to model IDs:

{
  "default": "provider-id/model-id",
  "roles": {
    "implementer": "provider-id/model-id",
    "spec-reviewer": "provider-id/model-id",
    "code-quality-reviewer": "provider-id/model-id",
    "integration-reviewer": "provider-id/model-id"
  },
  "tasks": {
    "mechanical": "provider-id/model-id",
    "standard": "provider-id/model-id",
    "capable": "provider-id/model-id"
  }
}

• If .mahou/models.json exists, the orchestrator (/mahou-orchestrator) and /mahou-ultracode use it to pick models for dispatch and reporting, falling back to its default for anything unmapped.
• If it does not exist, mahou falls back to the session's model — the opencode default. Mahou never invents a provider ID.
• .mahou/models.json is machine-specific (provider IDs). The .mahou/ directory is gitignored in this repo; keep the example local.

Limitations

OpenCode applies model config at load time. A repo's model choice takes effect when opencode starts in that repo (repo opencode.json) or when you set it with /models in a session. Plugins have no config hook, so .mahou/models.json cannot auto-switch the active model — when it calls for a different model than the session is running, the orchestrator asks you to set it via /models before dispatching subagents. Subagents inherit the dispatcher's model unless an agent's config pins one.

Workflows

Debug a bug

When something is broken, reach for /mahou-debug. It runs the 4-phase discipline end-to-end — investigation, pattern analysis, hypothesis, fix, and hardening.

/mahou-debug The auth tests are failing intermittently after the refactor

Design and build a feature

Start with /mahou-brainstorm to design, write a spec, and produce an implementation plan. Once the plan is approved, run /mahou-orchestrator to execute it task-by-task with two-stage review per task.

/mahou-brainstorm I want to add a webhook system for real-time notifications
/mahou-orchestrator ./.mahou/plans/<uuid>.md

Review existing code

Run /mahou-review on a scope to find verified issues. Confirmed correctness bugs go to /mahou-debug; architecture findings needing design go to /mahou-brainstorm; surgical fixes use the build agent.

/mahou-review src/services/payment/

Build a whole system from scratch

Start with /mahou-new-project to create the project layer, then brainstorm/orchestrate/verify/ship each feature in dependency order.

/mahou-new-project I want to build an e-commerce platform with React + Node + Postgres
/mahou-research --explore e-commerce architecture patterns
/mahou-brainstorm auth subsystem
/mahou-orchestrator ./.mahou/plans/<uuid>.md
/mahou-verify
/mahou-ship
/mahou-brainstorm product catalog  ← reads PROJECT.md + auth's spec
... repeat for each feature in ROADMAP build order ...

Feedback loop (when verify finds issues)

/mahou-verify
  → PASS: /mahou-ship
  → FIX_FORWARD: /mahou-debug (specific issue) → re-verify
  → REPLAN: /mahou-brainstorm (revises spec, appends revision log)

Architecture

Design invariants

These rules must not be violated by any command or reference:

1. Zero structural token cost — nothing auto-injects on every prompt; everything loads via @-include when invoked or inside subagent isolated context
2. Tool-level read-only enforcement — read-only commands route to the mahou-readonly agent (edit/write and destructive bash denied at the tool level); write access outside ./.mahou/ is denied for planning commands via the mahou-planner agent
3. No MCP, no npm, no plugins, no hooks, no telemetry — pure markdown + native tools (one optional TS plugin for compaction persistence and one optional TS tool for vision fallback; both degrade gracefully when absent)
4. Subagent isolation for heavy work — webfetch and large reads happen in explore/general subagents
5. Feedback loops — every downstream command has PASS / FIX_FORWARD / REPLAN return edges
6. State on disk — state.json written via bash, read only when needed
7. UI principles gated behind UI detection — non-UI projects pay zero cost
8. Append-only specs — replan appends revision log, doesn't overwrite
9. Project layer above feature layer — PROJECT.md + ROADMAP.md link features into a coherent system
10. No AGENTS.md auto-generation — mahou-init produces map.md only

Artifact structure

.mahou/
├── PROJECT.md          ← project context, architecture, conventions, decisions log
├── ROADMAP.md          ← feature breakdown, dependencies, build order, status
├── state.json          ← enriched session state (orchestrator, for resume)
├── map.md              ← codebase map (from /mahou-init, no AGENTS.md)
├── specs/              ← per-feature specs (linked from ROADMAP)
├── plans/              ← per-feature plans (linked from ROADMAP)
├── research/           ← research briefs (project-level + feature-level)
├── verify/             ← verification reports
└── postmortems/        ← post-mortems (Phase 2, directory reserved)

Repository Structure

mahou/
├── install.ps1
├── install.sh
├── commands/              ← opencode slash commands (markdown + frontmatter)
│   ├── mahou.md
│   ├── mahou-ask.md
│   ├── mahou-brainstorm.md
│   ├── mahou-debug.md
│   ├── mahou-designer.md
│   ├── mahou-init.md
│   ├── mahou-new-project.md
│   ├── mahou-orchestrator.md
│   ├── mahou-postmortem.md
│   ├── mahou-research.md
│   ├── mahou-resume.md
│   ├── mahou-review.md
│   ├── mahou-secure.md
│   ├── mahou-ship.md
│   ├── mahou-ultracode.md
│   └── mahou-verify.md
├── agents/                ← permission-enforced agents (installed to opencode)
│   ├── ask.md                       # read-only side-chat agent
│   ├── mahou-readonly.md            # read-only enforcement for review/verify/etc.
│   ├── mahou-planner.md             # .mahou/-only writes for brainstorm/etc.
│   ├── implementer.md               # subagent: one task, tests, commit
│   ├── spec-reviewer.md             # subagent: spec compliance (read-only)
│   ├── code-quality-reviewer.md     # subagent: code quality (read-only)
│   ├── integration-reviewer.md      # subagent: seam checks (read-only)
│   └── issue-verifier.md            # subagent: single-issue verification (read-only)
├── skills/                ← technique guides (SKILL.md, skill-tool discoverable)
│   ├── mahou-condition-waiting/
│   ├── mahou-defense-in-depth/
│   ├── mahou-design-craft/
│   ├── mahou-git-workflow/
│   ├── mahou-receiving-review/
│   ├── mahou-root-cause-tracing/
│   ├── mahou-ui-critique/
│   ├── mahou-ui-design/
│   ├── mahou-ultracode-patterns/
│   ├── mahou-verification-completion/
│   └── mahou-writing/
├── plugins/
│   └── mahou-compaction.ts          # injects .mahou/state.json into compaction
├── tools/
│   └── describe-image.ts            # auxiliary vision tool (non-vision models)
├── references/            ← subagent prompt templates + scripts
│   ├── code-quality-reviewer-prompt.md
│   ├── find-polluter.sh
│   ├── implementer-prompt.md
│   ├── integration-reviewer-prompt.md
│   ├── issue-verifier-prompt.md
│   ├── research-prompt.md
│   ├── spec-reviewer-prompt.md
│   └── verify-prompt.md
└── README.md

Contributing

PRs are welcome. This is a configuration package, not a library — changes should preserve the design invariants listed in Architecture.

To contribute:

1. Fork the repository
2. Create a feature branch
3. Make your changes — follow existing markdown conventions
4. Ensure no design invariants are violated
5. Submit a pull request

For questions or issues, please open a GitHub issue.

License

Share freely. This is a configuration package, not a library.

Changelog

What changed since the previous mahou (Mahou V1, commit 3139f6a).

Mahou V2 (current)

Commands — 4 new: /mahou-designer, /mahou-ultracode, /mahou-secure, /mahou-postmortem — 15 workflow commands total plus /mahou.

Agents — 8 permission-enforced agents: ask, mahou-readonly, mahou-planner, implementer, spec-reviewer, code-quality-reviewer, integration-reviewer, issue-verifier. Enforcement moved from command frontmatter to agent permission config (opencode ignores tools: in command frontmatter). Read-only commands route to mahou-readonly (edit: deny, destructive bash denied); planning commands to mahou-planner (writes only under .mahou/).

Skills — 11 SKILL.md guides (renamed from the old references/ collection), including design-craft, ultracode-patterns, verification-completion, receiving-review, condition-waiting, defense-in-depth.

Plugin & tool — mahou-compaction plugin injects .mahou/state.json into compaction prompts so orchestration survives context loss; describe-image tool gives non-vision models a vision fallback via Cloudflare AI Gateway.

Orchestration discipline — baseline test gate before any task (red baseline => stop), two-stage review loop (spec compliance then code quality), evidence requirements, <no_root_cause> reporting in /mahou-debug, test gate before push in /mahou-ship, review "silence is better than noise".

Model routing — removed ALL hardcoded provider/model IDs from commands. Model selection now resolves: .mahou/models.json in the current repository (task/role -> model mapping) if present, otherwise the opencode default (repo opencode.json -> global config -> session model). See "Model selection (model orchestrator)" above. The repo ships .mahou/models.json.example (local only) and never invents a provider ID.

Installer — install.sh / install.ps1 rewritten: installs commands/, agents/, skills/, plugins/, tools/, references/; cleans up the legacy command/ directory; substitutes {{MAHOU_HOME}}.

Docs — README rewritten and expanded; landing page (landing/) now lists all 15 commands with layer tags; DEPLOY.md rewritten for the Next.js landing app.