marauders-mischief 0.12.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.12.0 lands the PR-native flow. Every phase = one PR. The orchestrator opens a draft PR at Stage 2.2 of /mar:ship (after build steps, before tests run) via create-phase-pr.sh; the PR body is a derived view of plan.md (regenerated on every /mar:iterate plan and synced via gh pr edit). At Stage 5, review-agent and tester-agent switch to mode: pr — they write to session .md files as the canonical source of truth AND post a human-visible mirror to the PR (inline gh pr review for review, summary gh pr comment for tester). PR comments are one-way: agents do not read them back; refine reads only from session sources. The squash merge moves to /mar:approve integrate, which pre-checks mergeStateStatus == CLEAN, marks the PR ready, and runs gh pr merge --squash with integrate-agent's composed commit message. integrate-agent no longer pushes, creates, or merges — it composes the commit story only. Autonomous mode auto-runs the approve step at the integrate stage. New always-on safeguard: gh-pr-failure hit fires on any non-zero gh PR command in every mode including autonomous.

---

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 — 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.14 — mar update (with conflict resolution), mar status, mar doctor
• v0.15 — Codex CLI adapter, Cursor adapter
• v0.16 — mar update --auto-check (optional auto-notify on session start)

License

MIT — see LICENSE.