trailhead

Why trailhead

A shared map, an engine that builds

Give a big, foggy idea a place to begin and a disciplined way to walk it to a working result, with the whole plan living on your issue tracker instead of scattered local files.

Everything on GitHub Issues

The map is a parent issue, each ticket a child, discussion and plans are comments. No .planning/ directory: the repo holds code, the plan stays visible to the whole team.

Execution inside the map

Not plan-and-hand-off. Build tickets graduate from the fog and are executed as children of the map, discuss → plan → execute → verify, with atomic commits.

Built for teams

The tracker is the single source of truth. Claim a ticket to lock it, work a shared frontier one ticket per session, isolate concurrent work, pause, resume, split.

Install

Runs on Claude Code and Codex CLI

Authored once; the installer projects host-native artifacts. Pick your path.

Claude Code plugin

native

/plugin marketplace add ToRvaLDz/trailhead
/plugin install trailhead@trailhead

Managed by /plugin. Update with /plugin update trailhead.

npm

npx @marcomigozzi/trailhead # auto-detect host

Installs into your agent's config dir (~/.claude). Node 18+.

Codex CLI

npx @marcomigozzi/trailhead --codex

Projects a native $trailhead skill + hooks. Codex 0.145.0+.

Prerequisites: an authenticated gh CLI and a GitHub repo to work in.

How it works

Resolve one ticket at a time

Chart a map from a loose idea. Anything not sharp enough to plan yet sits in the fog; a grilling conversation dissolves it into decided tickets on the frontier. Resolve one per session and the map grows toward the destination.

Grilling clears the fog

trailhead won't guess the shape of your project. It interrogates you one pointed question at a time, converging a fuzzy area of the map into a closed decision, then writes it up as a real ticket. That's how the fog turns into work you can actually build, never an agent quietly deciding for you.

Discuss

Grill the idea into closed choices, only when there's real ambiguity.

Plan

Steps, seams, files, and verification criteria, reviewable on the ticket.

Execute

Atomic commits that each reference the ticket, visible in its timeline.

Verify

Tests, adversarial code review, and acceptance before the ticket closes.

Frontier — open, unblocked tickets you can take nowFog — what isn't sharp enough to plan yetDestination — a working artifact, not a spec

Built in, not bolted on

The techniques come with it

Grilling, quick off-map capture, design mockups, acceptance testing: no extra plugins to wire up. trailhead ships its own agents and needs only an authenticated gh.

Grilling

One question at a time until a fuzzy decision becomes a closed choice. It's how the fog on the map turns into tickets, and it keeps the call yours, not the agent's.

converge decisionsclear the fog

Whiteboard

Not every task belongs on a map. Capture a bug, a to-do, or a loose idea to the whiteboard and work it off to the side, no map ceremony, then get straight back to the trail.

off-map ticketsquick, no split

Design prototypes

For UI work, mock up the screen on a Claude Artifacts canvas, with your design system on it, or on Google Stitch before any code. Pick between variants, edit them live, approve, then the build reproduces them faithfully. This very page started as one of those mockups.

ArtifactsStitchhow it works →

Acceptance testing

Green tests don't close a user-facing ticket. trailhead asks who drives the UAT, then drives the app itself (browser, phone, TV: whatever the session can reach) with screenshots as evidence, checks the build against the approved mockup, and walks you through what only you can do, one step at a time.

browser & devicesmockup fidelityhow it works →

And the heavy machinery, where it earns its keep

Run once per ticket or once per repo, never as busywork.

RED → GREEN

TDD at the seams

A failing test at the real seam before any implementation, then make it pass, then refactor. Dial it up or off per project.

adversarial

Code review

Every build's diff reviewed across axes, each finding verified before it's reported, deferring to no "settled decision" or convention.

scientific method

Debugging

Reproduce, localise, a falsifiable hypothesis, confirm the cause with a test, then verify the fix. No guess-and-patch.

once per repo

Codebase mapping

A one-time fan-out that distils architecture, stack, conventions, and risks into a single issue the whole team reads.

Each runs as trailhead's own agent, projected to Claude Code and Codex. Zero external-plugin dependencies, nothing else to install.

Know where you stand

One command to see the whole surface

The plan is always on the tracker, and a handful of read-only views render it back to you, low-res and legible.

/trailhead:map

The low-res map

Destination, the decisions made, the frontier you can take now, and the fog still ahead. One glance at where the project stands.

/trailhead:whiteboard

The whiteboard

The loose, map-less tickets off to the side: what's open, its own frontier, and who holds each one.

/trailhead:dashboard

The pinned index

One pinned issue indexing every open map, the whiteboard, and live counts, always one click away in the repo.

/trailhead:inbox

Triage what others opened

Issues other people filed flow through an inbox; fold the worthwhile ones into the map in place, keeping their authorship.

Live in Claude Code

The map stays on screen while you work

In Claude Code the trailhead mod draws the work beside the conversation: the active map's tickets, the step you're on, and how the map is burning down.

The trailhead map panel docked beside the Claude Code transcript: the open maps, the frontier with a work button per ticket, tickets in progress and blocked, and a footer with refresh and close — /trailhead:panelThe **map panel**: every open map to view, the frontier with a **work** button per ticket, who holds what, and what is blocked.

The pipeline band above the prompt showing the ticket in play and its discuss, plan, execute, verify steps, with the trailhead status entry below — The **pipeline band** and **status entry**: the ticket in play and the step it's on: the band above the prompt, the status entry under it.

The burn-down section of the map panel: open, done, removed and peak counts over a chart of open tickets from the map's first ticket to now — The **burn-down**: open tickets over time, from the map's first ticket to now.

Claude Code 2.1.287+ · ships inside the trailhead plugin · Codex keeps the command hooks

Zero-friction capture

Something surfaces? One line, keep going

Work turns up mid-flow all the time. Record it in a single command and it lands as a real ticket, not a lost thought, without derailing the ticket you're on.

todo/trailhead:todo

A small, defined build ticket you'll do now. Straight onto the board, scoped and ready to work.

bug/trailhead:bug

A defect, captured with its repro. Add --of to mark it a regression of an already-shipped ticket.

seed/trailhead:seed

Work parked until a future trigger fires. Kept blocked and auditable, so nothing wanted-later slips through the cracks.

quick/trailhead:quick

Work one loose ticket whole, off the map, start to finish. Grills only if needed, never splits, just get it done.

On the tracker, not your laptop

Your plan follows you

The map is GitHub Issues, so the whole project isn't trapped in a local folder on one machine.

checkout mapbilling map

Two maps, side by side

Run two important features as two separate maps at once, each with its own frontier and its own grilling. Park one and switch to the other whenever priorities move, then pick the first back up exactly where you left it, without the two colliding.

Pick up on any machine

Because the whole plan lives on the Issues, not in a local folder, you can stop on your laptop and resume on another computer, or hand it to a teammate mid-flight. Nothing to sync, nothing to export, the tracker is the single source of truth.