All project documentation lives here. The root README is the public front door; this hub is the source of truth for product intent, architecture, and contributor onboarding.
Mutiny is a behavioral fuzz-testing engine for AI agents. Install it into your agent project via an adapter:
mutiny init→ connect adapter →mutiny run→ search for policy breaks → prove on traces → minimize → save permanent regression tests.
Shipped today: Adapter #1 — OpenAI Agents SDK. Install with
pip install mutiny-ai (CLI stays mutiny; see root README /
PUBLISHING.md). Sample/demo agents are reference harnesses,
not the primary product.
Safety: Authorized testing only. Targets are local / in-process / localhost with sandboxed mock tools for demos.
| If you want… | Read |
|---|---|
| Install + try in 5 minutes | Root README |
CLI flags (init / run / test) |
CLI.md |
| Packaging / PyPI | PUBLISHING.md |
| Clean-machine bootstrap | COLD_START.md |
| Contribute / first PR | CONTRIBUTING.md · GOOD_FIRST_ISSUES.md |
| Architecture boundaries | ARCHITECTURE.md |
| How the system runs | SYSTEM_DESIGN.md |
| What’s next | ROADMAP.md |
| Why we chose X | DECISION_LOG.md (esp. ADR-017, ADR-018) |
| Support / Windows / security | SUPPORT.md · SECURITY.md |
| Document | Owns | Does not own |
|---|---|---|
| PRD.md | Product intent, users, requirements, non-goals | Algorithms, package layout, day-by-day tasks |
| ARCHITECTURE.md | Principles, layering, package ownership, constraints | Product roadmap, competitor detail |
| SYSTEM_DESIGN.md | Lifecycles, data contracts, flows, diagrams | Milestone scheduling, demo narration |
| IMPLEMENTATION_PLAN.md | Milestones, DoD, sequencing | Product vision, long-term roadmap |
| DEMO_SCRIPT.md | Live demo scripts, backup, Q&A | System internals |
| COLD_START.md | Clean-machine bootstrap + smoke gate | Product narrative |
| GOOD_FIRST_ISSUES.md | Catalog of small contributor tasks | Execution ownership of Core redesigns |
| CLI.md | mutiny commands and flags from --help |
Hosted UI walkthrough |
| ../CHANGELOG.md | Unreleased + release notes | Live demo narration |
| DEVPOST.md | Short public pitch copy | Live demo choreography |
| COMPETITOR_ANALYSIS.md | Competitive landscape (claims freeze) | Mutiny feature specs |
| DECISION_LOG.md | Architecture Decision Records | Ongoing task lists |
| ROADMAP.md | Phased future work | Near-term execution detail |
| DESIGN.md | Pointer to Hosted visual canon | Product requirements |
Community files at repo root: CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, SUPPORT, LICENSE.
- Product intent → PRD
- Hard engineering constraints / boundaries → ARCHITECTURE
- Behavioral contracts (how the system works) → SYSTEM_DESIGN
- What to build next / DoD → IMPLEMENTATION_PLAN
- Why we chose X → DECISION_LOG
If docs disagree, fix the docs in that order—do not silently pick a convenient interpretation in code.
Install claims: Prefer the root README. Primary path is pip install mutiny-ai (CLI stays mutiny). Never recommend bare pip install mutiny / mutiny-sdk (those names are taken by other projects). Git/source install is optional — see PUBLISHING.md.
- Root README (What / Why / Install / Try)
- PRD.md (thesis + non-goals)
- ARCHITECTURE.md (boundaries)
- SYSTEM_DESIGN.md (how it runs)
- DECISION_LOG.md (ADR-017 customer-project primary; ADR-018 adapter-first)
- ROADMAP.md / GOOD_FIRST_ISSUES.md as needed
Customer agent project
↑
OpenAI Agents SDK Adapter ← Adapter #1 (shipped)
↑
Adapter Layer ← future: LangGraph, CrewAI, PydanticAI, AutoGen, HTTP, …
↑
Mutiny Core ← behavioral fuzz-testing engine
↑
CLI (mutiny init / run / test) ← primary
Hosted API + UI ← secondary
Sample / demo agent ← reference harness
Screenshots / demo assets: docs/assets/ — live Hosted PNGs + optional GIF; SVG storyboard remains as a static diagram. See assets/README.md. Release notes: CHANGELOG.md.