Metadata-Version: 2.4
Name: marauders-mischief
Version: 0.13.3
Summary: An AI-native dev harness. Solemnly swear you're up to no good.
Project-URL: Homepage, https://github.com/sindreespeland/marauders-mischief
Project-URL: Repository, https://github.com/sindreespeland/marauders-mischief
Project-URL: Issues, https://github.com/sindreespeland/marauders-mischief/issues
Author-email: Sindre Espeland <sindre.espeland2001@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agents,ai,claude-code,dev-tools,harness,workflow
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.12
Requires-Dist: jinja2>=3.1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.12.0
Description-Content-Type: text/markdown

# marauders-mischief

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

A workflow for [Claude Code](https://claude.com/claude-code) that makes a coding agent behave like an engineering team instead of a single overcaffeinated junior.

## Why

If you've used a coding agent for more than half an hour, you've watched it do at least one of these:

- Delete the failing test to make the suite green.
- Confidently report "feature shipped" when the feature doesn't work.
- Refactor while you asked it to fix a bug, breaking three other things on the way.
- Lose its mind around the second hour of a long task and forget what you asked for.
- Run overnight in autonomous mode and commit garbage to `main` while you slept.

Agents are very good at writing code. They are very bad at the parts of engineering that aren't writing code: planning, peer review, knowing when to stop, knowing when to ask. Most setups paper over that gap by just letting it happen and hoping for the best.

`mar` is the setup that doesn't. It splits each task into the stages a real team uses (research, plan, build, test, review, integrate), runs each stage in a fresh-context sub-agent that hasn't been defending its own previous choices, and enforces the boundaries mechanically. Not by asking nicely.

## What it does

For every task you give it:

1. **Research** — pulls together what you need to know about the problem (the codebase, the libraries, the prior art). Surfaces options; doesn't decide.
2. **Plan** — an author writes the plan. A skeptic in a fresh context tries to break it. They reconcile, or you do.
3. **Execute** — small steps, fresh agent per step, no accumulated context drift.
4. **Test** — multiple test kinds in parallel: unit, eval, agent-flow, browser, perf. The orchestrator picks which apply to what changed.
5. **Refine** — when something fails, the fix goes in the code. Not in the test. A PreToolUse hook physically blocks the agent from writing to `tests/`, fixtures, snapshots, or eval data.
6. **Simplify** — a cleanup pass. Same author/skeptic pattern. Reverts itself if cleanup regresses anything.
7. **Verify** — a structured pre-PR adherence check. Classifies failures by who should fix them (refine / replan / user) instead of bouncing everything back to refine.
8. **Review + Tester** — fresh-context PR review (inline comments on the actual PR) and functional validation (does the feature work for a user?) — in parallel.
9. **Integrate** — squash merge with the commit story you approved in step 2.

Every stage runs as a fresh sub-agent. None of them inherit the running history. The only thing that persists between stages is **files**: `plan.md`, `test-report.md`, `verification.md`. Context-as-files, not context-as-tokens. The plan, not the chat log, is the source of truth.

## What it stops

| Failure mode | What stops it |
|---|---|
| Agent weakens a failing test instead of fixing the code | `tests/`, fixtures, snapshots, eval data are write-blocked during refine via the scope hook |
| A refine cycle introduces new failures while patching old ones | Each round is checkpointed; new failures auto-revert and escalate via the `refine-regression-wall` safeguard |
| Plan and shipped reality drift apart | Verify runs 5 mechanical pre-checks (diff vs scope, unresolved questions, unchecked manual steps, deviations triage, plan-quality) before reasoning, with structured evidence required for every adherence claim |
| Long agents lose track of state | Each build step is a fresh sub-agent reading the previous step's handoff file |
| Autonomous mode ships broken work silently | 15+ always-on safeguards pause autonomous sessions on every known silent-failure mode |
| Agent self-grades and rubber-stamps its own work | Author/skeptic split at design-time stages (research, plan, simplify); fresh-context review at Stage 5 |
| Long-lived branches diverge and produce merge nightmares | One phase, one branch, one PR. Squash-merged at integrate. Phases run sequentially |

## Autonomy modes

Pick how much you want to be in the loop:

- **`interactive`** — every gate pauses for your approval.
- **`normal`** — gates pause for important things; routine stuff auto-passes.
- **`streamlined`** — auto-passes if no issues; gates only when something needs you.
- **`autonomous`** — runs end-to-end. You provide no input after `/mar:session-start` until the session finishes or a safeguard pauses it.

All four modes use the same safeguards. Autonomous is allowed to be unattended because the safeguards make it safe to be unattended, not because nobody's looking.

## Install

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

Prereqs:
- [Claude Code](https://claude.com/claude-code) installed
- [`gh`](https://cli.github.com/) authenticated for your repo (`gh auth login`)

## Quickstart

```bash
mkdir my-project && cd my-project
git init
gh repo create --private --source=. --remote=origin  # or use an existing repo

mar init

# Fill in the two files mar wants you to fill in:
#   .brain/CONTEXT.md  — what you're building, in plain language
#   .brain/STATE.md    — where you are right now
```

Then open Claude Code and run a session:

```
/mar:session-start "fix the auth token refresh bug"
# picker: size (XS/S/M/L/XL), kind, guidance, autonomy

/mar:plan
# → research, plan, plan-skeptic review

/mar:approve plan

/mar:ship
# → branch, execute, test, refine, simplify, verify, review + tester, draft PR

/mar:approve integrate
# → gh pr ready + gh pr merge --squash
```

For a tiny task (typo, isolated bug) the loop fits in 5-15 minutes. For a multi-day feature you'll plan it as L or XL and run multiple phases sequentially, each one its own PR.

## Slash commands

| Command | What it does |
|---|---|
| `/mar:session-start` | Start a session (size / kind / guidance / autonomy picker) |
| `/mar:plan` | Run the current planning sub-stage |
| `/mar:ship` | The build loop: branch → execute → test → refine → simplify → verify → review + tester → draft PR |
| `/mar:integrate` | Compose the commit story; pause for approval |
| `/mar:approve <gate>` | Pass a gate (research / meta-plan / plan / integrate / …) |
| `/mar:iterate <gate> "<note>"` | Refine the gate's output without losing position |
| `/mar:revise <target> "<note>"` | Back up to a prior stage with a note |
| `/mar:redirect "<direction>"` | Pivot the session entirely |
| `/mar:reject <gate>` | Discard the gate's artifact and back up |
| `/mar:status` | Where am I? |
| `/mar:session-list` | All active and archived sessions |
| `/mar:retrospect <id>` | Post-archive audit; surfaces framework feedback for the maintainer |

There are more (idea capture, session resume, between-session machinery). See `.claude/commands/mar/` after install, or the full spec at `ops/workflow/README.md`.

## What `mar init` writes

```
your-project/
├── CLAUDE.md                   Project-level context. You own it.
├── .brain/                     Curated context. You own it.
│   ├── CONTEXT.md              What you're building.
│   ├── STATE.md                Current state of play.
│   ├── STACK.md                Stack decisions.
│   ├── DECISIONS.md            Why you made the calls you made.
│   └── RISKS.md                What could go wrong.
├── .claude/
│   ├── agents/                 ~30 sub-agents (research, plan, execute, review, …)
│   ├── commands/mar/           20+ slash commands (/mar:*)
│   └── settings.json           Hooks + permissions. mar manages its own keys.
├── ops/workflow/               Spec, scripts, templates
└── .mm/lockfile.json           SHA256 of every framework file. `mar update` reads this.
```

Every shipped file falls into one of three classes:

- **framework** — owned by mar. Overwritten on `mar update`. Drift is detected if you edit.
- **scaffolded** — created once at init. Yours forever after. mar never touches.
- **merged** — mar owns specific keys; you own everything else in the same file (`.claude/settings.json`, `.gitignore`).

This split is what lets `mar update` upgrade the framework without clobbering your project.

## Development

```bash
git clone git@github.com:sindreespeland/marauders-mischief.git
cd marauders-mischief
uv sync --dev

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
```

## Status

Pre-release. The build loop is hardened end-to-end (v0.5 through v0.13.3). The PR-native flow is live (v0.12). Smoke-test against a throwaway repo before trusting it on real work.

Each minor release hardens one stage. See the roadmap below or the GitHub Releases page for what landed when.

## Roadmap

Shipped:

- **v0.5** — phase research: hypothesis-driven, 5-section structured output, optional skeptic
- **v0.6** — phase plan: author + skeptic at per-phase grain, AI-aware checks
- **v0.7** — execute step-decomposition: bounded context per build step
- **v0.8** — multi-kind testing: strategist + parallel runners (unit/eval/agent-flow/browser/perf), target-aware refine
- **v0.9** — simplify hardened: dynamic conventions, targeted re-test, revert on regression
- **v0.10** — refine hardened: protected surfaces (tests/fixtures/snapshots/evals), checkpoint + revert across all four refine loops
- **v0.11** — verify hardened: route-based dispatch (refine/replan/user), mechanical pre-checks, structured evidence
- **v0.12** — PR-native flow: draft PR at Stage 2.2, review/tester in PR mode, squash-merge at `/mar:approve integrate`
- **v0.13** — retrospect redesigned: per-session output, maintainer feedback via chat, no framework-shared file in user repos
- **v0.13.1** — first-run fix: `/mar:ship` auto-creates the phase branch
- **v0.13.2** — `CLAUDE.md` template brought up to date (session awareness, files-as-source-of-truth table, safeguards list, post-v12 repo map)
- **v0.13.3** — critical fix: `.claude/settings.json` hook shape corrected (was being rejected by Claude Code, silently disabling the scope hook)

Next:

- **v0.14** — PR-native polish: ready-for-review at Stage 5 verdict-clear, CI as 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)

## Contributing

Issues and PRs welcome at [github.com/sindreespeland/marauders-mischief](https://github.com/sindreespeland/marauders-mischief/issues). Run `/mar:retrospect` after a session if you find friction; the chat output formats framework findings as paste-ready issue bodies.

## License

MIT — see [LICENSE](LICENSE).
