Content
# 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.
[](https://planwright.tools/docs)
[](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.
