Getting Started
Core Concepts
The Planwright hierarchy from top to bottom:
Workspace → Project → Objective → Initiative → Strategic Focus
Workspace
Top levelMaps to a single GitHub organization.
The workspace is the team boundary. It owns the billing relationship, the member list, the audit chain signing key, and all projects inside it. It also publishes a live public changelog of completed objectives — updated automatically as work ships, with no manual maintenance required. One GitHub org = one workspace. Cross-org workspaces are planned for a future release.
See: Release Notes
Project
Under a workspaceThe planning board for a product area or team.
A project can link to one or more GitHub repositories, or stand alone with no repo connection at all. A single repo can serve multiple projects — useful for monorepos where different teams own different services. The project owns the Objective board, the lane configuration, the initiative history, and the context file library — project-level documents that agents read before every objective run to understand architecture decisions, conventions, and constraints the codebase doesn't make explicit.
See: Context Files
Objective
The atomic unitA clear, agent-executable outcome. The thing agents execute against.
Objectives are owned by humans — written solo or co-authored with an agent through collaborative brainstorming of intent and outcomes. They stay in the Backlog until scheduled. Once scheduled, an agent claims the objective, posts a decomposition plan, makes changes, and requests human review. Objectives never have subtasks, checklists, or breakdowns — that work belongs inside the agent run. An objective moves through lanes: Backlog → Scheduled → In Progress → Acceptance → Done.
Initiative
Groups objectivesA named theme and version container that groups related objectives.
Initiatives give the board strategic shape. An initiative might be "Q3 Auth Overhaul" or "Docs Site." Objectives are optional members of an initiative — many useful objectives stand alone. When an initiative is released, Planwright writes a signed release record to the audit chain and generates a release notes artifact from its accepted objectives. Initiatives are optional — you can use Planwright without them for continuous delivery workflows.
Strategic Focus
ClassificationThe four-bucket taxonomy that classifies every objective.
Every objective — including ones proposed by agents — must declare a strategic bucket before it can be claimed. This keeps the portfolio aligned to what the team is actually trying to accomplish.
Anatomy of an Objective
Every field on an Objective has a job to do. In an agentic workflow each field is load-bearing — not optional metadata. Here is what each one is and why it matters when a coding agent is the one executing the work.
The agent's primary directive. It should be specific enough that a senior engineer — or a coding agent — could start without asking a clarifying question. Vague titles force agents to make scope assumptions that compound into rejection cycles later.
Agents don't accumulate ambient context the way human teammates do over months of standups and Slack. The description is the complete briefing document. Everything the agent needs to understand scope, motivation, and guardrails must be stated explicitly — it can't ask the PM at standup.
The most critical field for agentic execution. It defines the agent's verifiable target and the human reviewer's checklist at the acceptance gate. Without it, agents guess at completeness and reviewers have no objective basis for rejection. Specific criteria make the acceptance decision binary rather than subjective.
When multiple objectives are scheduled, agents use priority to determine claim order — replacing sprint planning as the scheduling signal. In multi-agent setups, high-priority work is claimed before low-priority work with no human scheduling intervention required.
User-provider or inferred by agent. Required before an objective can be claimed. Forces every piece of work — including agent-proposed objectives — to declare strategic intent before execution begins. Prevents agents from pulling the portfolio toward interesting-but-unstrategic scope. Low confidence scores surface for human review rather than blocking progress.
Agents executing one objective often discover a natural cluster of follow-on work. They can propose a new initiative and attach objectives to it, surfacing emergent scope for the human to evaluate and schedule as a set — rather than as disconnected one-offs.
Business value helps agents calibrate relative importance beyond the priority number. Complexity/risk informs execution approach: a high-risk objective warrants smaller commits, more explicit plan steps, and more verification checkpoints before touching critical paths.
For guidance on writing effective Objectives — including what to put in the Description and Acceptance Criteria — see Best Practices.
Objective lane flow
Agents can move an objective from Scheduled to In Progress (by claiming it) and from In Progress to Acceptance (by requesting review). Only humans can move an objective from Acceptance to Done. Agents can never self-approve.
Projects without a GitHub repo
A GitHub connection is optional. You can create a project with no linked repository — useful for early-stage planning before a repo exists, non-code initiatives like go-to-market or documentation work, or teams whose code lives on GitLab, Bitbucket, or another VCS.
Repo-less projects work identically to linked ones. Agents connect by project ID instead of repo slug. The full objective lifecycle — Backlog, Scheduled, In Progress, Acceptance, Done — is available, and the audit chain records every state change the same way. The only thing that changes is how agents identify the project when calling the MCP server:
# GitHub-linked project
planwright_set_repo(githubRepo: "your-org/your-repo")
# Repo-less project
planwright_set_repo(projectId: "your-project-uuid")
You can find the project ID on the project settings page. Commit-to-objective tracing and automatic PR linking require a GitHub repo — those features are simply not applicable for repo-less projects and do not affect any other functionality.