Trailhead

🇬🇧 English · 🇮🇹 Italiano

Start and drive large projects as a map of tickets on GitHub Issues, resolving one at a time until the way to the destination is clear.

trailhead is an orchestrator skill for coding agents, running on Claude Code and Codex CLI from a single source. It gives a big, foggy idea a place to begin (a trailhead) and a disciplined way to walk it to a working result, with the whole plan living on your issue tracker instead of in scattered local files.

---

💡 Why trailhead exists

Two approaches to agent-driven project work each nail one half of the problem:

• Wayfinder (by Matt Pocock) is brilliant at starting. It turns a loose idea into a shared map of decision tickets on your issue tracker, named through a proper grilling conversation, with a visible frontier and a "fog of war" for what isn't sharp enough to plan yet. You resolve one decision per session and the map grows outward. What it deliberately doesn't do is build: it plans, then hands off.

• GSD (the open-gsd workflow system) is brilliant at doing. Its discuss → plan → execute → verify cycle, atomic commits, and zero-friction capture make the actual construction reliable and reviewable. But its state lives in a local .planning/ tree, separate from where the team can see it.

Working across both, one pattern kept recurring: use a Wayfinder-style map and onboarding to decide the shape of the work, then a GSD-style engine to build each piece, without ever leaving the issue tracker. trailhead is that pattern made into a set of cohesion-clustered skills over a shared core, its own self-contained take on both ideas rather than a wrapper around either.

trailhead is self-contained in the sense that it has zero external-plugin dependencies: trailhead-owned agents and the host's built-ins are fine, and no other skill or plugin is required. Wayfinder and GSD are inspiration, not dependencies. Every technique those systems package as a separate skill (grilling, TDD, systematic debugging, codebase mapping, code review) is built in here as an inline protocol. trailhead's core invokes no other skill; each engine technique dispatches to trailhead's own trailhead-* agent (trailhead-executor, trailhead-plan, trailhead-research, trailhead-code-review, trailhead-debug, plus trailhead-fix and trailhead-codebase-map), authored once as a committed agents/trailhead-*.md file and projected to each host (Codex gets ~/.codex/agents/trailhead-*.toml generated from that same source). These agents are thin (identity + tool policy + a config-driven model, with the technique protocol injected at spawn) and run on the host's native subagent toolkit (Claude Code's built-in Agent tool, or Codex's multi_agent toolkit). The only thing to install is trailhead itself. There is one opt-in exception: hosted mockups. design: artifacts uses Claude Code's built-in Artifact tool (nothing to install), and design: stitch uses the Google Stitch MCP (offered as a one-time install). See Mockups before code.

The design choices that fall out of it: