Plan blocks

Block	What it shows	Written when	Budget
`calls`	The functions a change reaches, marked new, changed or removed	The change crosses functions or files	3 blocks of 12 lines
`code`	A few lines of code with a note pinned under one	One line needs a note to be understood	12 lines a sketch, 3 pins
`states`	A lifecycle you click through	The change adds or alters a lifecycle	2 blocks of 8 states and 10 arrows
`screen`	A rough sketch of a screen	The change alters what a person sees	2 screens of 14 parts and 5 dots

Each block is a fenced code block in plan.md, so it reads as plain code on GitHub or in a terminal, and the spec viewer draws it as a card. A block the viewer can’t parse stays a code block.

The Companion plan step picks the blocks a change needs after it writes the plan, records the pick, then runs a check on every block. A change sized simple gets none. If it skips a block you wanted, ask for it and run plan again, or write the block yourself.

The stock Spec Kit workflow doesn’t write blocks. To add one there, attach its node after the plan document is written, with call-paths, code-pins, states or screens as the ref. Workflow Builder and hooks covers how hooks attach.

commands:
  plan:
    hooks:
      after:
        plan-doc:
          - { type: node, ref: call-paths }

Calls

```calls Offline favorite
  FavoriteArticleBriefButton() @ src/features/article/favorite-article/favorite-article.ui.tsx:6
~   useFavoriteArticleMutation() @ src/features/article/favorite-article/favorite-article.mutation.ts:9
+     isNetworkError() **new** @ src/shared/api/network-error.lib.ts
+     enqueue() **new** @ src/entities/favorite-queue/favorite-queue.model.ts
```
note: the unfavorite mutation changes the same way.

+ is new, ~ is changed, - is removed, and no mark means the function is on the path and stays as it is. Indent shows who calls whom. The check opens every cited file and reports a missing file or a line past its end.

A calls card titled Offline favorite. One entry function, one changed function tinted amber, and two new functions tinted green, each with its file path. The header counts 2 added and 1 changed. — Green rows are new, amber rows change. Click a path to open the file at that line.

You can comment on a row or strike it, the same way you review any line.

Code

```ts src/entities/article/article.api.ts:44-44 hl=44
    placeholderData: keepPreviousData,
```
pin 44: this line keeps the old key's articles on screen under the new key, so it is the one to delete.

A path with a line range cites real code. The card numbers it from that line, and the check opens the file to confirm the range exists. For code that doesn’t exist yet, write sketch before the path and leave the range off, as in ts sketch src/cart/total.ts hl=2.

A code card for src/entities/article/article.api.ts, line 44. The line is highlighted and a note under it says why it is the one to delete. — One real line, and the reason it matters.

States

```states Waiting change
Queued: Stored offline, waiting to be sent. (start)
Sending: Being sent during catch-up.
Sent: Server accepted it, removed from the list. (final)
Dropped: Server rejected it, removed from the list. (final)
Cancelled: Opposite change made, removed from the list. (final)
Queued -> Sending: online report or launch
Queued -> Cancelled: opposite change on the same article
Sending -> Sent: server accepts
Sending -> Dropped: server answers with an error
Sending -> Queued: no response, change stays waiting
grid:
Queued | Sending | Sent
.      | Cancelled | Dropped
```

The grid: rows place the states, up to 4 columns by 3 rows, and a . leaves a gap. A state can name a screen with shows <name>, and picking that state draws the screen under it. The check stops on a state nothing reaches and on a dead end that isn’t marked (final).

A states card titled Waiting change with five states: Queued, Sending, Sent, Cancelled and Dropped. Sending is picked, and below the diagram its sentence and its three next moves are listed. — Pick a state to read what it means and where it goes next.

Screens

```screen header Header
row:
  text: Conduit
  list: Home | New Article | Settings | Profile
  chip: Waiting changes count (new) (1)
```
1: **Plain number.** Shown only for a signed-in reader and hidden when the count is zero.

A screen is built from title, row, text, chip, button, field and list, one part per line, indented two spaces to sit inside a row:. Mark a part (new) or (changed), and add a numbered dot such as (1) to give it a note below the block.

A screen card titled Header. A row holds the app name, a list of four links and a new chip edged in green with a numbered dot. A note under the sketch explains the chip. — A new part is edged in green. Each numbered dot has a note.

Full grammar

Every rule the check applies, and how to make it a gate: calls, code, states, screens.