Ryuu's Skills

Plans

Intent, acceptance, probes, and the shared context a batch uses.

A plan carries intent and acceptance criteria, never a snapshot of current code. Snapshots go stale before the plan runs. Instead of a file and line reference, a plan has a ## Probe block with symbol searches that run at execution time.

Intent and Acceptance

This snippet illustrates the shape. The plan file template states the full format.

---
id: 095
slug: hide-blocked-messages
surface: chat search and pins, signed in users only
critical: false
needs: node
---

## Outcome

One paragraph. What is true when this is done, on one named surface.

## Acceptance

1. Blocking a user removes their messages from search, pins and reply previews.

## Probe

    rg -n "blockedUserIds|isBlocked" src/

a. Symbols present and acceptance already holds: close as DROPPED.
b. Symbols present, acceptance unmet: continue.
c. Nothing recognizable: stop and report.

needs: is optional. It lists the capabilities a machine must have to run the plan, and a plan without it runs on any machine. Machines lists the capabilities and what happens on a machine that lacks one.

The Probe

The agent runs the probe once, on the new branch, so it sees the code as it is when the plan starts. It has three outcomes:

  • Acceptance already holds. Close the plan as DROPPED because no work is needed.
  • Acceptance is unmet. Continue with the playbook.
  • Nothing is recognizable. Stop and report what the probe expected and what it found.

The last outcome is the probe's only stop condition. It fires when the subsystem moved, never because a file changed. Sibling plans in a batch can land without invalidating each other's probes. The destination gate is a separate check before the probe.

Shared Context

Everything a batch shares lives in a ctx-<batch>.md file: the subsystem model, vocabulary, invariants, destinations, and measurements. Siblings reference that file by name and never copy its contents. When the shared picture changes, edit that file once.

Before it drafts a plan, /plans new searches every project's plans with recall for work that already landed or was dropped, and lists the closed plans that bear on the batch under the ctx file's ## Prior work section.

The Plans Directory

Plans live in ~/Plans by default. Set PLANS_DIR to move the directory. Projects are the directories found there at runtime, matched to the repo by name.

<plans>/plans.db                      the store: every row change and trail event, one SQLite file per machine
<plans>/log.tsv                       view of the global append only trail, written by the store
<plans>/<Project>/index.tsv           view of status only, tab separated, note capped at 100 chars
<plans>/<Project>/NNN-slug.md         open plans, intent only, 4 KB cap above ## Landed
<plans>/<Project>/ctx-<batch>.md      shared model for a batch, referenced never copied
<plans>/<Project>/done/NNN-slug.md    closed plans, each carrying a ## Landed section
<plans>/<Project>/_archive/README.md  an older prose index, never read by an agent
<plans>/audit/<repo>/YYYY-MM-DD.json  one saved `skills audit --digest` run per repository and UTC date

index.tsv holds status, not the plan's story. See the index.tsv schema for its fields. A REVIEW row still holds its dependents until the PR merges. The next /plans do recognizes a merged blocker even before you close its row.

The Store

Each machine keeps its plans in one SQLite file, plans.db, at the root of the plans directory. A verb that changes a row or the trail commits the change there first, then rewrites the index.tsv or log.tsv it touched from it. Every verb that reads rows or the trail, the session brief included, reads the store.

index.tsv and log.tsv are views. They keep their paths and the same bytes they always had, so anything that reads them works as before. Never edit either by hand: change rows with skills plans set-row, add and close, and the trail with skills plans log.

Plan and ctx files stay ordinary files you edit. They are working copies: when skills brief, plans lint, plans wave, plans close or plans sweep reads one whose bytes changed since the last read, the store first keeps those bytes as a new revision. A plan keeps its history when it moves into done/.

Each store stands alone. To share one plans history across your machines, connect them through a hub, which carries the store's events and files between them encrypted and keeps one plan on one machine at a time while they can reach it.

After an Update

The first plans verb that finds no plans.db imports the directory before it does anything else: every index.tsv, log.tsv, plan and ctx file. It then renders both views from the store and compares them with the files on disk. One byte of difference refuses the import, naming the file and the first line that differs, and leaves no store behind. Until an import succeeds, readers report the refusal, writers exit nonzero, and the session brief prints the reason in place of its plans lines.

The status history starts at the import. The TSV layout kept no record of row changes, so --at cannot see past it.

A Refused View

A write that finds index.tsv or log.tsv changed outside the store refuses, naming the file and skills plans import. The change came from a hand edit, or from a release without the store writing the views behind its back. Run skills plans import: it takes the edit into the store and the next write goes through.

Some edits it cannot take in, and it refuses them, naming the file: a row deleted from a view, a trail line changed after it was imported, or a view edited while a write to it was unfinished. Move that view aside and run skills plans import again. The store writes the missing view back from what it holds.

Reading History

Each --at takes an ISO 8601 UTC time, such as 2026-10-31T15:25:31Z, or a YYYY-MM-DD date meaning the end of that day in UTC.

CommandWhat it does
skills plans importReads every view, plan and ctx file into the store. A rerun adds only what changed.
skills plans show <Project> <id> [--at <time>]Prints the newest revision of a plan, or a ctx file by its slug. With --at, the newest one recorded by that time.
skills plans show --conflict <Project> <id>Prints the other machine's copy of a plan or ctx file that the hub sync kept because both machines changed it.
skills plans history <Project> <id>One line per revision, oldest first, across the move into done/: when it was recorded, its sha256, the machine and the byte count.
skills plans checkout <Project> <id>Writes the newest revision back to a missing plan or ctx file. It refuses, changing nothing, when the file on disk differs.
skills plans frontier --at <time> [Project]Prints the frontier from the rows the store held at that time. It refuses a time before the store first held the project.

Cross Project Work

A plan can wait on work in another project. blocked_by takes a comma separated list, and each item releases its row in its own way:

ItemMeansReleased by
093row 093 of the same projectDONE or DROPPED, or its PR merging. While it is in REVIEW, the plan can stack on its branch
Stanza/168row 168 of project Stanza, a plan refDONE or DROPPED in Stanza only. A REVIEW row there still holds it, and it never becomes a base to stack on
Stanza#3issue 3 in Stanza's inbox, an issue refthe issue closing

skills plans add checks every plan ref and issue ref against the store before it writes the row, so a ref to a project, row or issue the store does not hold refuses. Until a ref is released, the frontier lists the row under BLOCKED with waits on Stanza/168 or waits on Stanza#3, and /plans do refuses to start it.

The Inbox

An issue is a request nobody has planned yet, filed into another project's inbox and numbered from 1 in that project.

CommandWhat it does
skills issues file <Target> <title> [--body <file>] [--from <Project>/<id>] [--blocks <Project>/<id>]Files an issue into the Target project's inbox and prints its ref. --body reads its text from a file, --from names the plan that asked, and --blocks adds the ref to that row's blocked_by.
skills issues list [Project] [--all]One tab separated line per open issue: its ref, its state, its title and the plan that filed it. --all adds the closed ones.
skills issues show <Project>#<n>The title, who filed it and when, its state, the plans it blocks and the plans that resolve it, then the body.
skills issues close <Project>#<n> <reason>Closes it by hand, with a reason.
skills issues link <Project>#<n> <id>Names row <id> of the issue's own project as a plan that resolves it.
skills issues renumber <Project>#<n>Moves the latest filing of a number filed more than once to the next free number and prints its new ref.

skills plans add takes --resolves <Project>#<n> to make the same link as it writes the row. Once every plan that resolves an issue is DONE, the issue closes by itself, naming them. A resolving plan closed as DROPPED loses its link instead. Once an issue closes, each plan waiting on it with nothing else open is released: a TODO plan becomes ready, and a BLOCKED one goes back to TODO on its branch, with the note unblocked by Stanza#3.

Bare /plans ends with an INBOX section, one line per open issue with the plan that filed it or per number in conflict, and the session brief adds an Inbox: line. /plans new runs skills issues list before it drafts a plan and weighs each open issue like work its survey found, unless skills issues show already lists a plan that resolves it. The plan that answers one gets --resolves on its row. When /plans do finds that a plan needs a change in another project's code, it files that change with --from and --blocks instead of making it, sets the row BLOCKED and hands back with the ref.

Two machines that file into the same inbox while apart can give the same number to different issues. Sync keeps every filing: the earliest holds the number and every link and close made on it, and the rest wait. /plans prints such a number as Stanza#3 conflict: first title | second title, run skills issues renumber Stanza#3, skills issues show prints that line above one block per filing, and issues close, issues link, --resolves and a blocked_by naming the number refuse until it is settled. Each skills issues renumber Stanza#3 moves the latest filing to the next free number, so a number filed three times takes two runs.

Issues live in the store alone. They have no file, no row in index.tsv and no line in log.tsv, so nothing about them is edited by hand: the verbs above file, link and close every one.

On this page