Planning complex, ambitious projects with AI agents often falls short when constrained to a single context window or single session. The Wayfinder skill addresses this limitation by introducing a structured, multi-session planning framework based on fundamental software engineering principles. It orchestrates large bodies of work across sequential and parallel sessions, allowing builders to navigate uncertainty without compromising on ambition.

Core Concept: Mapping the Fog of War

Wayfinder treats project planning as a map journey from an initial vague idea to a clear destination. It establishes a dynamic workflow by separating actionable decisions from those blocked by uncertainty:

• The Frontier: Active, decision-ready tickets that can be tackled in current or parallel sessions.
• The Fog of War: Dependent decisions that are deferred until required research, prototypes, or discussions are completed.
• Issue Tracker Integration: Wayfinder is issue-tracker agnostic (supporting GitHub, Linear, Jira, etc.), managing parent maps and linking sub-issues as decisions are made and resolved.

The Four Ticket Types

To systematically clear the fog of war, Wayfinder breaks down planning into four distinct interactive session types:

• Research: Automated sub-agent tasks designed to gather external information or analyze code bases.
• Prototype: High-fidelity code implementations that provide rapid feedback loops, ensuring the project avoids heavy, theoretical “waterfall” planning.
• Grilling: Interactive Q&A sessions where the AI interviews the user to clarify requirements and architectural details.
• Task: Real-world errands or scheduled execution steps needed to advance the project.

From Map to Execution

Once the decision tickets on the map are resolved, Wayfinder consolidates the findings into a comprehensive specification. Unlike traditional Spec-Driven Development (SDD), these specifications act as temporary destinations:

• Primary Source Traceability: Specs link directly back to individual decision tickets, preserving full context if the agent needs primary sources during implementation.
• Non-Persistent Specs: Once a spec is converted into implementation tickets and coded into the project, the spec issue is closed and discarded, ensuring the codebase remains the single source of truth.

Key Takeaways and Application

Wayfinder is ideal for large-scale, multi-session tasks where the path forward is initially unclear. It excels in both complex software engineering challenges and real-world project planning (e.g., managing vendor surveys and research for construction). If a task can be planned and built within a single context window, standard single-session prompting suffices; for everything else, Wayfinder provides the orchestration needed to execute big ideas.

Mentoring question

How could shifting from single-session AI prompts to a multi-session, decision-ticket architecture change the scale and complexity of the projects you feel comfortable building with AI?

Source: https://youtube.com/watch?v=F3lL98Pj90o&is=EC5ZA9RN1WXiIBSs