Metadata-Version: 2.4
Name: marauders-mischief
Version: 0.12.0
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 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

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

## Quickstart

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

```bash
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](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:

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

Run tests:

```bash
uv run pytest
uv run ruff check src tests
```

Try `mar init` against a throwaway directory:

```bash
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](LICENSE).
