Skip to content
trailhead

Workflow

The lifecycle

Section titled “The lifecycle”

Every project walks the same loop:

  1. Start: /trailhead:new "<idea>" (greenfield) or /trailhead:adopt (existing code: map the codebase once, then go lean). This charts the map: name the destination, then map the frontier breadth-first into the first tickets and the fog.
  2. Work the frontier, one ticket per session: /trailhead:work takes the next takeable ticket (or one you name) and runs the engine for its type: research gathers a fact, decision diverges options then grills to choose, prototype makes a rough artifact to react to, build runs discuss → plan → execute → verify, bug runs repro → diagnose → fix → verify, task is manual plumbing that unblocks a decision.
  3. Close & unblock: resolve the ticket (comment + close), gist it into Decisions so far, and drop trailhead:blocked from any dependent whose last blocker just closed, graduating it onto the frontier.
  4. Repeat until the frontier is empty and the fog has cleared: the destination (a working artifact) is reached.

Along the way: capture ideas mid-work without derailing (see Captures & the whiteboard), split a ticket that grew too big, pause/resume across sessions, and let several people work unblocked tickets in parallel (see Working as a team).

A worked example: “add social login”

Section titled “A worked example: “add social login””

Destination: users sign in with Google and GitHub, alongside email/password. Charting fans it into six tickets (one of each type) wired by their dependencies:

① research   "OAuth providers + library: Supabase Auth native or Auth.js?"   ← frontier (AFK)
② decision   "approach: Supabase Auth native vs Auth.js custom"              ← blocked by ①
③ task       "register OAuth apps on Google + GitHub, get client id/secret"  ← frontier (HITL)
④ prototype  "how the login screen with social buttons looks"                ← frontier (HITL)
⑤ build      "implement Google + GitHub login"                               ← blocked by ②③④
⑥ bug        (appears after ⑤ ships)

Initial frontier = ①③④, three people can start in parallel. Then:

  • ① research → a subagent reads the docs, returns a decision-ready finding, closes → unblocks ②.
  • ② decision → diverge the options, grill to choose native vs custom, record the why.
  • ③ task → the agent hands you a checklist (it needs your Google/GitHub accounts); you register the apps, it records where the credentials live.
  • ④ prototype → a rough login screen (on the configured design surface), approved before UI code.
  • With ②③④ closed, ⑤ build graduates → discuss → plan → execute (atomic commits, TDD at the auth seams) → verify (tests + code review + acceptance: the agent drives the browser through the real login flow).
  • After it ships you spot a wrong redirect in prod → /trailhead:bug --of ⑤ "GitHub redirect goes to localhost" → a new ticket carrying Regression of: ⑤, worked repro → diagnose → fix → verify. ⑤ stays closed.
① research ─┐
③ task ─────┼─► ② decision ─┐
④ prototype ┘                ├─► ⑤ build ──(ship)──► ⑥ bug (Regression of: ⑤)
③ task ──────────────────────┘

The preparatory types (research/decision/prototype/task) unblock the constructive ones (build/bug); parallelism is real but across sessions on the frontier, not inside one.

…then a suggestion arrives: inbox → fog → graduation

Section titled “…then a suggestion arrives: inbox → fog → graduation”

The app is live, and a user not on the team files a plain issue: “can we add Apple sign-in too?” No trailhead:* label, so it isn’t a ticket yet. Here’s how an outside voice becomes a first-class ticket on the map, without losing the reporter’s authorship:

  1. Inbox: /trailhead:inbox lists it under New: to triage. It’s in scope but not sharp: web only or native? does it need the paid Apple Developer account? You can’t phrase one answerable Question yet, so you don’t force a ticket.
  2. Fog: label it trailhead:fog and keep the issue open as a clarification space. A comment posts the sharpening questions (async grilling); the reporter and anyone interested refine it in the thread. It’s off the frontier but tracked: gh issue list --label trailhead:fog is the durable list, and the reporter follows their own issue.
  3. Graduation: the discussion converges. Next time you run /trailhead:inbox, its Parked fog section surfaces the thread as recently-active: that’s how you notice the fog cleared. Now the Question is phrasable, so you adopt it in place: swap trailhead:fog for trailhead:ticket + a type label, add the Parent: line and the ## Question. Same issue number, same reporter credited, it lands on the frontier, ready for /trailhead:work.
suggestion issue ──inbox──► fog (kept open, discussed) ──sharpens──► ticket on the frontier
                                                                    (same #, reporter still credited)

No separate backlog, no lost credit: the map absorbs external suggestions the same way it grows its own, through fog that graduates when it’s sharp.

Next: Ticket types for what each engine actually does, or Commands for the full verb list.