ToRvaLDz/trailhead

🧭 The problem it solves

A real project doesn't fit in one agent session. Ask for "the whole app" and you get a confident guess; split it yourself and you become the project manager, the memory and the glue.

😵 Without trailhead	🗺️ With trailhead
The agent guesses the big decisions and you find out three files later.	Decisions are tickets: options laid out, then a grilling, one question at a time, until you choose.
The plan lives in a chat that ends, or in local notes nobody else sees.	The plan lives on GitHub Issues: the map, the discussion, the plan and the verification, visible to the whole team.
Every session starts from zero: what was decided, what's left, what's next?	The frontier says what's takeable now; /trailhead:work picks it up with all the context.
Two agents in one checkout overwrite each other.	Assigning a ticket claims it, and each concurrent session gets its own worktree or clone.
"Done" means "it compiled".	Done means verified: tests, adversarial review and acceptance before the ticket closes.

✨ What you get

🗺️ A map, not a list A big idea becomes one map issue with a child ticket for each decision, research question and piece of work. What you can't phrase yet waits in the fog until earlier answers clear it.	⚙️ The right engine per ticket A decision is grilled to a choice, research gathers a fact, a build is planned and built, a bug is reproduced before it's fixed.	🤖 Hand it a map, come back /trailhead:auto works a map unattended, in up to four parallel slots, and leaves a report, the tickets that need you, and commits to push.
👥 Built for teams Many people and agents share one frontier, one ticket each. Pause, resume or split a ticket, and run several maps side by side.	🎨 Mockups and acceptance See the screen before it's coded, and close a feature only after it was tried the way a user would.	🛡️ Self-contained, with guardrails Nothing else to install: trailhead ships its own engine agents and ten guardrail hooks, on Claude Code and Codex CLI.

⚙️ How a ticket gets built

Every build ticket walks the same disciplined cycle, and every step is a comment on the ticket, so the reasoning stays next to the work.

🖥️ Live in Claude Code

The bundled mod puts the map beside the conversation: your tickets in progress, what needs you, and the frontier with a work button per ticket. A band above the prompt shows the ticket in play, and the session is named after it.

📍 Always know where you are. The band shows the ticket in play and its step: discuss, plan, execute, verify. ▶️ One click to start. Each frontier ticket has a work button that clears the context and starts it. 📉 See it shrink. The burn-down tracks the open tickets from the first one to the destination.

🚀 Get started

You need an authenticated gh CLI and a GitHub repo.

# Claude Code plugin
/plugin marketplace add ToRvaLDz/trailhead
/plugin install trailhead@trailhead

# or with npm, for Claude Code or Codex CLI (Node 18+)
npx @marcomigozzi/trailhead

Then restart your agent and give it a destination:

/trailhead:new "a booking app for my climbing gym"   # chart a map from a loose idea
/trailhead:adopt                                     # or adopt an existing codebase
/trailhead:work                                      # work the next ticket on the frontier

On Codex the entry point is $trailhead. Every option is in Getting started.

📚 Learn more

🧠 Core concepts maps, frontier, fog, anchors	🔄 Workflow the lifecycle and a worked example	⌨️ Commands all 24 verbs
👥 Working as a team claiming, isolation, CI capture	🎨 Design mockups see it before it's built	⚙️ Configuration models, TDD, isolation

🙏 Acknowledgements

trailhead joins two ideas that each nail one half of the problem: a map of decisions to start a project, and a disciplined engine to build it. It is an original, self-contained methodology inspired by them. It does not copy or redistribute their code, and it invokes none of their skills; it reimplements the ideas as its own inline protocols:

• Matt Pocock: for Wayfinder, whose map / frontier / fog-of-war model is the backbone of trailhead's planning half, and whose grilling, domain-modeling, prototype, research, and tdd skills shaped trailhead's inline techniques. See mattpocock/skills.
• The open-gsd team: for GSD, whose discuss → plan → execute → verify cycle, capture model, codebase mapping, and systematic debugging are the engine of trailhead's building half.

Thank you. If you like the ideas here, go star and use the originals: they go far deeper than trailhead's compact protocols.