# Planwright

**Control plane for autonomous software labor.**

Planwright is the objective-native planning board for agent-led software development. Humans define outcomes at the Objective layer; coding agents (Claude Code, Cursor, Codex, and others) claim work, decompose tasks, execute, and report back via native MCP—with every state change captured in a hash-chained, Ed25519-signed audit trail.

[![Documentation](https://img.shields.io/badge/docs-planwright.tools-blue)](https://planwright.tools/docs)
[![MCP](https://img.shields.io/badge/MCP-compatible-green)](https://modelcontextprotocol.io)

---

## Quick Start

### Claude Code (recommended)

```bash
claude mcp add planwright https://mcp.planwright.tools/mcp
```

Your browser opens for GitHub login. That's it.

### Other Agents

See the [full agent setup guides](https://planwright.tools/docs/agents) for Cursor, Codex, Claude Desktop, and generic MCP clients.

---

## How It Works

```
┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   PLANNING (Humans)                 EXECUTION (Agents)          │
│                                                                 │
│   "Add OAuth login" ───────┐                                    │
│                            │                                    │
│   create_objective() ──────┤                                    │
│                            ▼                                    │
│                     ┌──────────────┐                            │
│                     │   BACKLOG    │                            │
│                     └──────┬───────┘                            │
│                            │                                    │
│   schedule_objective() ────┤                                    │
│                            ▼                                    │
│                     ┌──────────────┐                            │
│                     │  SCHEDULED   │◀── list_objectives()       │
│                     └──────┬───────┘                            │
│                            │                                    │
│                            │── claim_objective() ──────────────▶│
│                            ▼                                    │
│                     ┌──────────────┐                            │
│                     │ IN PROGRESS  │◀── append_plan()           │
│                     │              │◀── record_diff()           │
│                     └──────┬───────┘                            │
│                            │                                    │
│                            │── request_acceptance() ───────────▶│
│                            ▼                                    │
│                     ┌──────────────┐                            │
│                     │  ACCEPTANCE  │                            │
│                     └──────┬───────┘                            │
│                            │                                    │
│   Human reviews ───────────┤                                    │
│   (web UI)                 │                                    │
│                     ┌──────┴───────┐                            │
│                     │     DONE     │                            │
│                     └──────────────┘                            │
│                                                                 │
│   Every step: hash-chained + Ed25519 signed audit trail         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## Key Features

**Objective-Native, Not Task-Based**
No story points. No velocity charts. No capacity planning. Agents decompose objectives into tasks themselves—you manage outcomes, not effort.

**Immutable Audit Trail**
Every state change produces a hash-chained, Ed25519-signed audit record. Know exactly what the agent planned, what it changed, and when.

**Native MCP Integration**
Agents connect via the Model Context Protocol—no custom API clients needed. Works with any MCP-compatible agent.

**Multi-Agent Support**
Claude Code, Cursor, Codex, Factory, Amp—if it speaks MCP, it can work from your Planwright board.

**Context Files**
Push CLAUDE.md, architecture docs, and specs to Planwright. Agents read them before starting work.

---

## Documentation

- [Getting Started](https://planwright.tools/docs/getting-started)
- [Agent Setup Guides](https://planwright.tools/docs/agents)
- [Writing Better Objectives](https://planwright.tools/docs/best-practices)
- [API Reference](https://planwright.tools/docs/reference)

---

## Examples

See the [`examples/`](./examples) directory for:

- Sample `CLAUDE.md` files for different project types
- Example objective structures
- Context file templates

---

## MCP Server

Planwright's MCP server is hosted and managed—no self-hosting required.

| Endpoint | Protocol |
|----------|----------|
| `https://mcp.planwright.tools/mcp` | Streamable HTTP |

Authentication is handled via OAuth 2.1 with Dynamic Client Registration (RFC 7591). Your agent opens a browser for GitHub login on first connection.

For CI/CD and headless environments, generate a static token in **Settings → MCP Tokens**.

---

## Available Tools

Planwright exposes 30 MCP tools for agent orchestration:

### Setup & Context
| Tool | Description |
|------|-------------|
| `planwright_set_repo` | Set active project for the session (by GitHub repo or project ID) |
| `planwright_list_workspaces` | List workspaces you have access to |
| `planwright_list_projects` | List projects with IDs and linked GitHub repos |
| `planwright_list_context_files` | List CLAUDE.md, specs, architecture docs for the project |
| `planwright_get_context_file` | Read a specific context file |
| `planwright_push_context_file` | Upload or update a context file |
| `planwright_get_doc_suggestions` | Get pending documentation gap suggestions |
| `planwright_dismiss_doc_suggestion` | Dismiss a doc suggestion |
| `planwright_get_board_url` | Get the Planwright board URL |

### Initiatives
| Tool | Description |
|------|-------------|
| `planwright_list_initiatives` | List initiatives (milestones) for the workspace |
| `planwright_create_initiative` | Create a new initiative |
| `planwright_update_initiative` | Update initiative metadata |
| `planwright_delete_initiative` | Delete an initiative |

### Objectives
| Tool | Description |
|------|-------------|
| `planwright_list_objectives` | List objectives by lane (backlog, scheduled, in_progress, acceptance, done) |
| `planwright_get_objective` | Get full objective details including agent run history |
| `planwright_create_objective` | Create a new objective with acceptance criteria |
| `planwright_update_objective` | Update objective metadata |
| `planwright_schedule_objective` | Move objective from backlog to scheduled |

### Agent Workflow
| Tool | Description |
|------|-------------|
| `planwright_claim_objective` | Claim a scheduled objective and start an agent run |
| `planwright_append_plan` | Post the agent's decomposition plan |
| `planwright_check_alignment` | Verify work aligns with claimed objective (drift detection) |
| `planwright_record_diff` | Record diff summary and test results |
| `planwright_submit_test_run` | Submit acceptance criteria verification results |
| `planwright_request_acceptance` | Move objective to acceptance lane for human review |
| `planwright_append_note` | Record task completion in the agent run log |
| `planwright_flag_clarity` | Flag objective as having clarity concerns |
| `planwright_override_clarity` | Human override for clarity flags |

### Enrichment & Classification
| Tool | Description |
|------|-------------|
| `planwright_list_unenriched` | List objectives/initiatives missing intent summaries |
| `planwright_list_unclassified` | List objectives missing strategic classification |
| `planwright_list_my_bugs` | List bugs for this project |

---

## Support

- [Documentation](https://planwright.tools/docs)
- [GitHub Discussions](https://github.com/Planwright/planwright/discussions)
- [Report a Bug](https://github.com/Planwright/planwright/issues/new?template=bug_report.md)

---

## License

Planwright is a commercial product. The MCP integration examples in this repository are provided under the MIT License.

See [LICENSE](./LICENSE) for details.