---
name: sidecars-plans
description: Write and iterate a plan as a Sidecars document — where it lives, a template proportional to the task, review rounds over comment threads, version-pinned approval, and hand-off. Use when asked to write a plan, proposal, spec or design in Sidecars, or to address the review on one.
compatibility: Needs the Sidecars MCP server connected (https://mcp.sidecars.ai/mcp) and the sidecars-documents skill.
metadata:
  homepage: https://docs.sidecars.ai/skills
---

# Write and iterate a plan in Sidecars

This skill uses the **sidecars-documents** skill for every read, edit and
comment step. If it is not installed, run
`npx skills add https://docs.sidecars.ai` (or tell the person to), then
continue. The plan is the document; the review happens in its comment
threads; approval is a person's explicit statement, pinned to a version.

## 1. Where the plan lives

Create it in the room, pod or library section the person named. If they did
not say, ask once rather than guess: a plan in the wrong place is invisible
to its reviewers. Use `create_document` with `title: "<slug> — plan"`,
`idempotency_key: "plan:<slug>"`, and the markdown body. Reply with the
document URL (`https://sidecars.ai/artifacts/<document_id>`), the id and the
`version`.

## 2. Template, proportional to the task

Always start with a Status line, then a one-sentence outcome, then the
end behaviour as a short bullet list: what happens when, and what does not
change. Detail goes beneath, never above.

**Light** (a change one person can hold in their head):

```markdown
**Status: draft — under review.**

One sentence: <outcome>.

## End behaviour
- …

## Acceptance criteria
- …

## Unresolved decisions
- …
```

**Detailed** (several parts, more than one reviewer, or work someone else
will pick up): add Context and prior art, Design, Alternatives considered,
a task list where each task has an independently testable outcome, Risks,
and Verification. A plan that changes data shapes shows the actual shape
(the real definition in a code block, a diagram of how the pieces relate),
not a prose summary of it.

Before calling a draft ready, do the fresh-reader check: would someone
without your context find the assumptions and the unresolved decisions
without asking you?

## 3. Review rounds

When asked to address the review, run the sidecars-documents review loop:
read the open threads, evaluate each one, edit the anchored passage, read
back, reply, resolve — and leave open what only a person can settle. Say at
the end which threads are resolved, which are open and why, and the new
version.

Comments resolved is never approval. Do not treat an empty open-thread list
as a go-ahead.

## 4. Version-pinned approval

Approval is a person saying so — in a comment thread, in the room, or to
you directly. Record it in the Status line and nowhere else:

```markdown
**Status: approved at version <N> by <name>, <date> (<where>).**
```

Any meaningful change after approval flips the Status back to
`draft — under review` and says what changed. Small fixes (typos, links)
can note themselves in the Status line without reopening review.

## 5. Hand-off

Where a team keeps approved plans is the team's policy, not this skill's.
If asked to export, use `export_document` with `format: "markdown"` and put
provenance at the top of the exported file:

```markdown
Source: https://sidecars.ai/artifacts/<document_id> · version <N>
```

so anyone reading the copy can find the living document and see whether it
moved since.