Start

---
name: start
description: Orient a fresh session before touching any file — read the current-state file, the relevant half's own guidance, and that half's memory index, then verify live facts with the plugin's own `status` verb instead of trusting the documents. Use at the start of a session, when picking up a new task or branch of work, or when the user asks to start, orient, or "what's next".
---

# Start

Orienting, not working. Do not edit code or memory during this — the job is
to find out where things stand and agree what happens next, and a clean
session has no conversation history to fall back on, only what this skill
reads.

See `agent-memory` for what a note, an index, and evidence mean; this skill
only says which of them to open and in what order.

The commands below call floppy's dispatcher, which ships with the plugin and
has no copy in this repository. The harness names this skill's own base
directory when it loads it — `Base directory for this skill:
<plugin>/skills/start` — and the dispatcher is `scripts/run` two directories
above that. Write that absolute path wherever a command says `<plugin>`.

If that line is not there — a harness that does not print it — do not guess a
cache path. `$CLAUDE_PLUGIN_ROOT` and `$CURSOR_PLUGIN_ROOT` are worth trying
first, and a checkout the human can name is worth asking for; a guess whose
failure mode is running the wrong copy of the plugin is worse than stopping.

## Order

1. **Identify the half the task belongs to.** Halves are directories under
   the configured memory directory (`memory_dir` in `.floppy/config`) — this
   skill does not hardcode their names. Which words route to which half is
   the consumer's own knowledge, kept in their own `AGENTS.md` (or
   equivalent), not here. If the task doesn't name a half clearly, ask which
   one in a single short question rather than guessing.

   A freshly initialized repository has no halves yet — everything lives
   flat under the memory directory, one `MEMORY.md` and nothing to choose
   between. That is not a dead end and not a question to ask: skip this step
   and open `MEMORY.md` directly. Splitting into halves is worth doing once
   the memory has grown enough to need routing, not before.

2. **Read the current-state file whole.** Its path is `statuses_now` in
   `.floppy/config` (a repository default such as `docs/statuses/NOW.md`).
   It is rewritten in place, so it answers "what's true right now" without
   needing history. It holds what is true about the **project**: frozen
   decisions, what is red, what waits on the human, metrics with their marks.
   If it points at a dated journal entry for a detail, open only that section,
   and only if the task needs it — not the whole journal.

   **Then read the personal status, if it exists** — `statuses_personal`,
   which defaults into the private scope at `machines/<name>/NOW.md`. This is
   the working state of whoever sits at this machine: what they were mid-way
   through, what is unfinished, where to pick it up. Missing is the ordinary
   case and not a fault — a repository nobody has left a working note in has
   nothing to say here. Do not go looking for it under a second machine's
   name: that state is theirs and is not about this session.

   Two files rather than one because they behave differently, not to be tidy.
   Project state is shared and changes rarely; personal state changes every
   session and is shared with nobody. Keeping them in one file meant every
   wrap rewrote the shared document to record something private, which is what
   made overlapping sessions collide in it.

3. **Read the half's own guidance** — its `AGENTS.md` or whatever document
   the consumer's routing table names for it.

4. **Open that half's memory index** (`<memory_dir>/<half>/INDEX.md`, or a
   sub-index within it), not the whole memory tree. Read the one or two notes
   that plainly relate to this task; skip the rest.

   **Log each note you actually open**: `bash <plugin>/scripts/run heat <slug>`, the
   slug being the filename without `.md` (several at once is fine). The log
   is what lets pruning lean on "was this ever read" instead of on dates —
   the one time usage was counted by hand, fourteen of twenty notes had
   never been opened, and nothing recorded it. Log real opens only, not the
   index skim; an inflated log is worse than the under-count it replaces.

   **Then, only if the task is not about this project alone, open
   `<memory_dir>/common/`** — the scope for facts about no single project: an
   outside tool that was evaluated, a shell trap, what this machine has
   installed. It holds one directory per audience (`shared`, `private`), each a
   link into a memory repository, and either may be absent on a machine that
   wired only one. Nothing in the project's index points there and nothing
   should — the link would be dead for anyone who has not wired the scope —
   which is exactly why it is named here instead. A repository that has no
   `common/` directory never wired it, and that is not a fault to report.

5. **Check live facts instead of trusting the documents:**

   ```bash
   bash <plugin>/scripts/run status
   ```

   Documents can be stale in a way that looks identical to being current — a
   rewritten current-state file carries no sign of its own age. The command
   reports what is actually true right now: git state, divergence from the
   remote, background work, memory wiring. If it disagrees with what the
   documents said, the command wins, and say so out loud rather than quietly
   answering from the documents.

   When the task is on the process/tooling half itself, this step is
   **replaced** by, not performed in addition to, the flag that reports the
   same live facts plus that half's own state — memory lint, the wrap lock,
   worktrees, recent process edits:

   ```bash
   bash <plugin>/scripts/run status --flow
   ```

   Run one or the other, never both: `--flow` is the plain report with the
   process-half section appended, so a plain `run status` right after it
   would just repeat what it already printed.

## Answering

Give the answer before making any edit, in four short parts:

- **Where we are** — from the current-state file and the memory just opened,
  with pointers to the files, not a restatement of their content.
- **What's frozen** — thresholds, artifacts, or decisions on this half that
  cannot move without a dated, deliberate change.
- **What I propose** — an ordered list, marking which items need a decision
  from the human and which don't.
- **What's missing** — unknown numbers, open decisions, external
  dependencies that block a confident answer.

If the current-state file and `run status` disagree — for instance the
command reports the branch is behind its remote — resolve that first (a
`git pull --rebase` before anything else) rather than answering against state
that no longer holds.

## What carries into the session

This rite ends here, but one rule outlives it. From now on a fact worth keeping
is written **when it appears**, not collected at the end. The moments that
produce a note are in `agent-memory`; the short form is that an option was
rejected, a measurement landed, a number turned out to mean something else, a
tool trap bit, or a decision was frozen.

Nothing is written now — `start` reads. The rule is stated here because this is
the only place early enough to be read before the first of those moments
arrives: `wrap` is loaded at the end, and `agent-memory` is loaded when a note
is already being written, which is too late to be the thing that prompts one.