Reference
API Reference
Complete reference for Planwright's MCP tools, permissions, lane state machine, audit events, and common errors.
On this page
MCP Tools Reference
All tools are prefixed with planwright_ and accessed via the MCP protocol at mcp.planwright.tools/mcp.
Session Setup
planwright_set_repo
Set the active project for this session. Required before any other tool call.
Parameters
planwright_list_workspaces
List workspaces you have access to with role and project counts.
planwright_list_projects
List projects you have access to with their IDs and linked GitHub repos.
Parameters
Objectives
planwright_create_objective
Create a new objective in the backlog.
Parameters
planwright_list_objectives
List objectives in a lane. Defaults to 'scheduled'.
Parameters
planwright_get_objective
Fetch full objective details including agent run history.
Parameters
planwright_update_objective
Update objective metadata (not lane — use transitions for that).
Parameters
planwright_schedule_objective
Move a backlog objective to scheduled lane. Human only.
Parameters
Agent Execution
planwright_claim_objective
Claim a scheduled objective and start an agent run.
Parameters
planwright_check_alignment
Verify proposed work aligns with claimed objective before coding.
Parameters
planwright_append_plan
Post the agent's decomposition plan to the run log.
Parameters
planwright_record_diff
Record diff summary and test results for the agent run.
Parameters
planwright_request_acceptance
Move objective to acceptance lane for human review.
Parameters
planwright_append_note
Add a progress note to the agent run log.
Parameters
Initiatives
planwright_list_initiatives
List initiatives for the current workspace.
planwright_create_initiative
Create a new initiative.
Parameters
planwright_update_initiative
Update an initiative's metadata.
Parameters
planwright_delete_initiative
Delete an initiative. Objectives are preserved with cleared assignment.
Parameters
Context Files
planwright_list_context_files
List all context files for the current project.
planwright_get_context_file
Read a specific context file by filename.
Parameters
planwright_push_context_file
Create or update a context file.
Parameters
Clarity & Quality
planwright_flag_clarity
Flag an objective as having ambiguous requirements.
Parameters
planwright_list_unenriched
List objectives/initiatives missing intentSummary.
planwright_list_unclassified
List objectives missing strategic_focus.
Utilities
planwright_get_board_url
Get the board URL for the current project.
Parameters
planwright_list_my_bugs
List bugs for this project.
Parameters
planwright_get_doc_suggestions
Get pending documentation gap suggestions.
Permissions & Roles
| Role | Permissions |
|---|---|
| owner | Full access. Manage workspace settings, billing, members. Transfer ownership. |
| admin | Manage members, projects. Cannot transfer ownership or delete workspace. |
| member | Create/edit objectives, manage initiatives. Cannot manage workspace settings. |
| viewer | Read-only access to board and objectives. |
| service token | Scoped to one project. Can claim/execute work. Cannot modify workspace. |
Lanes & Transitions
Objectives move through lanes via a strict state machine. Agents cannot directly mutate lanes — they request transitions via MCP tools, and the server validates and records each change.
| Lane | Description | Valid Transitions |
|---|---|---|
| backlog | Objectives not yet ready for agent pickup. Human-managed. | scheduled (human) |
| scheduled | Ready for agent pickup. Agents claim from here. | in_progress (agent claim) |
| in_progress | Active agent work. One agent run at a time. | acceptance (agent request), scheduled (clarity flag) |
| acceptance | Awaiting human review. | done (human accept), scheduled (human reject) |
| done | Completed and accepted. | archived (auto after retention) |
Audit Events
Every MCP tool call produces a hash-chained, ECDSA P-256-signed audit record. These records are immutable and satisfy SOC 2 Trust Services Criteria for AI-generated code.
| Event Type | Description |
|---|---|
| objective.created | New objective added to backlog |
| objective.updated | Objective metadata changed |
| objective.lane_changed | Objective moved between lanes |
| objective.clarity_flagged | Agent flagged ambiguous requirements |
| agent_run.started | Agent claimed objective |
| agent_run.plan_appended | Agent posted decomposition plan |
| agent_run.diff_recorded | Agent recorded code changes |
| agent_run.note_appended | Agent added progress note |
| agent_run.completed | Agent requested acceptance |
| acceptance.signed | Human approved the work |
| acceptance.rejected | Human rejected the work |
| initiative.created | New initiative created |
| initiative.updated | Initiative metadata changed |
| initiative.deleted | Initiative removed |
Error Codes
No project selected
Call planwright_set_repo first with your githubRepo or projectId
Invalid transition
Check the lane state machine. You may be trying an invalid lane change.
Actor type 'agent' cannot transition
This transition requires human action (e.g., scheduling, accepting)
Objective not found
Verify the objectiveId exists and you have access to the project
Agent run not found
Verify the agentRunId exists and belongs to the current objective
strategic_focus required
Provide a strategic_focus object with primary bucket and area
commitSha required
In direct mode, pass the commit SHA to record_diff
Strategic Focus Taxonomy
Every objective requires a strategic_focus classification. Use the primary bucket and area that best describes the objective's intent.
BUILD
- PRODUCT_CAPABILITY — User-facing features
- PLATFORM_INFRASTRUCTURE — Internal systems, tooling
GROW
- REVENUE_ENABLEMENT — Billing, upsells, pricing
- GO_TO_MARKET — Launch, marketing, positioning
- MARKET_POSITIONING — Competitive, branding
TRUST
- QUALITY_RISK_REDUCTION — Testing, reliability
- COMPLIANCE_GOVERNANCE — Security, audits
- CUSTOMER_ENABLEMENT — Docs, onboarding
SCALE
- ECOSYSTEM_INTEGRATIONS — Third-party connections
- ORGANIZATIONAL_SCALE — Team processes, hiring