# The Skill

Embed this file in a repo so Claude Code, Codex, or other MCP agents follow Plan Desk conventions. `plandesk connect` writes the same content to `.plandesk/skill.md` and references it from `CLAUDE.md`.

Copy to your repo as `.plandesk/skill.md` or add to agent instructions. Keep it committed — no secrets.

---

# Plan Desk MCP Instructions

## Setup

At the start of any session where Plan Desk may be used, list the available
Plan Desk MCP tools before calling them. Do not assume tool names or parameter
shapes; if expected tools are missing, say so before proceeding.

Never guess or hardcode a Plan Desk project, task, or document ID. Resolve the
project as below; look up tasks/documents by name and use the returned ID.

## Resolving the project

1. Read `.plandesk/config.json`. If `projectId` is present, use it. Stop here —
   do not ask which project.
2. (Fallback, only if no config file) check conversation history for a named
   project; then the working-directory name for a close match; then an explicit
   name in the request.
3. Single clear match → act directly. Multiple → show options and ask.
   None → say so and ask.

## Standing up a plan

When asked to plan a project, feature, or RFC from scratch, prefer the one-shot
`scaffold_project_from_plan` tool over many separate calls: it creates the
project, all tasks, their dependency edges, and linked spec documents in a
single atomic call. Give each task a stable `key` (a slug you choose) and
reference those keys in `edges` (`from`/`to`) and in a document's `link_to`.
The server resolves keys to real IDs and returns a `key_to_id` map. Use the
granular `create_task`/`create_edge`/`create_document` tools when ADDING to an
existing plan; use `scaffold_project_from_plan` to build a new one.

## Task creation

- Labels: short, imperative, outcome-focused — "Verb Noun in Location".
  The label must make clear what "done" looks like.
- Status at creation: `todo` (defined, ready) or `scope` (needs design/sizing).
  Never create a task as `in_progress`.
- Non-trivial tasks REQUIRE a description with:
  1. **Problem** — what must change; reference class/method names, never line numbers.
  2. **Action Items** — specific, independently completable steps.
  3. **References** — linked documents or related tasks.
- Before creating, check for an existing task covering the same work; prefer
  updating/linking over duplicating.
- Creating several tasks: space ~200 units apart, group related, place blockers
  above what they block.

## Documents

- Title prefix: `Investigation:`, `Scope:`, `Design:`, or `Fix:`.
- Include a `Status:` line near the top: "Ready to implement",
  "Open — requires investigation", "Ready for review", or "Superseded".
- After creating a document, link it to its primary task in the same step.

## Edges

- Connect related tasks with labeled edges. Prefer the vocabulary:
  `blocks`, `depends_on`, `unblocks`, `feeds`, `clarifies`, `enables`, `supports`.
- When you discover a new dependency while working, add the edge.

## Executing the plan

To work a plan, do not guess what is next — call `get_next_task`. It returns the
next actionable `todo` task (one whose prerequisite tasks are all `done`), plus
the `blocked` tasks and what each is `waiting_on`. The loop:

1. `get_next_task` → the next unblocked task.
2. Read its linked document before changing anything.
3. `update_task` to `in_progress`, do the work, then `update_task` to `done`.
4. Repeat until `get_next_task` reports no actionable task.

Edge direction drives sequencing: `from → to` with most labels (`blocks`,
`feeds`, `enables`, …) means `from` finishes before `to`; `depends_on` reverses
it (`from depends_on to` ⇒ `to` first). Add edges so dependencies sequence right.

## Keeping the board true

The board is only useful when it matches reality. Two standing rules:

- **Atomic status updates** — flip a task's status in the same step as the work
  event it reflects, never in a batch at the end: `update_task` to
  `in_progress` the moment you start, `done` the moment the work is verified,
  back to `todo` (or `scope`) if you stop without finishing. At any instant the
  board should show what is actually happening right now.
- **Reconcile against reality** — at the start of a session, after any long
  break, and before reporting a plan finished, sweep the whole board against
  the actual state of the work: recent commits, the working tree, what is
  verifiably built and shipped. Fix every mismatch with `update_task` — work
  that is done but not `done`, tasks `in_progress` that nobody is working on,
  planned tasks the code shows are already built or obsolete. Note non-obvious
  corrections in the task description or a document comment so the drift and
  its fix are traceable.

## Comments

People leave comments on documents in the UI to give you feedback or direction.

- At the start of a session, and after finishing a task, pull open feedback with
  `list_comments` (by `project_id`, optionally one `document_id`). By default you
  get unresolved comments.
- Address each comment, then `resolve_comment` to close the loop — resolving
  updates the commenter's UI live.
- Use `add_comment` to leave a suggestion or question on a document for a person.

## Agent runs

1. Start a run at the beginning of any multi-step Plan Desk operation.
2. Record progress after each meaningful unit of work (not every tool call).
3. Complete or fail the run before the session ends — never leave one open.

## Never do

- Guess or hardcode IDs.
- Batch status updates for the end of a session — statuses change atomically
  as the work happens.
- Leave a task `in_progress` that nobody is actively working on.
- Reference line numbers in tasks or documents.
- Create non-trivial tasks without a description.
- Set a task to `in_progress` at creation.
- Skip the duplicate check before creating a task.
- Delete Plan Desk tasks or documents (there is no delete tool by design).
- Leave open document comments unaddressed — read them with `list_comments` and
  `resolve_comment` once handled (resolving replaces deleting).
- Leave an agent run open at session end.
- Create a document without linking it to a task.