# Plansmith documentation
Turn a business requirement into a tree of dev-ready Specs, then push it to your issue tracker.
Source: https://www.plansmith.co/docs
Start with the five-minute quickstart, or wire up the CLI, the MCP server and the API.
From a business requirement to a plan in your issue tracker, in about five minutes.
Linear, Jira and Radial, and what re-pushing does to edits.
A versioned JSON API at `api.plansmith.co/v1`.
## Where to go [#where-to-go]
What Plansmith is for, the four words it uses, and how a plan comes together.
Read and push plans from your terminal or from CI.
Connect the MCP server to Claude Code, Cursor or Claude.ai in one config block.
What an Enterprise plan includes, and where Plansmith runs.
## How the docs are organized [#how-the-docs-are-organized]
**Start here** is what Plansmith is and how to get a plan out of it. **Plan the work** covers the
conversation, sub-plans, prototypes and sharing. **Give the agent context** is what it reads:
documents and your code. **Teach it how your team works** is how you shape what it writes.
**Ship the plan** is the push. **Run your workspace** is members, billing and the audit log.
**Enterprise** is where Plansmith runs, including against a Git server inside your own network, and
what an Enterprise plan includes.
The **Developers** tab covers the CLI, the MCP server and the API, and the **Changelog** records
what shipped.
Every page here has a markdown twin: add `.md` to any docs URL and you get the page as plain
markdown. There is a [full-site index](/llms-full.txt) too, and an [agent index](/llms.txt).
---
# Agent instructions
Standing decisions the agent follows in every conversation, set for you, a plan, a project or the whole company.
Source: https://www.plansmith.co/docs/agent-instructions
**Instructions** are standing decisions the agent should follow. They are the place for the
correction you keep making:
```text
Mobile ships after web. Stop proposing mobile work in the first pass.
We do not use feature flags for anything customer-visible.
```
Unlike [Context](/docs/context-sources), which is material the agent *reads*, instructions are
rules it *follows*. They are injected into every turn, so they shape the decision before the agent
starts thinking rather than sitting in a document it might consult.
## Four levels [#four-levels]
| Level | Applies to |
| ------------- | ------------------------------------------- |
| **You** | Only your conversations, in this workspace. |
| **This plan** | Only that plan. |
| **Project** | Every plan in that project. |
| **Company** | Every plan in the workspace. |
They are **additive**, not overriding. The agent sees all four, narrowest last. A genuine conflict
between two levels is yours to resolve, not something the system silently picks a winner for.
Your personal instructions are per workspace, so if you plan for two companies, each gets its own.
## Keep them short [#keep-them-short]
Instructions cost space in every single turn, so there is a cap on how much is injected. Write
decisions, not documentation:
* Good: "Always include a rollback step for anything touching billing."
* Bad: three paragraphs explaining your billing architecture. That is [Context](/docs/context-sources).
## The agent writes them too [#the-agent-writes-them-too]
As you plan, the agent notices how you work and writes instructions at the You, plan and project
levels on its own. That is why the project instructions grow over time without anyone opening the
settings screen.
## Company instructions need approval [#company-instructions-need-approval]
Company-level instructions reach every member's conversations, so they are **owner-only** and the
agent can only propose them.
When it does, the settings screen shows "A change is waiting" with today's version and the proposed
one side by side, and an owner approves or rejects. A member sees the pending change and a note
that an owner needs to approve it.
That gate exists because a company instruction is the highest-leverage text in the workspace. Anyone
who could get text in there could steer every future conversation for everyone, so the write is
deliberately a human act.
Edit yours under **Settings → Instructions**, at either the workspace or the project level, and
your own under your profile.
---
# Agent tools
What the planning agent is allowed to do as you, and how to change it.
Source: https://www.plansmith.co/docs/agent-tools
The planning agent acts **as you**. When it reads a repository, attaches a document or pushes a
plan, it does so with your access and nothing more.
**Settings → Agent tools** in your profile is where you decide which of those things it may do
without asking.
## It is a personal setting [#it-is-a-personal-setting]
Your tool permissions are yours. They are not a workspace policy, and changing them affects your
conversations only.
That is the right shape because the permissions are bounded by your own access anyway. The agent
cannot reach a plan you cannot reach, or a repository you never connected, whatever this screen
says.
## What it covers [#what-it-covers]
The controls cover the actions with a side effect outside the conversation: reading connected
repositories, searching the web, fetching a page, writing to your issue tracker.
Turning one off does not break planning. The agent tells you it needs that action and asks, rather
than silently producing a worse plan.
Nothing here can widen your access. It only narrows what the agent may do on your behalf, which
means the safe default is to leave it alone until you have a reason not to.
---
# Getting started with the Plansmith API
The base URL, how to authenticate, and the one error rule worth knowing before you start.
Source: https://www.plansmith.co/docs/api-reference
The Plansmith API is a versioned JSON API. Every page in this section is generated from the same
OpenAPI document the server publishes at
[`/v1/openapi.json`](https://api.plansmith.co/v1/openapi.json), so what you read here is what the
API actually accepts and returns.
## Base URL [#base-url]
```text
https://api.plansmith.co/v1
```
Pointing a local client at a dev server needs the `/api` segment:
`http://localhost:3000/api/v1/me`. The `api.plansmith.co` host rewrites `/v1` onto it for you, and
nothing else does.
## Authentication [#authentication]
Every request carries a bearer credential:
```bash
curl -H "Authorization: Bearer psk_read_…" https://api.plansmith.co/v1/me
```
Two kinds work on the same header: a **personal API key** (`psk_…`) minted in Settings → API keys
or with `plansmith keys create`, and an **OAuth access token** (`plan_at_…`) obtained by the CLI or
an MCP client.
Both act as the human they belong to. A credential reaches exactly the plans that person can reach,
and scope (`read` or `write`) is a ceiling on top of that, never a widening of it.
## Errors [#errors]
Errors come back in one envelope, on every endpoint:
```json
{
"error": {
"code": "not_found",
"message": "No such plan."
}
}
```
**A plan you cannot read answers 404, exactly like a plan that does not exist.** That is
deliberate: a 403 next to a 404 would tell you which private plans are real. The only 403 you will
see on plan content is when you can read a plan but not edit it.
## Shapes worth knowing up front [#shapes-worth-knowing-up-front]
Collections are **named**, not wrapped in a generic envelope: `GET /v1/api-keys` answers
`{ "keys": [ … ] }`, `GET /v1/projects` answers `{ "projects": [ … ] }`.
Deletes answer **200 with a small acknowledgement**, not 204: `{ "deleted": true }`,
`{ "removed": true }`, or a count.
Plans and Specs are addressed by their **handles** (`PLAN-12`, `SPEC-3`) wherever a URL takes one,
and `needsFirst` comes back as handles too, so you can render "needs SPEC-3 first" without building
your own id map.
## Versioning [#versioning]
The path carries the version. `/v1` will not change shape underneath you: fields are added, never
removed or repurposed, and a breaking change would arrive as `/v2`.
## Trying a request [#trying-a-request]
Every endpoint page has a playground. Fill in a key and send a real request; without one you get a
real `401`, which is the fastest way to confirm you are reaching the right host.
---
# Connect a tracker or MCP connector
Source: https://www.plansmith.co/docs/api-reference/connectors/createV1ConnectorsByConnectorIdConnect
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Register an MCP server by URL
Source: https://www.plansmith.co/docs/api-reference/connectors/createV1McpServers
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Disconnect a connector
Source: https://www.plansmith.co/docs/api-reference/connectors/deleteV1ConnectorsByConnectorIdConnect
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Remove a registered MCP server
Source: https://www.plansmith.co/docs/api-reference/connectors/deleteV1McpServersBySlug
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# The connector catalog, with this workspace’s connection status
Source: https://www.plansmith.co/docs/api-reference/connectors/getV1Connectors
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# The connector’s MCP toolset
Source: https://www.plansmith.co/docs/api-reference/connectors/getV1ConnectorsByConnectorIdToolsets
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# List this workspace’s own MCP servers
Source: https://www.plansmith.co/docs/api-reference/connectors/getV1McpServers
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Get a registered MCP server
Source: https://www.plansmith.co/docs/api-reference/connectors/getV1McpServersBySlug
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Enable or disable a connector’s MCP tools
Source: https://www.plansmith.co/docs/api-reference/connectors/updateV1ConnectorsByConnectorIdToolsets
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Update a registered MCP server
Source: https://www.plansmith.co/docs/api-reference/connectors/updateV1McpServersBySlug
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Attach a Context source to the workspace
Source: https://www.plansmith.co/docs/api-reference/context/createV1Context
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Re-fetch a URL-backed Context source
Source: https://www.plansmith.co/docs/api-reference/context/createV1ContextBySourceIdRefresh
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Upload a file as a Context source (on_conflict: keep_both | replace | skip)
Source: https://www.plansmith.co/docs/api-reference/context/createV1ContextUpload
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Remove a Context source
Source: https://www.plansmith.co/docs/api-reference/context/deleteV1ContextBySourceId
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# List the Context sources for the workspace
Source: https://www.plansmith.co/docs/api-reference/context/getV1Context
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Get a Context source
Source: https://www.plansmith.co/docs/api-reference/context/getV1ContextBySourceId
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Mint an API key (the secret is returned once)
Source: https://www.plansmith.co/docs/api-reference/credentials/createV1ApiKeys
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Revoke one of your API keys
Source: https://www.plansmith.co/docs/api-reference/credentials/deleteV1ApiKeysByKeyId
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Disconnect an app and kill its tokens
Source: https://www.plansmith.co/docs/api-reference/credentials/deleteV1OauthConnectionsByGrantId
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# List your API keys in this workspace
Source: https://www.plansmith.co/docs/api-reference/credentials/getV1ApiKeys
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# List the apps you have connected
Source: https://www.plansmith.co/docs/api-reference/credentials/getV1OauthConnections
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Reset the workspace format to the built-in
Source: https://www.plansmith.co/docs/api-reference/formats/deleteV1FormatsByKind
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# The resolved Spec or Epic format, with its source tier
Source: https://www.plansmith.co/docs/api-reference/formats/getV1FormatsByKind
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Set the workspace’s Spec or Epic format (owner only)
Source: https://www.plansmith.co/docs/api-reference/formats/setV1FormatsByKind
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# API index, plus the identity of the calling credential when one is sent
Source: https://www.plansmith.co/docs/api-reference/identity/getV1
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Who this credential is, and what it can do
Source: https://www.plansmith.co/docs/api-reference/identity/getV1Me
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Re-fetch a URL-backed Context source
Source: https://www.plansmith.co/docs/api-reference/plans/createV1ProjectsByProjectSlugContextBySourceIdRefresh
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Attach a Context source to a plan
Source: https://www.plansmith.co/docs/api-reference/plans/createV1ProjectsByProjectSlugPlansByPlanShortIdContext
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Re-fetch a URL-backed Context source
Source: https://www.plansmith.co/docs/api-reference/plans/createV1ProjectsByProjectSlugPlansByPlanShortIdContextBySourceIdRefresh
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Add a needs-first edge between plans
Source: https://www.plansmith.co/docs/api-reference/plans/createV1ProjectsByProjectSlugPlansByPlanShortIdDependencies
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Add a prototype comment
Source: https://www.plansmith.co/docs/api-reference/plans/createV1ProjectsByProjectSlugPlansByPlanShortIdPrototypeComments
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Mint or rotate a public link (owner only)
Source: https://www.plansmith.co/docs/api-reference/plans/createV1ProjectsByProjectSlugPlansByPlanShortIdPrototypeShares
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Push a plan and its Specs to the connected tracker
Source: https://www.plansmith.co/docs/api-reference/plans/createV1ProjectsByProjectSlugPlansByPlanShortIdPush
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Share a plan with a workspace member
Source: https://www.plansmith.co/docs/api-reference/plans/createV1ProjectsByProjectSlugPlansByPlanShortIdSharingCollaborators
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Add a Spec to a plan
Source: https://www.plansmith.co/docs/api-reference/plans/createV1ProjectsByProjectSlugPlansByPlanShortIdSpecs
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Promote a Spec subtree into its own sub-plan
Source: https://www.plansmith.co/docs/api-reference/plans/createV1ProjectsByProjectSlugPlansByPlanShortIdSpecsBySpecShortIdPromote
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Remove a Context source
Source: https://www.plansmith.co/docs/api-reference/plans/deleteV1ProjectsByProjectSlugPlansByPlanShortIdContextBySourceId
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Remove a needs-first edge
Source: https://www.plansmith.co/docs/api-reference/plans/deleteV1ProjectsByProjectSlugPlansByPlanShortIdDependenciesByEdgeId
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Delete a comment
Source: https://www.plansmith.co/docs/api-reference/plans/deleteV1ProjectsByProjectSlugPlansByPlanShortIdPrototypeCommentsByCommentId
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Revoke every public link for this plan
Source: https://www.plansmith.co/docs/api-reference/plans/deleteV1ProjectsByProjectSlugPlansByPlanShortIdPrototypeShares
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Remove a collaborator
Source: https://www.plansmith.co/docs/api-reference/plans/deleteV1ProjectsByProjectSlugPlansByPlanShortIdSharingCollaboratorsByUserId
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Delete a Spec
Source: https://www.plansmith.co/docs/api-reference/plans/deleteV1ProjectsByProjectSlugPlansByPlanShortIdSpecsBySpecShortId
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# List the Context sources for a plan
Source: https://www.plansmith.co/docs/api-reference/plans/getV1ProjectsByProjectSlugPlansByPlanShortIdContext
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Get a Context source
Source: https://www.plansmith.co/docs/api-reference/plans/getV1ProjectsByProjectSlugPlansByPlanShortIdContextBySourceId
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Read a plan’s epic
Source: https://www.plansmith.co/docs/api-reference/plans/getV1ProjectsByProjectSlugPlansByPlanShortIdEpic
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Export a plan as markdown, CSV or JSON
Source: https://www.plansmith.co/docs/api-reference/plans/getV1ProjectsByProjectSlugPlansByPlanShortIdExport
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Get the plan’s clickable prototype
Source: https://www.plansmith.co/docs/api-reference/plans/getV1ProjectsByProjectSlugPlansByPlanShortIdPrototype
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# List prototype comments
Source: https://www.plansmith.co/docs/api-reference/plans/getV1ProjectsByProjectSlugPlansByPlanShortIdPrototypeComments
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# List live public links for this prototype
Source: https://www.plansmith.co/docs/api-reference/plans/getV1ProjectsByProjectSlugPlansByPlanShortIdPrototypeShares
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# What has been pushed, and what changed since
Source: https://www.plansmith.co/docs/api-reference/plans/getV1ProjectsByProjectSlugPlansByPlanShortIdPushStatus
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Who this plan is shared with (owner only)
Source: https://www.plansmith.co/docs/api-reference/plans/getV1ProjectsByProjectSlugPlansByPlanShortIdSharing
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# List collaborators (owner only)
Source: https://www.plansmith.co/docs/api-reference/plans/getV1ProjectsByProjectSlugPlansByPlanShortIdSharingCollaborators
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Get a Spec, including its numbered Acceptance Criteria
Source: https://www.plansmith.co/docs/api-reference/plans/getV1ProjectsByProjectSlugPlansByPlanShortIdSpecsBySpecShortId
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Get a plan with every Spec, sub-plan and dependency in one call
Source: https://www.plansmith.co/docs/api-reference/plans/getV1ProjectsByProjectSlugPlansByPlanShortIdTree
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Replace a plan’s epic
Source: https://www.plansmith.co/docs/api-reference/plans/setV1ProjectsByProjectSlugPlansByPlanShortIdEpic
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Make a plan private or visible to the whole workspace
Source: https://www.plansmith.co/docs/api-reference/plans/setV1ProjectsByProjectSlugPlansByPlanShortIdSharingVisibility
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Resolve or reopen a comment
Source: https://www.plansmith.co/docs/api-reference/plans/updateV1ProjectsByProjectSlugPlansByPlanShortIdPrototypeCommentsByCommentId
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Change a collaborator’s role
Source: https://www.plansmith.co/docs/api-reference/plans/updateV1ProjectsByProjectSlugPlansByPlanShortIdSharingCollaboratorsByUserId
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Update a Spec
Source: https://www.plansmith.co/docs/api-reference/plans/updateV1ProjectsByProjectSlugPlansByPlanShortIdSpecsBySpecShortId
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Create a project
Source: https://www.plansmith.co/docs/api-reference/projects/createV1Projects
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Attach a Context source to a project
Source: https://www.plansmith.co/docs/api-reference/projects/createV1ProjectsByProjectSlugContext
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Upload a file as a Context source (on_conflict: keep_both | replace | skip)
Source: https://www.plansmith.co/docs/api-reference/projects/createV1ProjectsByProjectSlugContextUpload
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Create a plan, or a sub-plan under an existing one
Source: https://www.plansmith.co/docs/api-reference/projects/createV1ProjectsByProjectSlugPlans
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Remove a Context source
Source: https://www.plansmith.co/docs/api-reference/projects/deleteV1ProjectsByProjectSlugContextBySourceId
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Reset this project’s format
Source: https://www.plansmith.co/docs/api-reference/projects/deleteV1ProjectsByProjectSlugFormatsByKind
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Delete a plan
Source: https://www.plansmith.co/docs/api-reference/projects/deleteV1ProjectsByProjectSlugPlansByPlanShortId
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Delete a project skill
Source: https://www.plansmith.co/docs/api-reference/projects/deleteV1ProjectsByProjectSlugSkillsBySlug
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# List projects
Source: https://www.plansmith.co/docs/api-reference/projects/getV1Projects
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Get a project
Source: https://www.plansmith.co/docs/api-reference/projects/getV1ProjectsByProjectSlug
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# List the Context sources for a project
Source: https://www.plansmith.co/docs/api-reference/projects/getV1ProjectsByProjectSlugContext
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Get a Context source
Source: https://www.plansmith.co/docs/api-reference/projects/getV1ProjectsByProjectSlugContextBySourceId
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# The format resolved for this project
Source: https://www.plansmith.co/docs/api-reference/projects/getV1ProjectsByProjectSlugFormatsByKind
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# List the plans you can see in a project
Source: https://www.plansmith.co/docs/api-reference/projects/getV1ProjectsByProjectSlugPlans
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Get a plan and its epic
Source: https://www.plansmith.co/docs/api-reference/projects/getV1ProjectsByProjectSlugPlansByPlanShortId
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# List a project’s skills
Source: https://www.plansmith.co/docs/api-reference/projects/getV1ProjectsByProjectSlugSkills
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Read a project skill
Source: https://www.plansmith.co/docs/api-reference/projects/getV1ProjectsByProjectSlugSkillsBySlug
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Set this project’s format
Source: https://www.plansmith.co/docs/api-reference/projects/setV1ProjectsByProjectSlugFormatsByKind
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Write a project skill
Source: https://www.plansmith.co/docs/api-reference/projects/setV1ProjectsByProjectSlugSkillsBySlug
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Rename a project
Source: https://www.plansmith.co/docs/api-reference/projects/updateV1ProjectsByProjectSlug
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Rename, re-parent, or move a plan through its lifecycle
Source: https://www.plansmith.co/docs/api-reference/projects/updateV1ProjectsByProjectSlugPlansByPlanShortId
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Delete a workspace skill (owner only)
Source: https://www.plansmith.co/docs/api-reference/skills/deleteV1SkillsBySlug
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# List skills (built-in and workspace)
Source: https://www.plansmith.co/docs/api-reference/skills/getV1Skills
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Read a workspace skill
Source: https://www.plansmith.co/docs/api-reference/skills/getV1SkillsBySlug
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Write a workspace skill (owner only)
Source: https://www.plansmith.co/docs/api-reference/skills/setV1SkillsBySlug
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# This document, describing every endpoint
Source: https://www.plansmith.co/docs/api-reference/spec/getV1OpenapiJson
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Invite someone to the workspace
Source: https://www.plansmith.co/docs/api-reference/workspace/createV1Invites
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Revoke a pending invite
Source: https://www.plansmith.co/docs/api-reference/workspace/deleteV1InvitesByInviteId
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Remove a member (name a successor if they own plans)
Source: https://www.plansmith.co/docs/api-reference/workspace/deleteV1MembersByUserId
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# List pending invites
Source: https://www.plansmith.co/docs/api-reference/workspace/getV1Invites
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# List the members of this workspace
Source: https://www.plansmith.co/docs/api-reference/workspace/getV1Members
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Change a member’s role
Source: https://www.plansmith.co/docs/api-reference/workspace/updateV1MembersByUserId
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Audit log
A record of the consequential things that happened in your workspace, readable by owners.
Source: https://www.plansmith.co/docs/audit-log
The audit log records the events an administrator needs after the fact: members invited and
removed, roles changed, connectors added and revoked, and changes to company-level settings.
Find it under **Settings → Audit log**.
## Owners only [#owners-only]
Reading the audit log requires the owner role.
A member who opens the page gets the page and an honest refusal rather than a 404. Pretending the
screen does not exist would be a worse answer: they can see it in the navigation, and telling them
"this is owner-only" is the truthful one.
## What is in an entry [#what-is-in-an-entry]
Each entry records what happened, who did it, and when. Events are recorded as they occur and are
not editable by anyone, including owners.
## What it is not [#what-it-is-not]
It is not a plan history. Changes to a plan's Specs live in the plan itself and in its conversation,
which is a better record of *why* something changed than an event row would be.
It is not a login log. Authentication is handled by your identity provider, and its own logs are the
place to answer questions about sign-ins.
---
# Billing and usage
The three plans, what counts as usage, and how to add more when you run low.
Source: https://www.plansmith.co/docs/billing-and-usage
## The plans [#the-plans]
| Plan | For |
| -------------- | ------------------------------------------------------------------------------ |
| **Solo** | One person planning their own work. Self-serve. |
| **Team** | A team planning together, plus self-hosted Git servers and the managed broker. |
| **Enterprise** | Larger organizations. Arranged with us rather than self-serve. |
Owners manage the subscription under **Settings → Billing**.
## What usage means [#what-usage-means]
Planning conversations do real work: research, reading your Context, writing and rewriting Specs.
That work is what your allowance covers, and the billing screen shows how much of it you have used
as a percentage of your monthly allowance.
Reading plans, browsing Specs, sharing, and pushing to your issue tracker do not consume it. The
cost is in the planning itself.
## Running low [#running-low]
If you are heading toward your limit before the month resets, add usage from the billing screen.
The addition applies immediately and does not change your plan.
## What happens at the limit [#what-happens-at-the-limit]
Planning conversations stop until the month resets or you add usage. Nothing is deleted, nothing is
locked, and everything you have already planned stays readable, shareable and pushable.
Only owners can change the subscription or add usage. A member who hits the limit sees what has
happened and who to ask, rather than a generic failure.
---
# Connecting a repository
Ground your Specs in the code your team actually has. Read-only, GitHub, GitLab and Bitbucket.
Source: https://www.plansmith.co/docs/connecting-a-repository
Connecting a repository lets the planning agent read your code while it plans, so the Specs it
writes match the stack, the patterns and the naming you already use.
**Connecting is read-only.** Plansmith reads your repository to understand it. It never opens a
pull request, never pushes a commit, and never writes anything back.
## The code connectors [#the-code-connectors]
github.com and GitHub Enterprise Server.
gitlab.com and self-managed GitLab.
Bitbucket Cloud and Bitbucket Data Center.
These are **not** push destinations. Nothing from a plan is written to them. For where a finished
plan goes, see [Push to your issue tracker](/docs/push-to-your-issue-tracker).
## Connecting [#connecting]
Open **Settings → Connectors** in your project and authorize the provider. Connections are made
with OAuth, per person, and the agent reaches a repository as the person who connected it.
Once a repository is linked to a project, anyone planning in that project can ground against it.
## Self-hosted servers [#self-hosted-servers]
A GitHub Enterprise, self-managed GitLab or Bitbucket Data Center instance connects the same way,
with two conditions:
* **It is a Team plan capability.** Registering a self-hosted server requires the Team or
Enterprise plan, and an owner.
* **It must be reachable over public HTTPS.** Plansmith refuses private and internal addresses on
purpose.
If your server only answers inside your network, that is what the
[self-hosted Git broker](/docs/developers/broker) is for: a small container you run, which dials
out to Plansmith and relays a fixed list of read-only requests. Nothing inbound, and your Git
credential never leaves your network.
---
# Context sources
The documents the agent reads before it plans: what to attach, at which level, and how inheritance works.
Source: https://www.plansmith.co/docs/context-sources
**Context** is the material the agent reads before it writes anything: your PRDs, research, support
transcripts, regulations, API documentation, meeting notes.
It is the single highest-leverage thing you can give it. An agent with no Context writes a
plausible plan about software in general; an agent with your Context writes a plan about your
business.
## Three levels, and they flow down [#three-levels-and-they-flow-down]
| Attach at | When |
| ----------- | ---------------------------------------------------------------------------------- |
| **Team** | True for everything you build: how you work, your tone, your standards. |
| **Project** | True for this product: its PRD, its architecture, its customers. |
| **Plan** | Only for this piece of work: the regulation, the vendor's docs, the ticket thread. |
Context flows **downward**. A plan sees its own sources, plus its project's, plus your team's. A
sub-plan also inherits everything above it, read-only.
Nothing flows upward or sideways. A project does not read its plans' sources, and sibling plans
never see each other's.
## Choosing the level [#choosing-the-level]
Attach as high as the material is true, and no higher.
A document at Team level reaches every plan in every project, which is right for "how we write
release notes" and wrong for "the Q3 pricing memo". The cost of attaching too high is not storage,
it is that every unrelated plan now reads it.
If a piece of work needs its own sources, that is the signal it should be a sub-plan rather than
more Specs in the current one. Specs cannot hold Context; plans can. See
[Sub-plans and dependencies](/docs/sub-plans-and-dependencies).
## Code is Context too [#code-is-context-too]
A connected repository is Context in every sense. The agent reads it to ground what it writes in
the stack and conventions you actually have. It is set up differently, so it has its own page:
[Connecting a repository](/docs/connecting-a-repository).
---
# Core concepts
Team, Project, Plan and Spec: the four words every other page in these docs uses.
Source: https://www.plansmith.co/docs/core-concepts
Four containers, nested. Everything else in Plansmith hangs off them.
Your workspace. People, billing, and the conventions everyone shares.
A product or a body of work. Holds plans, and the issue tracker they push to.
One piece of work being planned. The unit you converse with and push.
A single dev-ready item, with its acceptance criteria. Where Plansmith stops.
## Plans and Specs both nest [#plans-and-specs-both-nest]
A **Plan** can contain sub-plans, to any depth. A **Spec** can contain child Specs. Both can also
depend on each other: "this needs that first".
That gives you two ways to break work down, and choosing between them is the one structural
decision worth understanding. It comes down to Context, and it has its own page:
[Sub-plans and dependencies](/docs/sub-plans-and-dependencies).
## A Spec is the smallest unit [#a-spec-is-the-smallest-unit]
Every Spec has a title, a body, and numbered **acceptance criteria**, the checklist that says what
done means. It also carries two judgements the agent makes and you can correct:
| | What it means | How it reads |
| ------------- | -------------------------------------- | ----------------------- |
| **Readiness** | How build-ready this Spec is right now | Rough · Shaping · Ready |
| **Effort** | Rough size, for ordering and planning | Low · Med · High |
Readiness is the more useful of the two. A plan full of Rough Specs is a plan that needs another
conversation, and the agent will tell you which ones and why.
## Context sits alongside [#context-sits-alongside]
**Context** is the material the agent reads: documents you attach, and code repositories you
connect. It attaches at Team, Project or Plan level and flows downward, so a Plan sees its own
sources plus everything above it.
Context is deliberately not attached to a Spec. If a piece of work needs its own sources, that is
the signal it should be a sub-plan.
What to attach, at which level, and how inheritance works.
When to nest a plan instead of adding another Spec.
---
# Deployment options
Where Plansmith runs, and how it reads a Git server that only answers inside your network.
Source: https://www.plansmith.co/docs/deployment-options
Plansmith is a hosted service. What varies between teams is where your Git server lives and how much
of it stays on your side of the firewall.
## Plansmith cloud [#plansmith-cloud]
How everyone runs Plansmith today. The application is hosted, your workspace data lives in a managed
Postgres database, and there is nothing to install.
Which providers process your data, and where, is stated in the
[privacy policy](/privacy). This page does not keep a second copy of that list, because two copies
drift and one of them ends up wrong in front of a customer.
## Your Git server, inside your network [#your-git-server-inside-your-network]
GitHub Enterprise, self-managed GitLab and Bitbucket Data Center all connect the same way a cloud
host does, and grounding a plan in your code works the same once connected.
**Self-hosted Git servers are a Team and Enterprise capability**, and registering one takes an owner.
What differs is whether Plansmith can reach the server at all.
### Reachable on public HTTPS [#reachable-on-public-https]
Plansmith connects directly. This covers all three providers.
The part worth reading if you are reviewing us: every request checks the address the hostname
actually resolved to, inside the same lookup that makes the connection. A name cannot resolve to
something harmless during a check and something internal a moment later.
* Loopback, private and link-local addresses are refused.
* Cloud metadata endpoints are refused.
* Carrier-grade NAT, unique local IPv6 and multicast ranges are refused.
* Plain HTTP is refused. Self-hosted means public HTTPS.
Register the server under **Settings → Connectors**, then connect it the way you would a cloud host.
See [Connecting a repository](/docs/connecting-a-repository) for the product flow.
### Not reachable from the internet [#not-reachable-from-the-internet]
The managed broker is a small container you run inside your network. It dials **out** to Plansmith
and asks for work, so:
* there is **no inbound firewall port**, and nothing for you to open;
* your Git credential never leaves your side: the container authenticates to your server with a
service account you create, and that account is the bound on everything the broker can read.
Be clear on what the broker does, because "outbound only" is about connections, not about
intent. The work still originates with Plansmith: the container polls for a request, runs it against
your server, and sends the result back so the agent can ground a plan in it. What stays on your side
is the credential and the network position. What travels is the content the agent asked for, the
same as any other connected repository.
**The broker relays GitLab.** Its target list holds GitLab and nothing else today. If you run GitHub
Enterprise or Bitbucket Data Center and your server answers on public HTTPS, use the direct path
above. If it does not, talk to us: there is nothing to run yet.
[The broker setup guide](/docs/developers/broker) is written for the person running the container,
not for a Plansmith user. Hand it over as-is.
## Self-hosted Plansmith [#self-hosted-plansmith]
For an Enterprise agreement we will discuss running Plansmith inside your own environment. What that
looks like depends on your constraints, so it is scoped per agreement rather than described here.
Start with a conversation. See [Enterprise features](/docs/enterprise).
## If you run a corporate proxy or an egress allowlist [#if-you-run-a-corporate-proxy-or-an-egress-allowlist]
Allow these:
| Host | What it serves | Who needs it |
| ------------------ | ----------------------------------------------------------------- | ------------------------------- |
| `app.plansmith.co` | The product | Everyone |
| `www.plansmith.co` | The marketing site, including these docs and demo booking | Everyone |
| `*.supabase.co` | Sign-in and live plan updates, which the browser fetches directly | Everyone |
| `api.plansmith.co` | The REST API | Teams using the API or the CLI |
| `mcp.plansmith.co` | The MCP server | Teams connecting a coding agent |
The Supabase host is the one people miss. The app signs you in and streams plan updates from it in
the browser rather than through our API, so a proxy that allows only `plansmith.co` leaves your team
staring at a login screen.
The broker adds nothing inbound. Outbound, it talks to exactly two places: `app.plansmith.co`, and
the Git server you point it at inside your own network. Point it at the API or the MCP host instead
and it refuses to start, naming the host to use.
## Side by side [#side-by-side]
| | Cloud | Your Git, direct | Your Git, broker | Self-hosted |
| -------------------- | ------------------- | ------------------------------------------------ | ----------------------------------------------- | ---------------- |
| **Application runs** | Plansmith cloud | Plansmith cloud | Plansmith cloud | Your environment |
| **Your Git lives** | Anywhere | Your server, public HTTPS | Your network, no inbound port | Your network |
| **Providers** | All | GitHub Enterprise, GitLab, Bitbucket Data Center | GitLab | By agreement |
| **We hold** | Your workspace data | Plus an OAuth token and whatever the agent read | Plus a broker token and whatever the agent read | By agreement |
| **What it takes** | Sign up | Team plan, an app registered on your server | Team plan, run a container | Talk to us |
The product flow for grounding a plan in your code.
The runbook for the person who runs the container.
---
# Plansmith for developers
The three developer surfaces, how they authenticate, and which one to reach for.
Source: https://www.plansmith.co/docs/developers
Everything your team does in Plansmith is available outside the browser.
Read and push plans from your terminal or from CI.
Give a coding agent the plan it is meant to build from.
A versioned JSON API at `api.plansmith.co/v1`.
## Which one [#which-one]
Reach for the **CLI** for anything a person or a script runs: pulling a plan into a repo, pushing
from CI, checking what is Ready.
Reach for the **MCP server** when a coding agent should read the plan while it works. That is the
difference between an agent that guesses at requirements and one that builds from Specs with
acceptance criteria.
Reach for the **API** when you are building something of your own.
## One permission model [#one-permission-model]
Whichever surface you use, **your credential acts as you**. It reaches exactly the plans you can
reach, and a private plan nobody shared with you is invisible to your scripts and your agents too.
Nothing here can widen your access. A write-scoped key held by someone with view-only access to a
plan still cannot change that plan.
## Authenticating [#authenticating]
Two credential kinds work everywhere, on the same `Authorization: Bearer` header:
| Credential | Get one | Use it for |
| ------------------------------ | ----------------------------------------------------- | ---------------------------------------------------- |
| **Personal API key** (`psk_…`) | Settings → API keys, or `plansmith keys create` | CI, scripts, anything non-interactive. |
| **OAuth access token** | `plansmith auth`, or your MCP client's consent screen | A person at a terminal, or an agent acting for them. |
A key is scoped `read` or `write`. Scope is a ceiling on top of your own permissions, never a
widening of them.
```bash
curl -H "Authorization: Bearer psk_read_…" https://api.plansmith.co/v1/me
```
## How things are addressed [#how-things-are-addressed]
Projects have a slug, plans are `PLAN-n` within their project, and Specs are `SPEC-n` within their
plan. They are the same handles you see in the web app, so a URL you read in the console is a path
you can call.
```text
/v1/projects/recipe-box
/v1/projects/recipe-box/plans/PLAN-12
/v1/projects/recipe-box/plans/PLAN-12/specs/SPEC-3
```
---
# Plansmith API
A versioned JSON API at api.plansmith.co/v1, authenticated with a bearer credential.
Source: https://www.plansmith.co/docs/developers/api
## Start here, with no credential [#start-here-with-no-credential]
`GET /v1` answers without one. It returns the link map, how to get a credential, and where the
OpenAPI document lives, so a client can learn the shape of the API before anyone has minted
anything.
```bash
curl https://api.plansmith.co/v1
```
Send a credential on the same call and you get your workspace, your scope and the credential kind
back instead. A credential that is present and invalid is still refused with a 401: only the
absence of one is anonymous.
## Authentication [#authentication]
```bash
curl -H "Authorization: Bearer psk_write_…" https://api.plansmith.co/v1/me
```
Two credential kinds work on the same header: a personal API key (`psk_…`) minted in
Settings → API keys, and an OAuth access token obtained by the CLI or an MCP client. Both act as the
human they belong to.
## Scopes [#scopes]
A credential is `read` or `write`. Scope is a ceiling on top of your own permissions, never a
widening of them: a write key held by someone with view-only access to a plan still cannot change
that plan.
## Errors [#errors]
```json
{
"error": {
"code": "not_found",
"message": "No such plan."
}
}
```
A plan you cannot read answers 404, exactly like a plan that does not exist. That is deliberate: a
403 would confirm which private plans are real, so the two are made indistinguishable. The one 403
you will see on plan content is when you can read a plan but not edit it.
## How things are addressed [#how-things-are-addressed]
Projects have a slug, plans are `PLAN-n` within their project, and specs are `SPEC-n` within their
plan: the same handles you see in the web app, so a URL you read in the console is a path you can
call.
```text
/v1/projects/recipe-box
/v1/projects/recipe-box/plans/PLAN-12
/v1/projects/recipe-box/plans/PLAN-12/specs/SPEC-3
```
## The full reference [#the-full-reference]
Every route, parameter and response shape is described by the OpenAPI document. It needs no
credential, and it is served from two addresses: the API host, and the site root, which is where a
client that only knows the domain will look.
```bash
curl https://api.plansmith.co/v1/openapi.json
curl https://www.plansmith.co/openapi.json
```
`https://www.plansmith.co/.well-known/api-catalog` lists all of it in RFC 9727 form: the OpenAPI
document, these guides, and the MCP endpoint.
---
# Plansmith self-hosted Git broker
Let Plansmith read a Git server inside your network, without opening a firewall port and without giving us your credentials.
Source: https://www.plansmith.co/docs/developers/broker
{/*
PSM-584 — the managed broker setup guide.
⚠ THE READER OF THIS PAGE IS NOT A PLANSMITH USER. It is the customer's infra
or security engineer: someone handed a URL and a token by a colleague, who
will never log in, and who has to decide whether to run our container inside
their network. So it leads with what it does and what it can reach, answers
the security review in their vocabulary, and only then gives the command.
⚠ ONE BLOCK ON THIS PAGE IS PINNED TO CODE AND MUST NOT BE HAND-EDITED: the
image reference in the `docker run` command, pinned to `BROKER_IMAGE`
(`src/lib/marketing/broker-image.ts`) by `broker-image.test.ts`, which reads
THIS FILE. To change it, change the constant and re-run that test.
⚠ THE ENDPOINT TABLE IS GONE ON PURPOSE, AND SO IS ITS GUARD. This page used
to publish `renderAllowlistTable()` verbatim under an "The allowlist" heading,
pinned by `broker-allowlist-drift.test.ts`. Readers found a table of GitLab
REST paths confusing — it reads as a thing they have to evaluate, when the
bound they actually control is the service account they create. The security
section now says that, and mentions the container's own narrowing in a
sentence. Do not restore the table without restoring the drift guard with it:
a published table nothing pins is how the last one came to promise a narrower
surface than the container enforced (PSM-593).
⚠ THE SETUP TABS CARRY NO MARKDOWN HEADINGS, DELIBERATELY. The table of
contents is built from the file, not from what is on screen, so a `##` inside
a panel lists all three products' steps at once and two thirds of them scroll
to hidden content. Steps inside a panel are `` with a bold first line.
⚠ ONLY THE GITLAB TAB DESCRIBES A BROKER. The container's target is GitLab
(`TARGET_GITLAB_BASE_URL`) and `broker-agent/src/allowlist.ts` exports
`TARGETS = { gitlab }` — nothing else. The other two tabs describe the DIRECT
path, which is what actually works for them today. Do not write broker steps
for GHES or Bitbucket DC before the allowlist has rules for them.
*/}
## When you need one [#when-you-need-one]
If your GitLab, GitHub Enterprise or Bitbucket server is reachable from the internet, you do not
need this. Register it directly and skip this page. The managed broker exists for the other case: a
server that only answers inside your network, behind a VPN or a corporate firewall.
Self-hosted Git servers, including the broker, are available on the Team and Enterprise plans.
## How it works [#how-it-works]
You run a small container inside your network. It dials **out** to Plansmith over TLS and asks for
work. When a planning session needs to read your repository, we put a request on a queue; your
broker picks it up, adds your own Git credential, calls your server, and posts the response back.
**One broker reaches one server.** The container is configured with a single target URL, so if you
have two internal Git servers you run two brokers, each with its own token. Plansmith enforces this:
a broker that already reaches a server cannot be chosen for a second one.
## What your security team will ask [#what-your-security-team-will-ask]
* **Inbound ports: none.** The broker makes outbound connections only. There is no firewall rule to
add, no inbound route, and no VPN access for us.
* **Where credentials live: only in your network.** Your Git token is an environment variable on
your container. Plansmith never receives it, never stores it, and cannot read it. The broker
overwrites the authorization header on every request with your token, so nothing we send can
substitute a credential of ours.
* **What can be reached: whatever the service account or API token you create allows.** You set the
reach in your own Git server, and Plansmith cannot exceed it: the broker holds no credential of
its own, so an account with read access to two projects is an integration with read access to two
projects. The container narrows it further, to the handful of read-only API calls Plansmith
actually makes; a request outside that set is refused before it reaches your server, and the
refusal is logged. No write endpoint is reachable through the broker at all.
* **Audit: one JSON line per relayed request** to the container log, recording timestamp, method,
path, decision, status, duration and byte counts. Never request bodies, never file contents, never
tokens.
* **What we store, and for how long.** What your broker returns is the context the planning agent
works from, so it lives in that plan's chat for as long as the chat does. Getting it there uses a
queue in our database, and those rows are deleted as they are read; anything a failed request
leaves behind is scrubbed within the hour, and revoking a broker deletes its queued rows on the
spot. Archive a plan and it is deleted 30 days later, its chats and everything read into them
included.
## Setting up your server [#setting-up-your-server]
Select the git server you run.
**The broker does not relay GitHub Enterprise Server yet.** The container's target is GitLab and its
allowlist holds GitLab endpoints, so there is nothing to run for GHES today. What you do depends on
one thing: whether your server answers from the internet.
**If it does**, you do not need a broker at all: register it directly and skip the rest of this
page.
**In GHES: create a GitHub App.** In the organization that owns the repositories, go to **Settings →
Developer settings → GitHub Apps → New GitHub App**. Set the callback URL to
`https://app.plansmith.co/api/code-context/oauth/github/callback`, untick **Webhook → Active**, and
give it two read-only repository permissions: **Contents: Read-only** and **Metadata: Read-only**.
Nothing else is used.
**Collect four values** from the App's page: the **App ID**, its **slug** (the last segment of the
App's URL), a **client secret**, and a **private key**. The last two are generated on that page, and
the key downloads as a `.pem` file.
**Install the App** on the organizations whose repositories your team plans against. An App that
exists but is installed nowhere connects successfully and then lists no repositories.
**In Plansmith: register the server.** Open **Settings → Connectors** as an owner on the Team or
Enterprise plan, and under **Self-hosted** select **Add instance → GitHub Enterprise Server**.
Answer that the server is **reachable from the internet**, enter its URL and the four values, save,
then select **Connect** to authorize as yourself.
**If it only answers inside your network**, there is nothing to run yet. Broker relay for GHES is
planned as this same container with a GitHub target and its own allowlist, on the terms above:
outbound only, your credential never leaving your network, reads only. It is prioritized by who
asks, so tell us you need it.
None of this applies to github.com, which connects in one click under **Settings → Connectors**.
The setup takes about fifteen minutes across three places, and each step names where you are. You will need:
* Owner access to the GitLab group or project you want to plan against, for steps 1 to 3
* A Plansmith owner on the Team or Enterprise plan for step 4
* A host inside your network with Docker, able to reach the GitLab server and to make outbound HTTPS to `app.plansmith.co`, for step 5.
**In GitLab: create a service account.** A service account is GitLab's non-human account for
exactly this: it has no password and no inbox, nobody can sign in as it, its reads appear in your
audit logs under its own name, and it holds exactly the access Plansmith needs and nothing else.
1. Open the **group** whose projects your team plans against. For a single repository, open that
**project** instead.
2. In the left sidebar, go to **Settings → Service accounts**.
3. Select **Add service account** and name it `plansmith`.
Create it on the group when several projects should be available; a project-level service account
covers that one project. Creating one takes an owner of the group or project.
If **Settings → Service accounts** is not in your sidebar, your GitLab is older or on the Free tier.
The fallback works the same way: an administrator creates a dedicated regular user in the **Admin
area** (**Overview → Users → New user**), signs in as it once, and mints the token under **Edit
profile → Access tokens**. Steps 2 and 3 are unchanged.
**In GitLab: give it read access to the right projects.** A service account starts with access
to nothing, and its token can only see what the account can see. Membership is where you decide
which code Plansmith can read; nothing outside it is reachable, whatever the token says.
1. In the group (or project), go to **Manage → Members** and select **Invite members**.
2. Invite the service account. Search for the name you gave it; it appears with a generated username
like `@service_account_…`.
3. Give it the role **Reporter**.
4. Repeat for any other group you want available. Subgroups and their projects inherit the
membership.
**Reporter is the floor.** On a private project the Guest role can see that the project exists but
cannot read its files, so a Guest membership passes every screen here and then produces empty file
lists in step 6.
**In GitLab: create the access token.** Tokens for a service account are managed from the same
page you created it on. You never sign in as the account.
1. Back in **Settings → Service accounts**, open the **⋮** menu on the `plansmith` row and select
**Manage access tokens**.
2. Select **Add new token**.
3. Name it `plansmith-broker`, pick an expiry your policy allows, and tick **both** scopes:
**read\_api** and **read\_repository**.
4. Create it and copy the `glpat-` value straight away. GitLab shows it once.
**Both scopes, deliberately.** The broker talks to the GitLab REST API, and the scope that opens it
is `read_api`. A token with only `read_repository` looks right, is accepted here, and then fails
step 6 with 403: that scope covers Git operations, not the API. Both scopes are read-only.
**In Plansmith: add the server and get a pairing token.**
1. In Plansmith, open **Settings → Connectors**. You need to be an owner, on the Team or Enterprise
plan.
2. Under **Self-hosted**, select **Add instance** and pick GitLab.
3. Where it asks whether the server is reachable from the internet, answer **behind a firewall or
VPN**.
4. Enter the server URL, for example `https://gitlab.example.internal`. This is how the server
appears in Plansmith; traffic goes wherever your container is configured to reach, so use the
same URL here and in `TARGET_GITLAB_BASE_URL` in step 5. Private addresses and internal hostnames
are fine.
5. Select **Add managed broker** and name it after where it will run, for example `dc-frankfurt`.
The `psbk_` pairing token is shown **once**, with the command for step 5 pre-filled.
Keep this tab open: the broker flips to **Online** here the moment the container makes its first
poll.
**On your host: run the container.** On the Docker host inside your network, run the pre-filled
command from step 4. It looks like this:
```bash
docker run -d --name plansmith-broker --restart on-failure:5 \
-e PLANSMITH_URL=https://app.plansmith.co \
-e PLANSMITH_BROKER_TOKEN=psbk_… \
-e TARGET_GITLAB_BASE_URL=https://gitlab.internal \
-e TARGET_GITLAB_TOKEN=glpat-… \
ghcr.io/braingridai/plansmith-broker:0.3.0
```
`PLANSMITH_URL`: always `https://app.plansmith.co`. Not the API or MCP host, which serve a different
surface and will not answer a broker poll (the container refuses to start if you point it at one).
`PLANSMITH_BROKER_TOKEN`: the `psbk_` token from step 4.
`TARGET_GITLAB_BASE_URL`: your GitLab as reachable **from this container**, the same URL you entered
in step 4.
`TARGET_GITLAB_TOKEN`: the `glpat-` token from step 3. It never leaves your network.
`HTTPS_PROXY` / `NO_PROXY`: optional, honoured if your egress goes through a proxy.
`NODE_EXTRA_CA_CERTS`: optional, point it at your CA bundle if a proxy terminates TLS or your server
uses a private CA.
`AUDIT_LOG_PATH`: optional. The audit log always goes to stdout; this also writes it to a file.
**Verify end to end.** Within a few seconds of the container starting, the broker shows
**Online** in Plansmith. Finish saving the instance: Plansmith verifies it by asking your broker to
call `GET /user` on your GitLab, with your token, from inside your network. When that succeeds, pick
the repositories your team should plan against. The list you are choosing from is the service
account's membership from step 2.
For a final check, attach one of those repositories to a plan and ask the planning agent something
about the code. The answer arrives through the broker, and `docker logs plansmith-broker` shows one
JSON audit line per file read.
**The broker does not relay Bitbucket Data Center yet.** The container's target is GitLab and its
allowlist holds GitLab endpoints, so there is nothing to run for Bitbucket today. What you do
depends on one thing: whether your server answers from the internet.
**If it does**, you do not need a broker at all: register it directly and skip the rest of this
page.
**In Bitbucket: create an incoming application link.** As an administrator, go to **Administration →
Applications → Application links**, select **Create link**, and choose **External application →
Incoming**.
**Set the redirect URL** to `https://app.plansmith.co/api/code-context/oauth/bitbucket-dc/callback`
and grant the **Repositories: Read** permission, which is the whole of what Plansmith asks for. Save
the link, then copy its **client ID** and **client secret**.
**In Plansmith: register the server.** Open **Settings → Connectors** as an owner on the Team or
Enterprise plan, and under **Self-hosted** select **Add instance → Bitbucket Data Center**. Answer
that the server is **reachable from the internet**, enter its URL and the two values, save, then
select **Connect** to authorize as yourself.
**If it only answers inside your network**, there is nothing to run yet. Broker relay for Bitbucket
Data Center is planned as this same container with a Bitbucket target and its own allowlist, on the
terms above: outbound only, your credential never leaving your network, reads only. It is
prioritized by who asks, so tell us you need it.
None of this applies to Bitbucket Cloud, which connects in one click under **Settings →
Connectors**.
## If something is wrong [#if-something-is-wrong]
Everything below is about a running broker, so it is the git server's path.
* **A startup error naming the host.** `PLANSMITH_URL` points at the API or MCP host. Use
`app.plansmith.co`.
* **Polls return 404.** The pairing token was revoked, or mistyped. Add a new managed broker (step
4\) and restart the container with its token.
* **It stays Offline.** Outbound HTTPS to `app.plansmith.co` is blocked, or your proxy variables are
not set on the container.
* **Verification fails with 403 on a fresh token.** Two different halves fail identically from
outside: the token is missing the scope that opens your server's REST API, or the account it
belongs to is not a member of the group or project. Check both; your product's tab above names
the scope and the role.
* **Repositories are missing from the picker, or file lists come back empty.** The account's
membership does not cover them, or covers them at a level that can see a project exists but not
read its files. Widen the membership; a broader token will not fix it, because the token can only
ever see what the account can.
* **`allowlist_denied` in the log.** Working as designed: the container relays a fixed set of
read-only API calls, and something outside it was requested and refused before reaching your
server. Send us the line if you think that call should be allowed.
* **TLS errors.** Set `NODE_EXTRA_CA_CERTS` to your CA bundle.
* **Your monitoring shows requests with no response status.** Expected. An idle broker holds a poll
open for up to 25 seconds waiting for work, and some tools log the open request with an empty
status. It completes as an ordinary 200.
## Upgrading and shutting down [#upgrading-and-shutting-down]
Pin a version tag or an image digest and redeploy to upgrade. To stop a broker for good, revoke it
in Plansmith: its token stops working immediately, whatever version the container is running, and
anything still queued for it is deleted.
**To move a server to a different broker**, start the new broker, then add the server again in
Plansmith with the same URL and pick the new broker. Same URL means it updates the server you
already have rather than creating a second one, and the repositories you have already linked keep
working, so there is nothing to re-link.
---
# Plansmith CLI
Plan, spec, and push from your terminal. Zero dependencies, every command scriptable.
Source: https://www.plansmith.co/docs/developers/cli
## Install and sign in [#install-and-sign-in]
```bash
npm install -g plansmith.co
plansmith auth
```
Signing in uses the device flow: the CLI shows a short code, your browser confirms it, and the CLI
receives a token bound to the workspace you picked.
The package is published as `plansmith.co`; the binary it installs is `plansmith`.
## Everyday commands [#everyday-commands]
```bash
plansmith use recipe-box # pin a default project
plansmith plan list # plans you can see
plansmith plan tree PLAN-12 # specs, sub-plans, dependencies
plansmith spec show PLAN-12/SPEC-3
plansmith context add ./notes.md --plan PLAN-12
plansmith plan status PLAN-12 READY
plansmith push PLAN-12 --to linear
```
A plan can be named three ways: fully qualified (`recipe-box/PLAN-12`), with `--project`, or bare
once you have pinned a default with `plansmith use`.
## Scripting [#scripting]
Every command takes `--json` and prints the API response unchanged, so your script depends on the
API rather than on how the CLI formats things. Human-facing output goes to stderr, so redirecting
stdout gives you clean data.
```bash
plansmith plan tree PLAN-12 --json | jq '.specs[] | .shortId + " " + .title'
```
## CI [#ci]
```bash
PLANSMITH_KEY=psk_read_… plansmith plan list -p recipe-box --json
```
A static key skips the saved session entirely and never refreshes, so CI behaves identically on
every run. Mint one with `plansmith keys create ci --scope read`.
## Environment [#environment]
```text
PLANSMITH_KEY static API key (overrides the saved session)
PLANSMITH_API_URL default https://api.plansmith.co
PLANSMITH_AUTH_URL default https://www.plansmith.co
PLANSMITH_MCP_URL default https://mcp.plansmith.co
PLANSMITH_CONFIG_DIR default ~/.config/plansmith
```
Pointing the CLI at a local server needs the `/api` segment:
`PLANSMITH_API_URL=http://localhost:3000/api`. The `api.plansmith.co` host rewrites `/v1` onto it
for you, and nothing else does.
---
# Plansmith MCP server
Give a coding agent the plan it is meant to build from. Hosted is read-only; the local server adds the write tools.
Source: https://www.plansmith.co/docs/developers/mcp
## Hosted [#hosted]
```json
{
"mcpServers": {
"plansmith": {
"url": "https://mcp.plansmith.co"
}
}
}
```
Your client discovers how to authorize on its own and sends you to a consent screen the first time.
Nothing to paste.
## Local [#local]
```json
{
"mcpServers": {
"plansmith": {
"command": "plansmith",
"args": ["mcp"]
}
}
}
```
Runs on your machine and reuses the session from `plansmith auth`. Useful when the agent is already
local and you would rather not authorize a second connection.
## What the agent can do [#what-the-agent-can-do]
Read the plan and build from it: list projects and plans, pull a whole plan tree in one call, read a
Spec with its numbered acceptance criteria, and export a plan as markdown.
The hosted server is read-only in v1. To let an agent create plans and Specs, set a status, write an
epic, attach context or push to your issue tracker, run the local server instead: it acts under the
session you just created rather than a connection you authorized months ago.
An agent connected this way acts as you. It can reach exactly the plans you can reach, and a
read-only credential can never change anything. Revoke a connection any time in Settings → API keys.
## A good first prompt [#a-good-first-prompt]
```text
Read PLAN-12 in the recipe-box project from Plansmith and
implement SPEC-1, following its acceptance criteria exactly.
```
---
# Enterprise features
What an Enterprise plan includes, how your Git server stays in your network, and what buying one involves.
Source: https://www.plansmith.co/docs/enterprise
Plansmith sells itself for most teams. Enterprise exists for the ones where it has to clear
procurement first, or where the Git server it reads has no route in from the internet.
## Who it is for [#who-it-is-for]
* Teams that need volume pricing or contract terms of their own.
* Teams whose purchase goes through a review before anyone signs.
* Teams whose Git server only answers inside their network.
## What is included [#what-is-included]
| Capability | Availability |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| **Roles and per-plan access.** Owner, member and comment-only, with plans private by default and access set per plan. See [Members and roles](/docs/members-and-roles). | Every plan |
| **Audit log.** Invites, role changes, connector changes and company settings. See [Audit log](/docs/audit-log). | Owners only |
| **Self-managed GitHub, GitLab and Bitbucket**, plus the broker for a GitLab server with no route in from the internet. See [Deployment options](/docs/deployment-options). | Team and Enterprise |
| **Self-hosted Plansmith.** Running Plansmith inside your own environment, scoped to your constraints. | By agreement |
| **A named contact and dedicated onboarding.** Someone who knows your rollout, rather than a queue. | Enterprise |
## Procurement [#procurement]
* Volume pricing and contract terms of your own.
* Invoicing rather than a card.
* A data processing agreement on request.
* Security review: we answer questionnaires directly, and the [privacy policy](/privacy) covers what
we store, who processes it and what leaves your workspace.
## What Plansmith does not do to your code [#what-plansmith-does-not-do-to-your-code]
Worth stating plainly, because it is the first question a reviewer asks. Code grounding is read
only. The agent reads the repositories you authorize so the Specs it writes match your stack, and it
never opens a pull request, pushes a commit, or writes anything back. Push runs the other way: from
Plansmith to your issue tracker, carrying exactly the plan you push.
## Talk to us [#talk-to-us]
Thirty minutes. Bring a real business requirement from your backlog and we will plan it live.
---
# Spec and Epic formats
The sections every Spec and Epic is written to, and how to replace ours with your own.
Source: https://www.plansmith.co/docs/formats
A **format** is the document structure the agent writes to. There are two:
* **Spec format** shapes every Spec, including its numbered acceptance criteria.
* **Epic format** shapes each plan's Epic, the narrative your issue tracker receives as the
project or epic description.
Plansmith ships a standard version of each. A company or a project can replace either one outright.
## What ours look like [#what-ours-look-like]
The standard **Spec format** has an Overview and Acceptance Criteria always, plus User flow,
States, Data and Out of scope when the work calls for them. It adapts: a one-line fix does not get
the same eight sections as a new user-facing feature.
The standard **Epic format** is the stakeholder-facing document: a one-liner, the value
proposition, who it is for, the job to be done, background, key functionality, how you will tackle
it, and what is explicitly not in v1.
## Customizing [#customizing]
Open **Settings → Formats** and choose **Customize for this company** or **Customize for this
project**. You are handed the current format as a starting point and you own it from then on.
Resolution is **nearest wins, whole document**: a project copy beats a company copy, which beats
ours. Formats are never merged, because a format assembled from three partial sources produces
output nobody can predict.
## One rule per kind is enforced [#one-rule-per-kind-is-enforced]
Whatever else you change, each format has to keep one thing:
| Format | The rule | Why |
| -------- | ------------------------------------- | --------------------------------------------------------------------------------------- |
| **Spec** | Ends with a `- [ ]` checklist | Every Spec needs acceptance criteria; the tool that writes Specs enforces it. |
| **Epic** | Has at least one `## Section` heading | The Epic becomes your issue tracker's description, and headings make it readable there. |
The editor shows the rule beside your draft as you write.
## Removing a customization [#removing-a-customization]
The control is **Remove override**, not "reset to default", and the wording is exact: removing a
*project* format falls back to your *company* format when one exists, not to ours.
If a format was saved but cannot be read back, the settings card says so and tells you which one
the agent is actually using. It does not quietly fall through to the default, because "my
customization is live" and "my customization is broken" should not look the same.
## Changing it in conversation [#changing-it-in-conversation]
You can also adjust the **project** Spec format by asking, in a planning conversation:
```text
Here are two of our tickets. Match this format from now on.
```
That path is project-only on purpose. The company format is an owner act in settings, so a single
conversation cannot re-shape every Spec the whole workspace writes.
---
# Import from your issue tracker
Bring existing Jira work into a plan, refine it with the agent, and push it back to the same issues.
Source: https://www.plansmith.co/docs/import-from-your-issue-tracker
Work that already lives in Jira does not have to start over. Bring an epic or an issue into a plan,
refine it here, and push it back to the issues you started from.
## How to start one [#how-to-start-one]
Type it in the plan's chat:
```
import SIT-42
```
A Jira link works the same way, and `/import` in the composer fills the sentence in for you. There
is no separate import screen: the preview arrives as a card in the conversation, so what you brought
over stays in the chat history with the rest of the plan's story.
You can also just say what you want. If you tell the agent "we already planned the payments work in
Jira", it can find the item and offer the same card.
Connect Jira in **Settings → Connectors** first. The same connection powers both directions, so if
you can push to Jira you can import from it.
## What comes over [#what-comes-over]
The card shows the whole tree before anything is written:
* The item you picked **becomes the epic**, and its issues become specs.
* Sub-tasks **nest under their spec** as child specs.
* "Blocks" links become **needs-first** dependencies between specs.
* Images and attachments come along and land beside the specs that reference them. Pictures show up
in the spec, and the planning agent can read them, so you can ask about a screenshot.
* The **comment thread comes too**, under a "Comments from Jira" heading, with the images people
posted in it.
* Descriptions arrive **word for word**. Nothing is rewritten on the way in.
One issue with nothing under it lands as a single spec. If the structure is not what you want, the
top row has a toggle: bring it in as an epic with its specs, or as one spec with child specs. The
card re-counts as you flip it, so you can see what you are about to get.
## Choosing what to bring [#choosing-what-to-bring]
Untick anything you do not want. Unticking a parent leaves out everything under it, and there is a
one-click way to drop everything already marked Done, which is usually what you want when the epic
has been running for a while.
If you leave out a spec that another one needs first, the card says so and lets you continue. The
dependency becomes a note in the spec body instead of a broken link.
Nothing is written in Plansmith or in Jira until you press the button. Skipped items are remembered,
so bringing more over later does not ask about them again.
## After it lands [#after-it-lands]
The specs read exactly as Jira had them, which is the point: you can see what your team actually
wrote. When you want them in Plansmith's spec format, ask the agent to reshape them. It will do one
first so you can judge the result before it touches the rest.
If you then polish the epic and its jobs no longer line up with the imported specs, ask for a
coverage pass. The agent walks each job, says which specs cover it, which are partial and which are
missing, and proposes changes one spec at a time. It never rewrites your team's specs to match the
epic on its own.
## Pushing back [#pushing-back]
Every imported spec stays linked to the issue it came from. Push the plan and those same issues are
updated in place: no duplicates, and no second epic. You can see the link in a spec's frontmatter as
`tracker_key`.
If you asked Plansmith to mark the issues as checked out, the label and its comment come off once
the work has gone back.
Plansmith is where the plan gets written, so bring work over when this is where it is going to be
worked on. If a teammate edits an imported issue in Jira while you refine it here, the next push
stops and asks rather than overwriting them. See
[What happens when someone else edited it](/docs/push-to-your-issue-tracker).
Images travel one way too. A picture that came over with an issue renders in the spec, and the
planning agent can look at it. Pushing back does not re-upload the file to Jira: the issue keeps the
attachments it already had, and the description Plansmith pushes links to the copy here, which opens
for anyone who can already read the plan.
An image past the size limit is not brought over at all. The spec keeps its caption, marked as not
imported, and the check-out card names the file. If a single import carries a lot of pictures, the
last few arrive without a written description, and the card tells you how many.
Jira is the first issue tracker you can import from. Linear and Radial remain push destinations for
now. See [Push to your issue tracker](/docs/push-to-your-issue-tracker).
---
# Instructions, skills or formats?
Three ways to make the agent work the way your team works, and which one you want.
Source: https://www.plansmith.co/docs/instructions-skills-or-formats
Plansmith gives you three ways to shape how the planning agent behaves. They look similar from a
distance and they do quite different jobs.
The short version: **instructions are rules, skills are procedures, formats are shapes.**
| Use | For | The agent reads it |
| ---------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| **Instructions** | Standing decisions it should always follow, like "mobile ships after web, stop proposing it". | Every turn. |
| **Skills** | A playbook for a situation: how you write release notes, how you run a readiness review. | When the situation calls for it, or when you type `/` and pick one. |
| **Formats** | The shape of the documents it writes, meaning the sections every Spec and Epic has. | Whenever it writes a Spec or an Epic. |
If you find yourself repeating the same correction in every conversation, that is an instruction.
If you are explaining a process, that is a skill.
## Why the reading model matters [#why-the-reading-model-matters]
Instructions are injected into **every** turn, so they shape a decision before the agent thinks.
That is why they must stay short, and why they are the right home for a standing rule.
Skills and formats are read **on demand**. The agent only sees a one-line summary of each until it
decides one is relevant, which is why a skill can be long and detailed without slowing every
conversation down.
## Where each one applies [#where-each-one-applies]
All three can be set for the whole company or for a single project, and the narrowest one wins.
Instructions go further: you can also set them just for yourself, or just for one plan.
| | You | A plan | Project | Company |
| ---------------- | --- | ------ | ------- | ----------- |
| **Instructions** | Yes | Yes | Yes | Owners only |
| **Skills** | No | No | Yes | Owners only |
| **Formats** | No | No | Yes | Owners only |
**Spec format and Epic format appear in your Skills list, but you edit them under Formats.** They
are listed there because that is how the agent reaches them.
## Who can change what [#who-can-change-what]
Anything set for the whole company changes every conversation for everyone, so only owners can save
it.
Company instructions go one step further: the agent can **suggest** a change as it learns how you
work, but an owner has to approve it before it takes effect. The agent never writes a skill, at any
level.
Standing decisions, followed in every conversation.
Playbooks the agent opens when they are relevant.
The sections every Spec and Epic is written to.
---
# Members and roles
Who is in your workspace, what each role can do, and what happens to someone's plans when they leave.
Source: https://www.plansmith.co/docs/members-and-roles
Everyone in your workspace holds one of three roles.
| Role | Can do |
| ---------------- | ------------------------------------------------------------------------------------------------------------ |
| **Owner** | Everything a member can, plus billing, members, company instructions, skills and formats, and the audit log. |
| **Member** | Plan, write Specs, connect an issue tracker, and set anything at project level. |
| **Comment-only** | Read and comment. Never edits a plan. |
## Your access is the lower of two things [#your-access-is-the-lower-of-two-things]
Access to a particular plan is the **lower** of your workspace role and your role on that plan.
The consequence worth knowing: giving a Comment-only teammate editor access on a plan does not make
them an editor, because their workspace role is the ceiling. Plansmith refuses that grant outright
rather than accepting it and quietly doing nothing.
See [Sharing a plan](/docs/sharing-a-plan) for the per-plan side of this.
## Inviting people [#inviting-people]
Owners invite by email from **Settings → Members**, choosing the role on the way in. An invite is
the only way into a workspace; there is no domain-based auto-join.
## When someone leaves [#when-someone-leaves]
Removing a member hands their plans to another owner in the same step, so nothing is left without
an owner. You pick the successor as part of the removal.
To find what needs re-homing first, **Settings → All plans** lists every plan in the workspace with
its name, owner and visibility. That view is owner-only and deliberately shows those three things
only: it exists so an owner can administer plans they cannot open, not to give them a way to read
private ones.
Plans are private until you share them.
Your plan, what usage means, and how to add more.
---
# Plan lifecycle
The five states a plan moves through, what moves it, and why you cannot set them freely.
Source: https://www.plansmith.co/docs/plan-lifecycle
A plan has a status, and it moves through five of them in order.
| Status | What it means |
| ------------ | --------------------------------------------------------------------- |
| **Planning** | Being written. The conversation is live and Specs are still changing. |
| **Ready** | You are happy with it. Nothing is pushed yet. |
| **Pushed** | It has landed in your issue tracker at least once. |
| **Building** | Your team is working on it downstream. |
| **Done** | Finished. |
## The transitions are managed [#the-transitions-are-managed]
You cannot jump a plan to any state you like. The order is enforced, which keeps the status
meaningful: a plan marked Building really has been pushed somewhere.
Two behaviours worth knowing:
* **Pushing moves the plan for you.** A plan in Planning or Ready becomes Pushed when you push it.
You do not have to set it yourself.
* **Pushing never moves a plan backwards.** Re-pushing a plan that is already Building leaves it
Building. A later push is an update, not a restart.
## Sub-plans have their own status [#sub-plans-have-their-own-status]
Each sub-plan moves independently. A parent plan sitting at Building can have one sub-plan already
Done and another still in Planning, and that is the normal shape of real work.
There is no automatic roll-up. A parent does not flip to Done because its children are; someone
decides that.
## What status does not do [#what-status-does-not-do]
Status does not gate anything. A plan in Planning can be pushed, and a plan in Done can still be
edited. It is a signal to your team about where the work stands, not a permission system.
For who can see and change a plan, see [Sharing a plan](/docs/sharing-a-plan).
---
# Planning with the agent
How the conversation works, why it researches before it asks, and how to correct a Spec.
Source: https://www.plansmith.co/docs/planning-with-the-agent
Planning happens as a conversation. You describe the business requirement, the agent works, and you
correct it. There is no form to fill in.
## It researches before it asks [#it-researches-before-it-asks]
The agent reads your Context first (the documents attached to this plan, its project and your
team, plus any connected repository), and only then asks you questions.
That ordering matters. An agent that asks first wastes your time on things it could have looked up,
and an agent that never asks invents the answers. You should expect a short pause, then questions
that are specific to your business rather than generic.
## Answer the awkward questions [#answer-the-awkward-questions]
The questions worth answering carefully are the ones about edge cases: what happens in a different
time zone, who gets notified, what the state is after a failure. Those answers become acceptance
criteria, and acceptance criteria are what make a Spec buildable.
If you do not know an answer yet, say so. "We have not decided" is a real answer and the agent will
write the Spec so the decision is visible rather than silently assumed.
## Point at something with @ [#point-at-something-with-]
Type `@` in the message box to point the agent at exactly what you mean instead of describing it.
Nothing is typed first: `@` opens a short menu of the three places things live, each with a count.
| | |
| ----------- | --------------------------------------------------- |
| **Plan** | your epic, your specs, and any prototypes |
| **Context** | the documents on this plan and the ones it inherits |
| **Code** | files in the repositories connected to this project |
Press `→` to walk into one, `←` to come back out. Or skip the browsing and keep typing: the menu
searches all three at once, and it matches loosely, so `authsvc` finds `auth-service.ts`.
Whatever you pick is inserted as plain text, and the row that appears under the box shows what the
agent will actually read. If something you typed by hand does not appear there, the agent will not
find it either.
Mentioning a file does not change what else the agent can see. It reads your whole Context as usual;
`@` only says which part you are talking about right now.
## Correcting a Spec [#correcting-a-spec]
Highlight the part that is wrong and say what you want instead. A small box appears at your
selection; type your note and press Enter. The agent receives the passage along with your note, so
you never have to describe which part you meant.
This works anywhere you read the plan: a spec, your epic, your context sources, and the agent's own
answers in the conversation. Quoting an answer back at it is often the fastest correction of all,
because it lands on the exact sentence rather than the whole reply.
When the change is bigger than one passage, ask in the conversation and name the Spec:
```text
SPEC-4 should also cover weekly schedules. Editing a saved report
changes what the next send contains, not the schedule itself.
```
Either way the agent rewrites that Spec in place, including its acceptance criteria. You can also
edit any Spec directly if you would rather write it yourself.
## Readiness is the signal to watch [#readiness-is-the-signal-to-watch]
Each Spec carries a readiness of **Rough**, **Shaping** or **Ready**. It is the agent's judgement
about whether someone could pick this up and build it.
A plan full of Rough Specs is not a bad plan; it is an early one. Ask the agent what is missing and
it will name the specific gaps rather than rewriting everything.
Readiness is about the Spec, not about you. A Spec can stay Rough because a business decision has
not been made yet, and that is worth seeing rather than papering over.
## When the work is too big [#when-the-work-is-too-big]
If the conversation keeps splitting into topics that need different background material, that is
the signal to break the plan up. See
[Sub-plans and dependencies](/docs/sub-plans-and-dependencies).
---
# Prototypes
Turn a plan into a clickable mockup you can share, comment on, and send back to the agent.
Source: https://www.plansmith.co/docs/prototypes
A plan can render as a **prototype**: a clickable mockup of what it describes, generated from the
Specs themselves.
It exists to make a plan reviewable by people who will not read a Spec tree. A stakeholder who
shrugs at "SPEC-4: schedule a report" will tell you within seconds that the screen never says which
time zone the send happens in.
## Generating one [#generating-one]
Ask for it in the plan conversation. The agent builds the prototype from the plan as it currently
stands, so generate it after the Specs are roughly right rather than at the first draft.
Regenerating it later picks up whatever has changed.
## How the agent builds one [#how-the-agent-builds-one]
It follows the same pass every time. It looks at your linked repository first, so the prototype
matches what you already ship. It walks every spec that has a screen, covers the empty and error
states as well as the working one, checks its work against a fixed list, and only then saves.
That check is why the first version you open is usually complete, instead of arriving with gaps you
have to point out.
## Matching your app [#matching-your-app]
Link a repository and the prototype uses your real colours, type and components. The agent tells you
which repository it matched against, so you can check it picked the right one.
If it cannot match, it says which of three things happened, because they need different answers from
you:
* **No repository is linked.** Link one and the next prototype will match your app.
* **Your linked repositories hold no user interface.** Nothing to match. This is a fact about your
code, not a problem to fix.
* **A repository could not be read.** Its connection needs reconnecting. Your app is there, we could
not see it.
## Revising keeps your comments in place [#revising-keeps-your-comments-in-place]
When the agent revises a prototype, it carries your comment anchors across, so feedback left on an
earlier version still lands where it belongs. Restyling or moving something does not break its
comments.
The agent tells you when an anchor is lost: if a part is removed altogether, the comments anchored
to it lose their place.
## What the agent checks before you see it [#what-the-agent-checks-before-you-see-it]
The agent works through a fixed list before it saves, and the save reports anything it missed back
to it. These are the things on that list:
* Every screen shows the real address it stands for.
* Every screen says whether this plan adds it, changes it, or leaves it alone. When we cannot tell,
it says so rather than guessing.
* Notes from the agent sit outside the mockup, never inside it, so commentary is never mistaken for
the product.
* The flow list dims what is not built yet instead of hiding it.
## Point at something and say what to change [#point-at-something-and-say-what-to-change]
Open the prototype and press the element-select button in its toolbar. The pointer becomes a
crosshair and whatever you hover is outlined, so you can see what you are about to pick. Click the
button, card or heading you mean, type one instruction, and press Enter.
Your instruction lands in the chat box with the element, the screen it sits on and the prototype it
belongs to already named, added after anything you were part-way through writing. Read it, change it
if you want, and press send. Nothing reaches the agent until you do.
It works the same way on the plan's own prototype and on any prototype file in the drawer; on a file
the instruction names that file, so the agent edits the right one.
## Sharing it [#sharing-it]
A prototype has its own share link. Anyone holding that URL can open it, sign-in or not, which is
what makes it useful for showing a customer or an exec.
**A prototype share link sits outside your plan's permissions.** It is a public URL for whoever has
it. Making the plan private later does **not** kill an existing link. Revoke the link itself, and see
[Sharing a plan](/docs/sharing-a-plan).
## Comments come back to the agent [#comments-come-back-to-the-agent]
Reviewers can leave comments anchored to a specific part of the prototype, and you can resolve them
as you work through.
The useful part: a comment can be sent to the planning agent, which reads it as feedback on the
plan and updates the affected Specs. That closes the loop from "this screen is wrong" to a changed
acceptance criterion without anyone transcribing anything.
## Wrapping the prototype builder [#wrapping-the-prototype-builder]
Your team can add its own rules to every prototype without rewriting how prototypes are built. A
wrapper is a company or project skill that **extends** the built-in one; it names the builder's
hooks, so it keeps working when we reword a step.
| Hook | What it adds |
| --------------- | -------------------------------------------------------------------------------------------- |
| `extra-craft` | Your typefaces, spacing and brand rules |
| `extra-screens` | Screens you want in every prototype |
| `extra-notes` | Extra kinds of note beside the two we ship: what did not change, and what happens underneath |
| `extra-checks` | More things to check before saving |
| `save-bar` | Raise the bar the agent holds itself to before saving |
Write this under **Settings → Skills**. Copy it and change the parts in your own words.
**Paste the body only.** The settings form writes the header for you. Pasting a whole file that
carries its own header gives you two, and the inner one quietly becomes body text.
```text
Follow /skills/prototype-builder/SKILL.md exactly. Everything below EXTENDS it.
The pass, the way a prototype is saved and the checks it must pass are unchanged.
[HOOK: extra-craft] - our house style, on every prototype:
- Display face is Söhne, body is Söhne. Never a substitute, never a system font.
- Brand green is a foreground only. It is never a background fill.
[HOOK: extra-screens] - always include, even when the plan does not mention them:
- The printed dispatch note. It is a document, not a screen, so it is drawn as a
sheet with no browser chrome.
[HOOK: extra-notes] - add one register beside the two we ship:
- "Warehouse impact": what changes for a picker on the floor.
[HOOK: extra-checks] - also check before saving:
- Every price is shown with its currency. A bare number has been misread twice.
- Every date is unambiguous (12 Mar 2026, never 03/12/26).
[HOOK: save-bar] - saving additionally requires that every screen showing stock
also shows its as-of time. This RAISES the bar. It never lowers it.
```
### What a wrapper cannot do [#what-a-wrapper-cannot-do]
A wrapper adds rules and raises the bar. It cannot lower one. It cannot:
* **Change how a prototype is saved.** Saving has one door, and it has to be one door: it stores the
file, records the prototype, and stamps which specs it was built from, all together. Save any
other way and the file exists with nothing pointing at it, so the Prototypes panel opens an empty
tab and you cannot tell what the agent did.
* **Widen where a prototype may load things from, or unpin the icon version.** Both keep a saved
prototype rendering the same way months later.
* **Make a prototype call a server or load real data.** It runs entirely in your browser, on made-up
data. That is what makes it safe to share with anyone holding the link.
* **Remove a check, or lower the accessibility floor.**
If a wrapper asks for any of those, the agent follows the built-in skill and tells you it did.
Who can see a plan, and how prototype links differ.
How to ask for changes once the feedback is in.
The other skill you can wrap, and its own worked example.
---
# Push to your issue tracker
Send the plan to Linear, Jira or Radial, with its hierarchy and dependencies intact.
Source: https://www.plansmith.co/docs/push-to-your-issue-tracker
When a plan is good, push it. Your team keeps working where they already work, and the plan becomes
issues they can pick up.
## Where you can push [#where-you-can-push]
Project, issues and sub-issues nested to any depth, with dependencies as issue relations.
Epic and issues on your Jira site, with the Spec tree mapped to issue hierarchy.
Issues and sub-issues in your Radial workspace.
Connect one in **Settings → Connectors**. Connections are per person: the push happens as you, and
the issues are created by you.
GitHub, GitLab and Bitbucket are **code connectors**, not push destinations. Plansmith reads them
to ground your Specs; nothing is ever written back to them. See
[Connecting a repository](/docs/connecting-a-repository).
## What lands [#what-lands]
Each Spec becomes an issue. The tree becomes issue hierarchy, "needs first" becomes issue
relations, and effort becomes an estimate where the issue tracker has one.
The acceptance criteria go into the issue body as a checklist, which is the part that matters: the
person who picks the issue up gets the definition of done without opening Plansmith.
## Re-pushing updates the same issues [#re-pushing-updates-the-same-issues]
Pushing again updates the items Plansmith created rather than making new ones. Anything your team
creates independently in the issue tracker is untouched.
Plansmith is the place the plan gets written, so the habit that works best is still to change the
plan here and push it, rather than editing a pushed issue's description in the issue tracker and
expecting Plansmith to pick that up. But an edit made over there is no longer lost silently. See
below.
## What happens when someone else edited it [#what-happens-when-someone-else-edited-it]
Available on **Jira** today. Reading an issue back is what makes this possible, and Jira is the
one issue tracker Plansmith can currently read as well as write. Pushes to Linear and
radial.build still overwrite, as described above.
Before Plansmith writes anything, it checks what changed in your issue tracker since the two sides
last agreed. Most of the time nothing has, and the push goes straight through.
If somebody edited an issue you had pushed or imported, **the push stops before writing** and the
agent walks you through it. For each one it shows what they changed and what you changed since the
last agreed version, and you decide: keep both, keep theirs, keep yours. What you decide becomes an
ordinary edit to the spec, so you can read it in the plan before anything leaves Plansmith. When
every item is settled, one button sends the lot.
Three things worth knowing:
* **A status change is not a conflict.** Someone moving your issue to In Progress will not stop a
push. Only an edit to the words will.
* **Nothing lands half-done.** The push stops *before* it writes, so there is no partial update to
undo, and nothing of your teammate's is lost while you decide.
* **A deleted issue is not recreated silently.** If an issue you pushed has been deleted in the
issue tracker, Plansmith asks what you want rather than quietly making a duplicate.
If the issue tracker cannot be reached, the push also stops. "We could not check" is not the same
as "nothing changed", and guessing wrong there costs somebody their work.
## Work that is already in Jira [#work-that-is-already-in-jira]
You do not have to start it over here. Bring the epic into a plan, refine it, and push it back to
the same issues. See [Import from your issue tracker](/docs/import-from-your-issue-tracker).
## No issue tracker yet [#no-issue-tracker-yet]
You can export the plan instead and connect an issue tracker whenever you like. Nothing about writing a
plan depends on the connection, and the export carries the same Specs and acceptance criteria.
---
# Quickstart
From a business requirement to a plan in your issue tracker, in about five minutes.
Source: https://www.plansmith.co/docs/quickstart
You do not need an issue tracker connected to finish this. You can export the plan instead and
connect Linear, Jira or Radial later.
### Create a project [#create-a-project]
From your dashboard, create a project and give it the name your team already uses for this product.
A project holds plans, and later it holds the connection to your issue tracker.
### Write the business requirement [#write-the-business-requirement]
Open a new plan and describe what the business needs, in plain English. No format, no template. A
paragraph is enough:
```text
Customers keep emailing us to ask for last month's numbers as a PDF.
We want them to save a report once and have it arrive on a schedule.
```
Write what the business wants, not the implementation. Deciding how is the agent's job, and yours
to correct.
### Answer the agent's questions [#answer-the-agents-questions]
The agent researches your Context first, then asks you what it still needs. Expect two or three
questions, and expect them to be the awkward ones: what "monthly" means in someone else's time
zone, who keeps receiving a report when the person who set it up leaves, what a schedule does when
the report behind it changes.
This step is what makes the Specs specific. Skipping it produces a plan that reads well and cannot
be built.
### Review the Specs [#review-the-specs]
You now have a plan: a tree of Specs, each with acceptance criteria, an effort and a readiness of
Rough, Shaping or Ready.
Read the acceptance criteria first, not the titles. That is where a plan is right or wrong. Ask for
changes in the same conversation ("SPEC-3 should cover weekly as well as monthly") and the agent
rewrites it in place.
### Push to your issue tracker [#push-to-your-issue-tracker]
Connect Linear, Jira or Radial, then push. The plan lands as issues and sub-issues with its
hierarchy and its "needs first" dependencies intact, and every Spec keeps its acceptance criteria
in the issue body.
## What you end up with [#what-you-end-up-with]
A plan of record in your issue tracker, and a conversation in Plansmith you can come back to when
the plan needs to change. Re-pushing updates what Plansmith created.
Team, Project, Plan and Spec: the four words the rest of the docs use.
Linear, Jira and Radial, and what re-pushing does to edits.
---
# Readiness review
Score how build-ready one spec is, get the gaps as questions you answer and fixes you approve, and keep the findings in a file.
Source: https://www.plansmith.co/docs/readiness-review
A **readiness review** looks at one spec and tells you whether it is ready to build. Ask how
build-ready something is, paste a requirement you already have, or type `/readiness-review`.
Ready means a developer who was not in the conversation could build it and know when they were
done. Longer is not readier: a long spec full of vague criteria is less ready than a short one with
concrete ones.
## What it looks for, and what it leaves alone [#what-it-looks-for-and-what-it-leaves-alone]
It hunts what the product does, for whom, under which rule, and what happens when things go wrong.
It does not raise endpoint shapes, data columns or library choices. Those belong to the team
building it, and raising them here hands you homework that was never yours.
One exception: when the interface itself is the product, and people outside build against it, a
missing error or an unstated limit is a real gap and the review says so.
## What you get back [#what-you-get-back]
Two kinds of finding, kept apart, because mixing them is what makes a review unusable.
**Open questions** (`OQ1`, `OQ2`) only you can answer: what should happen, to whom, in what order.
Asked in plain words, so you never need to open anything to answer one.
**Findings** (`F1`, `F2`) the agent can close itself by rewriting an acceptance criterion. Each one
quotes the phrase at fault and gives you the concrete replacement, so you are approving a fix rather
than doing one.
Those handles are how you reply. "Here's OQ1." "Apply F2."
## Where the findings land [#where-the-findings-land]
In a file, at `context/readiness-reviews/SPEC-12.md`, one per spec, rewritten each time you review
that spec. You open it the same way you open any file the agent writes, from the plan's file drawer.
A verdict in the chat scrolls away. A file is something you work on together, and it is still there
weeks later when someone who was not in the conversation opens it.
Review the same spec again and a handle keeps its number for the life of that spec. Anything you
settled moves to a Resolved section that says what settled it and where it landed, so a handle never
quietly disappears and a number is never reused.
## The summary table [#the-summary-table]
Five rows, every time, so two reviews of the same spec can be compared:
| Row | What it counts | Third cell |
| ------------------------------- | ---------------------------------------------------------------------- | ----------------------------- |
| Behaviors with a criterion | Everything the spec promises, and whether a criterion pins it | The handles that close it |
| Criteria that could fail | Criteria two people could disagree about the outcome of | The handles that close it |
| What happens when it goes wrong | How many of empty, failure, and not-allowed the spec answers | Which of the three is missing |
| Inconsistencies | Two statements that cannot both be true, or a clash with the prototype | What agreed |
| Open questions | How many need your answer | Which carry over |
Every row has a third cell naming the handles that close it, which is what the `extra-rows` example
below appends to.
A count with a denominator reads "7 of 9" rather than a percentage, because the denominator is
the honest part. Inconsistencies and open questions are a plain number.
The verdict is a word, never a score: **Rough**, **Shaping** or **Ready**, the same three the rest
of the product shows.
A clean review still writes the whole file: the verdict, all five rows, "Open questions: 0", and the
full walk through what was checked. A review that always finds problems is one nobody trusts, and a
clean review with no evidence is one nobody can verify.
## Extending it for your team [#extending-it-for-your-team]
Your review may have to check something a general one cannot know about: a regulator you answer to,
a legacy system every change touches, a document your client's contract requires. You can wrap this
skill with your own.
A wrapper is a company or project skill that **extends** this one rather than replacing it. It does
not repeat the pass. It names the review's hooks, so it keeps working when we reword a step.
| Hook | What it adds |
| ----------------- | --------------------------------------- |
| `extra-criteria` | More to look for while reading the spec |
| `extra-questions` | Questions to always ask |
| `ready-bar` | Raise what Ready requires |
| `extra-rows` | Extra rows below the five |
| `extra-sections` | Extra sections in the findings file |
Rows and sections are separate on purpose: the five rows are comparable across every team's reviews,
so a wrapper appends below them and never renames or reorders them.
### A worked wrapper [#a-worked-wrapper]
Write this under **Settings → Skills**. Copy it and change the parts in your own words.
**Paste the body only.** The settings form writes the header for you. Pasting a whole file that
carries its own header gives you two, and the inner one quietly becomes body text.
```text
Follow /skills/readiness-review/SKILL.md exactly. Everything below EXTENDS it.
The pass, where the findings go and the shape of that file are unchanged.
[HOOK: extra-criteria] - also look for:
- A rule taken from regulation with no source cited. Name it, cite where it
comes from, or record it as an open question.
- A change to shared billing behaviour described only as a delta ("as today,
but..."). Write what "today" is into the spec.
[HOOK: extra-questions] - when the spec touches money, always ask:
- Which of the two customer types does this apply to, and what happens to
the other one?
[HOOK: ready-bar] - Ready additionally requires that every rule taken from
regulation is cited in the spec. This RAISES the bar. It never lowers it.
[HOOK: extra-rows] - append below the five fixed rows:
| Rules cited | n of N | name the handles for the uncited ones |
[HOOK: extra-sections] - append to the findings file:
## Regulation
One line per rule the spec relies on: the rule, where it comes from, and
whether the spec states it or assumes it.
```
### What a wrapper cannot do [#what-a-wrapper-cannot-do]
It adds criteria, questions, rows and sections, and it can raise the bar for Ready. It cannot lower
that bar, send the findings anywhere but the file, or change that file's shape. A team's extra rigor
must not cost the findings file its one readable form.
If a wrapper asks for any of those, the agent follows the built-in skill and tells you it did.
The other skill you can wrap, and its own worked example.
The three tiers, and how to write one.
---
# Sharing a plan
Plans are private until you share them. Who can see one, who can edit it, and the one link that sits outside the rules.
Source: https://www.plansmith.co/docs/sharing-a-plan
**A plan is private to whoever created it.** Nobody else in your workspace can see it, including
owners, until it is shared.
That is the default because a half-written plan is a draft, and a draft that everyone can read is a
draft nobody writes honestly.
## Three ways a plan is visible [#three-ways-a-plan-is-visible]
| | Who can see it |
| ------------------------------- | -------------------------------------------- |
| **Private** | You, plus anyone you share it with. |
| **Team** | Everyone in the workspace. |
| **Shared with specific people** | The teammates you name, as viewer or editor. |
Sharing works on the **root** plan and covers its whole sub-plan tree. You do not share sub-plans
one by one.
## Your access is the lower of two things [#your-access-is-the-lower-of-two-things]
Someone's access to a plan is the **lower** of their workspace role and their role on that plan.
The consequence that surprises people: giving a Comment-only teammate editor access on a plan does
not make them an editor. They can still only read and comment, because their workspace role is the
ceiling. Plansmith refuses that grant rather than accepting it and quietly doing nothing.
For what each workspace role can do, see [Members and roles](/docs/members-and-roles).
## Prototype links are different, on purpose [#prototype-links-are-different-on-purpose]
A [prototype](/docs/prototypes) share link is a public URL. Whoever holds it can open the
prototype, signed in or not.
Switching a plan back to Private does **not** revoke an existing prototype link. The link was
published deliberately, so it is revoked deliberately: open the share dialog and revoke it there,
where you can also see how many live links exist.
Creating, rotating or extending a prototype link requires ownership of the plan. Revoking one only
needs edit access, because revoking can only ever narrow who sees it.
---
# Skills
Short playbooks that teach the agent how your team does a particular job, read when they are relevant.
Source: https://www.plansmith.co/docs/skills
A **skill** is a short guide that teaches the agent how your team does something: how you write
release notes, how you size work, what your readiness review covers.
Each one has a name, a line describing when it should be used, and a body. The agent only sees that
one line until it decides the skill is relevant, then it opens it. So a skill can be as long as it
needs to be without slowing down every conversation.
## Using one [#using-one]
Type `/` in the message box and pick a skill to apply it deliberately. Otherwise the agent reaches
for one on its own when the situation matches its description.
That description is the whole interface. "Whenever drafting release notes or launch announcements"
gets opened at the right moment; "notes" does not.
## Three tiers [#three-tiers]
| Tier | Who it is for | Who can write it |
| ---------------- | -------------------------------- | ---------------------- |
| **Built in** | Ships with Plansmith, read-only. | Nobody, they are ours. |
| **Company** | Everyone in the workspace. | Owners. |
| **This project** | Only that project. | Members and owners. |
## What ships built in [#what-ships-built-in]
Where new work belongs: Specs here, a sub-plan, or beside this plan.
The shape every Spec is written in.
How a plan's Epic is written, the body your issue tracker receives.
Scores how build-ready one spec is; findings land in a file.
Builds a clickable prototype of the plan.
Sends parallel research agents at a question; the report lands in Context.
Argues the other side of one spec before you commit to it; findings land in its review file.
Sends the plan to your issue tracker, and stops without writing if a teammate changed one of
the issues first.
Works through what your team changed, one item at a time, so a stopped push can go.
**Spec format and Epic format are edited under [Formats](/docs/formats), not here.** They appear in
this list because that is how the agent reaches them, and if your team customizes either one, the
agent reads your version instead of ours.
## Wrapping a built-in skill [#wrapping-a-built-in-skill]
A company or project skill can **extend** a built-in one instead of replacing it. Your wrapper adds
your team's own rules; the built-in pass, its output and its safeguards stay exactly as they are.
Two skills can be wrapped today: **Readiness review** and **Prototype builder**.
A wrapper names the built-in skill's hooks rather than copying its steps, so it keeps working when
we reword one. Each skill's page lists its hooks and carries a worked wrapper you can copy:
[Readiness review](/docs/readiness-review) and [Prototypes](/docs/prototypes).
A wrapper can add rules and raise the bar. It cannot lower one. If a wrapper asks the agent to relax
something the built-in skill states, the agent follows the built-in skill and tells you it did.
**Paste the body only.** The settings form writes the header for you. Pasting a whole file that
carries its own header gives you two, and the inner one quietly becomes body text.
## The agent never writes a skill [#the-agent-never-writes-a-skill]
At any tier. It can propose an [instruction](/docs/agent-instructions) and it can adjust a project
[format](/docs/formats) when you ask it to in conversation, but a skill is always written by a
person.
That is deliberate: skills are procedures the agent then follows, so a skill it could write itself
would be a loop with nobody in it.
Write one under **Settings → Skills**.
---
# Sub-plans and dependencies
When work belongs in this plan, when it needs its own sub-plan, and how to say one thing needs another first.
Source: https://www.plansmith.co/docs/sub-plans-and-dependencies
There is one rule for deciding whether new work belongs in the plan you are in or in a sub-plan of
its own, and it is about Context, not about size.
**Same context, same plan. Its own context, its own sub-plan.**
Specs share their plan's Context. So work that needs its **own** background material (its own
regulation, its own vendor API docs, its own research) belongs in a sub-plan, because a sub-plan
is the thing that can hold sources.
A plan about checkout that grows a section on tax compliance is the usual example. The tax work
needs the tax rules attached; the checkout work does not want them in every prompt. That is a
sub-plan, not five more Specs.
## What a sub-plan gets [#what-a-sub-plan-gets]
A sub-plan is a plan in every respect. It has its own conversation, its own status, its own Specs,
and it pushes to your issue tracker on its own schedule.
It **inherits** its ancestors' Context automatically and read-only, so you never re-attach the same
document twice.
## Sibling sub-plans cannot see each other [#sibling-sub-plans-cannot-see-each-other]
Two sub-plans of the same parent are isolated. Neither one's conversation knows the other exists,
and that is deliberate: a plan that can see its siblings starts making claims about work you did
not ask it to think about.
The one exception is when you create a dependency between them, below.
## Needs first [#needs-first]
Any plan or Spec can declare that it needs another one first. That is how you say "the API has to
exist before the UI can call it".
Dependencies do three things:
* They order the work, and the order survives the push to your issue tracker as issue relations.
* They are cycle-checked. A dependency that would create a loop is refused when you make it, not
discovered later.
* At **plan** level, a needs-first edge also imports that plan's Context and Specs, so the
dependent plan can actually see what it is waiting on.
That import is direct only. If A needs B and B needs C, A sees B, not C.
What Context is, and how inheritance flows down the tree.
The statuses a plan moves through, and who moves them.
---
# What is Plansmith
Plansmith turns a business requirement into a tree of dev-ready Specs, then pushes them to your issue tracker.
Source: https://www.plansmith.co/docs/what-is-plansmith
You describe what the business needs in plain English. A planning agent researches what it already
knows about your work, asks you the questions it still needs answered, and writes the result as a
**plan**: a tree of Specs, each one specific enough for a developer to build from.
Then you push the plan to Linear, Jira or Radial, and your team works where they already work.
## What it is for [#what-it-is-for]
The gap Plansmith fills is between "we should do this" and "here is a ticket someone can pick up".
That gap is usually crossed by one person writing tickets late at night, and it is where most of
the ambiguity in a project survives: the ticket says what to build but not what done means, and
nobody notices until review.
A Spec written here carries its acceptance criteria with it. That is the point.
## What it is not [#what-it-is-not]
It is not an issue tracker. Yours stays the plan of record, and Plansmith is where the plan
gets good before it lands there.
It is not a project management tool. There are no burndown charts, no sprint boards and no status
reports. Plansmith stops at the Spec; your team executes downstream.
It does not write your code. It can read your codebase to ground what it writes, but the output is
a plan, not a pull request.
## How the pieces fit [#how-the-pieces-fit]
Team, Project, Plan and Spec: the four words the rest of these docs use.
From a business requirement to a plan in your issue tracker, in about five minutes.