marauders-mischief 0.11.0

An AI-native dev harness. Solemnly swear you're up to no good.

marauders-mischief

An AI-native dev harness. Solemnly swear you're up to no good.

A versioned, harness-agnostic development framework for AI-native software engineering. Size-adaptive sessions, multi-agent quality gates, persistent context across sessions.

Built for Claude Code today; designed to support Codex CLI and Cursor in future releases.

Status: Pre-release. v0.11.0 hardens verify-agent. Verify is the pre-PR adherence gate — it confirms the build loop produced what the plan promised. Previously every verify-fail bounced to refine-agent; under v0.10's protected surfaces, some failures (a declared test that was never built, a scope violation, an unchecked manual step) can't actually be fixed by refine. v0.11 has verify classify each failure with a route: refine (missing production code, existing path), replan (scope drift, declared test not built, plan unverifiable — escalate immediately), or user (unresolved [QUESTION] in autonomous mode, unchecked manual step — needs human action). The orchestrator dispatches by route: pure-refine sets bounce to refine as before; any non-refine route fires the new verify-escalation hit safeguard instead of burning a refine cycle. Verify also runs 5 mechanical pre-checks via Bash before any reasoning (diff vs scope, [QUESTION] count, manual-step boxes, deviations triage, plan-quality preconditions) and requires structured-format evidence for every adherence claim — prose-only "looks good" no longer counts. Effort medium → high.

---

Install

pipx install marauders-mischief
# or
uv tool install marauders-mischief

Quickstart

mkdir my-new-project && cd my-new-project
git init
mar init

This scaffolds the harness into your repo:

my-new-project/
├── CLAUDE.md                        Project-level context (you own)
├── .brain/                          Curated, distilled context (you own)
│   ├── CONTEXT.md
│   ├── STATE.md
│   ├── STACK.md
│   ├── DECISIONS.md
│   └── RISKS.md
├── .claude/
│   ├── agents/                      12 subagents (research, plan, execute, ...)
│   ├── commands/mar/                19 slash commands (/mar:*)
│   └── settings.json                Hooks + permissions (mar manages its keys)
├── ops/
│   ├── memory/                      Knowledge capture pipeline (uv-managed)
│   ├── workflow/                    Session/phase/stage spec + scripts
│   └── ideas/                       Idea lifecycle machinery
└── .mm/
    ├── version                      Installed mar version
    └── lockfile.json                SHA256 of every framework file

Then:

cd ops/memory && uv sync   # one-time: set up memory pipeline deps

Fill in .brain/CONTEXT.md and .brain/STATE.md, and you're ready to run /mar:session-start in Claude Code.

Commands

Command	Purpose
mar init	Scaffold the harness into the current directory
mar update	Pull latest framework version and apply updates (v0.2)
mar status	Show installed version and local drift (v0.2)
mar doctor	Verify install integrity (v0.2)

Flags:

• --target <adapter> — currently claude (default). codex and cursor adapters land in future releases.
• --force — overwrite scaffolded files (.brain/*, CLAUDE.md) that already exist.
• --project-name <name> — substituted into Jinja-rendered templates. Defaults to the current directory name.

How it works

File classes

Every file shipped by mar belongs to one of three classes (see docs/file-classes.md):

Class	Behavior
framework	Owned by mar. Overwritten on mar update. Conflict-detected if you edit locally.
scaffolded	Created once at init. You own thereafter; mar never touches.
merged	mar owns specific keys; you own everything else in the same file. Update reconciles only mar's keys.

This split is what lets mar update upgrade the framework without clobbering your project's content.

Adapter layer

The mar core is harness-agnostic in spirit. Each harness (Claude Code, Codex CLI, Cursor) gets a small adapter that:

• Validates which paths the framework can write to
• Provides merge strategies for files that mix framework wiring with user config (e.g., .claude/settings.json for Claude Code)

Today only the Claude Code adapter is implemented. Adding a new adapter means subclassing Adapter and MergeStrategy.

The workflow framework

mar's centerpiece is a size-adaptive session loop:

• XS edits skip the framework entirely
• S/M sessions collapse to a single phase
• L/XL sessions get an explicit meta-plan with human approval gates between phases

Each phase runs through stages: research → plan → execute → test → refine → simplify → verify → review + tester → integrate. A PreToolUse scope hook prevents agents from editing outside their declared scope.

Full spec lives in your repo at ops/workflow/README.md after mar init.

Slash commands

After mar init, these are available in Claude Code:

Command	What it does
/mar:session-start	Start a new session (size/guidance/autonomy picker)
/mar:plan	Run research + planning for the current sub-stage
/mar:ship	Run execute → test → refine → simplify → verify → review + tester
/mar:integrate	Compose commit story, propose .brain/ writebacks
/mar:approve <gate>	Pass a gate
/mar:iterate <gate> "<note>"	Refine in place with new direction
/mar:replan	Discard current plan and re-plan from scratch
/mar:status	Current session status
/mar:session-list	All active and recently archived sessions
/mar:idea-new	Capture an incubating idea

Full reference: see .claude/commands/mar/*.md after install.

Development

Clone and set up:

git clone [e-mail]:sindreespeland/marauders-mischief.git
cd marauders-mischief
uv sync --dev

Run tests:

uv run pytest
uv run ruff check src tests

Try mar init against a throwaway directory:

mkdir /tmp/test-install && cd /tmp/test-install
uv run --project ~/repos/marauders-mischief mar init

Roadmap

• v0.1 — mar init, Claude Code adapter, the workflow framework (v2)
• v0.2 — multi-role meta-research (workflow v3): parallel role-agents at Stage 2a with a mid-research briefing gate
• v0.3 — meta-planning v4: strategist / author / skeptic with named decomposition strategies + 4-option meta-plan gate (approve / iterate / revise / redirect)
• v0.4 — single-repo gh issue creation: Stage 2b creates real GitHub issues against origin; service-organized layout removed
• v0.5 — phase research v2: hypothesis-driven, 5-section structured output, optional skeptic for L/XL phases, 4-option phase research gate
• v0.6 — phase plan v6: author + skeptic at per-phase grain; 10-entry implementation strategy catalogue (incl. 3 AI-native); 3 optional plan sections for AI/agentic phases; 5-option phase plan gate
• v0.7 — execute step-decomposition: plan declares build steps; fresh-context execute-step-agent per step; bounded context for the doing stage
• v0.8 — multi-kind testing: test-strategist + per-kind runners (unit / eval / agent-flow / browser / perf) dispatched in parallel; target-aware refine
• v0.9 — simplify hardened: author+skeptic, dynamic conventions from CLAUDE.md, targeted re-test, revert-on-regression
• v0.10 — refine hardened: protected surfaces (tests/fixtures/snapshots/evals) + checkpoint-and-revert on regression across all four refine loops
• v0.11 — verify hardened: route-based failure classification (refine/replan/user), mechanical pre-checks, structured evidence
• v0.12 — mar update (with conflict resolution), mar status, mar doctor
• v0.13 — Codex CLI adapter, Cursor adapter
• v0.14 — mar update --auto-check (optional auto-notify on session start)

License

MIT — see LICENSE.