Getting Started

Your First Project

An end-to-end walkthrough — from GitHub connection to a coding agent executing your first objective and you accepting the result.

1. 1

   Install the GitHub App

   During sign-up you'll be prompted to install the Planwright GitHub App on your organization. If you skipped it, go to Settings → GitHub and click Install. The app needs read access to repository metadata and write access to receive webhooks — it never reads code or writes to your repos.

2. 2

   Create a project

   From your workspace, click New Project. Name it after the thing you're building — not a team name. Link the GitHub repository (or repositories) that hold the code. Planwright uses the repo link to associate agent commits with objectives via commit trailers.

   Monorepo? Link the same repo to multiple projects — one per product area or team.

3. 3

   Write your first objective

   Click New Objective on the board. Write an outcome, not a task. The test: could a senior engineer read this and start without asking a clarifying question? Add acceptance criteria — a bulleted list of conditions that must be true for the objective to reach Done.

4. 4

   Create an initiative and assign the objective

   Click Initiatives in the sidebar and create a new one. Give it a name that captures the theme — "Q3 Auth Overhaul" or "Docs Site", not "Sprint 12". Go back to your objective and assign it to the initiative. This is optional but gives the board strategic shape.

5. 5

   Schedule the objective

   Open the objective and click Schedule. This moves it from Backlog to the Scheduled lane — visible to any coding agent connected to this project. Objectives stay in Scheduled until an agent claims them.

6. 6

   Your agent claims the objective

   Once your coding agent is connected (see AI & Agents), it can call planwright_list_objectives to see scheduled work and planwright_claim_objective to start. The objective moves to In Progress, the agent posts a decomposition plan, makes code changes, and opens a pull request.

   The agent's every commit must include a Planwright-Objective trailer so Planwright can link the code to the objective.

7. 7

   Review and accept

   When the agent is done, it calls planwright_request_acceptance. The objective moves to the Acceptance lane and you receive a notification. Open the objective, review the agent's plan and diff, and click Accept or Reject. Your decision is written to the audit chain — signed with your identity and the workspace's KMS key.