# Agent plan

> Before an agent acts, it lists its steps, what each one reads and what each one changes. The person edits, skips or approves each step.

Source: https://kwark.space/designSystem/components/agent-plan

## Usage

### What it is
A short ordered list of what the agent proposes to do, shown before it does anything. Each step names its object in Kwark’s words and says whether it **reads only**, makes **proposals** or **changes** something. A step that changes work starts unticked. The primary counts what will run: **Run 2 steps**.

### When to use
- Any request that takes more than one step or touches more than one module: tagging the breakdown from the script, drafting a call sheet from the schedule, renaming a character everywhere.

### When not to use
- A single proposal on a single line: that is the [Suggestion panel](https://kwark.space/designSystem/components/suggestion-panel.md).
- For writing or judging story. A step that would draft a scene, rewrite a line or assess the work is never in a plan (Decision 0002).
- For anything outside the project or anything that affects other people (sending, issuing, sharing). Those stay the person’s own act (Decisions 0020, 0042).

### Writing
- Title: the task in the person’s words, with its scope: *Tag props in Scenes 12–14*.
- Steps start with a verb and name the object. The effect line is one of *Reads only*, *Proposals, for your review*, *Changes the Breakdown*.

## Style

### Anatomy

1. **Card**: `--k-surface`, 1px `--k-line`, 10px corners, 16px padding.
2. **Header**: title Raleway 16px 600; count line 12px `--k-text-2`.
3. **Step**: 44px minimum, checkbox 16px (`accent-color` the project accent), name 14px 500, effect 12px. A step that changes work has the effect in `--k-warn`.
4. **Footer**: quiet Cancel, primary *Run N steps*.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-surface` | #ffffff | #1a1a1a |
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-warn` | #8a5a00 | #d8a44a |
| `--k-accent` | #98633f | #98633f |
| `--k-radius-card` | 10px |  |
| `--k-font-display` | 'Raleway', 'Poppins', system-ui, sans-serif |  |
| `--k-fs-title` | 16px |  |
| `--k-fs-meta` | 12px |  |

## Code

### React

Use the HTML below with `kwark.css`. The example shows the markup and styling. Supply any application behavior described on this page.

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<section class="kw-plan" aria-label="Plan: tag props in Scenes 12–14">
  <header><h3>Tag props in Scenes 12–14</h3><p>3 steps · nothing changes until you run them</p></header>
  <ol>
    <li><label class="kw-plan__step"><input type="checkbox" checked><span><b>Read Scenes 12–14</b><small>Reads only</small></span></label></li>
    <li><label class="kw-plan__step"><input type="checkbox" checked><span><b>Propose prop tags from the action lines</b><small>Proposals, for your review</small></span></label></li>
    <li><label class="kw-plan__step is-changes"><input type="checkbox"><span><b>Add the accepted tags to the Breakdown</b><small>Changes the Breakdown · skipped</small></span></label><button class="kw-text-button" type="button"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M21.2 6.8a1 1 0 0 0-4-4L3.8 16.2a2 2 0 0 0-.5.8l-1.3 4.4a.5.5 0 0 0 .6.6l4.4-1.3a2 2 0 0 0 .8-.5z"/></svg><span>Edit step</span></button></li>
  </ol>
  <footer><button class="kw-button kw-button--quiet" type="button">Cancel</button><button class="kw-button kw-button--primary" type="button">Run 2 steps</button></footer>
</section>
```

## Accessibility

### Keyboard
| Key | Does |
|---|---|
| Tab | Each step’s checkbox, its Edit step, then the footer. |
| Space | Ticks or skips a step. |
| Escape | Cancel; nothing runs. |

### ARIA
- An ordered list inside a section labelled by the title. The run button’s name updates with the count; announce the change politely.

## For agents

### Rules

- **Never** include a step that writes, rewrites or judges story; every step finds, moves, carries, converts or measures the writer’s own material (Decision 0002).
- **Must** show the plan before any step runs.
- **Must** label each step Reads only, Proposals or Changes, and start every Changes step unticked.
- **Never** include sending, issuing, sharing or deleting as an agent step; those stay a person’s act.
- **Always** let each step be skipped or edited.
- **Must** count the steps that will run in the primary button.

### AI readiness test

**Task:** Plan how the agent will build Day 3's call sheet from the schedule.

**Give the agent:** This page, Decision 0020 (numbered revisions), Agent activity.

**Constraint:** The call sheet for Day 3 was issued as Rev 1.

**A reliable answer:**
- Lists reading the schedule, proposing the sheet as a draft Rev 2
- Starts any step that changes the call sheet unticked
- Excludes issuing Rev 2 from the plan
- Counts the steps in Run
