sandrods/trek-skill

A Claude Code skill for a program too large to finish
in one brainstorm → plan → execute → merge cycle.
A **trek** is one program walked in several cycles. The skill cuts the program into
cycles, keeps a record of where the trek stands, and walks each cycle through design,
plan and build: the design by the Superpowers
brainstorming skill, the plan and the build by the skill itself. It exists so that a
fresh session, weeks in, can read one short file and know what to do next.
The problem it solves
A multi-cycle program produces knowledge that outlives any single cycle: the rules it
has decided, the facts it has measured about systems it does not own, the questions
still gating it. Without a place for that knowledge, it lands wherever is open — the
brainstorm's input document, a status file, a note — and those files grow until nobody
can afford to read them at the start of a session.
trek gives that knowledge a shape with two rules behind it:
- **The record holds current state; the log holds history.** trek.md is replaced in
place and never appended to. log.md is appended to and never edited. Kept apart, a
status change replaces the old status instead of stacking a new reason on top of it.
- **Only what outlives a cycle enters the record, and it enters as one line.** Cycle
design stays in the cycle's own folder. A rule, a fact or an open question comes up
as a numbered one-liner pointing back at the cycle that produced it.
What a trek looks like
**trek.md** is the file a session reads first. Each cycle is an entry at the
resolution of the cut — goal, scope, out, dependencies, governing rules, unknowns,
done-when, artifacts, status — and nothing more: no task rows, no narrative. Below the
cycles sit the program's **rules** (R1, R2, …), **facts** (F1, …) and **open
questions** (Q1, …), one line each. Handles are permanent; specs cite them, and a
superseded item keeps its handle with a one-line pointer to what replaced it.
**log.md** answers "how did we get here?" without making the record carry it.
**The status mod** answers "where are we?" without a second record. The skill's folder
is also a Claude Code plugin: it reads the records of the checkout a session runs in and
draws a band above the prompt. On a treks/ /… branch it shows that trek (cycle
track, lead cycle, ledger progress, open questions); on any other branch, one line per
open trek, to choose where to go. /trek-status opens a pane for the same treks, with
every cycle, the lead cycle's ledger and the open questions; --all shows every trek.
It draws from the files, so it cannot disagree with them.
**The cycle folder** holds everything cycle-scoped. The findings file is created empty
at dispatch and named in every implementer brief, so a fact about a legacy database or
an external package has somewhere to go the moment it is found. At merge it is read,
and what outlives the cycle goes up to trek.md as one line pointing back.
**The plan** is about a page: a ledger table, then 3–5 coarse tasks, each a goal, the
files, the behaviours to test and a done-when. No code. The spec holds the decisions;
the implementer writes the code. The ledger table (task · status · commit · note) is
what resume reads and what the band shows.
How it flows
| Mode | How it starts | What it does |
|---|---|---|
| **Start** | /trek start | A brainstorm at the altitude of the cut: asks boundary questions, presents candidate cuts, writes the trek folder. Stops without dispatching cycle 1. |
| **Dispatch** | Resume finds a cycle whose dependencies are done | Creates the cycle folder and runs the brainstorm; once the spec is approved, writes the short plan; once that is approved, builds it with one fresh implementer agent per task, then one final review agent over the whole branch. |