marauders-mischief 0.13.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.13.0 redesigns retrospect-agent to separate audiences cleanly. The previous design had retrospect append findings to a framework-shared ops/workflow/test-findings.md — but that file was the maintainer's personal scratchpad shipped into every user's repo. v0.13 removes that artifact entirely. Retrospect now writes a structured per-session sessions/archive/<id>/retrospect.md (with ## Wins, ## Session findings, ## Framework findings) and emits a clearly-delimited "ready to file" block in chat output formatted as GitHub Issue bodies targeted at sindreespeland/marauders-mischief. The maintainer copies the entries they want into real issues; external users can ignore the block. No automation, no telemetry. Severity is now action-oriented (must-fix-next-version / worth-fixing / monitor / idea) and findings carry structured fields (theme, autonomy-impact, cost estimate, recurrence) that promote severity automatically on repeat observation. Required-reading list refreshed for v7-v12 artifacts; v12+ sessions also audit PR state (safe to read post-archive). User repos no longer accumulate framework-improvement notes.

---

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 — PR-native core: draft PR at Stage 2.2, review/tester in PR mode, squash-merge at /mar:approve integrate, push-on-clean-round
• v0.13 — retrospect redesigned: per-session output (no shared file in user repos), structured findings with action-oriented severity + autonomy-impact + cost + recurrence, chat-output "ready to file" block for maintainer triage
• v0.14 — PR-native polish: ready-for-review at Stage 5 verdict-clear, CI-status as a hard merge-block, worktree-per-phase (multi-phase parallelism)
• v0.15 — mar update (with conflict resolution), mar status, mar doctor
• v0.16 — Codex CLI adapter, Cursor adapter
• v0.17 — mar update --auto-check (optional auto-notify on session start)

License

MIT — see LICENSE.