Pathfinder

Direct AI agents through software delivery without giving up the decisions.

Pathfinder is a small, portable workflow kit you copy into a software project.

It gives AI agents reusable skills for discovering, planning, building, testing, completing, debugging, learning from, and reflecting on software work — while keeping judgment and consequential decisions with you.

It is intentionally stack-agnostic. Pathfinder does not choose React, Python, mobile, a database, hosting platform, Git model, or other implementation details for you.

The kit owns the workflow. The project owns the stack.

Pathfinder gives you one disciplined workflow with two ways to operate it: work one ticket at a time with direct human control in human-in-the-loop mode, or let orchestrator mode coordinate several dependency-safe workers while surfacing only the human gates that need you.

Choose an execution mode.

What Pathfinder gives you

Pathfinder has four small building blocks:

Skills — reusable procedures for software-development work
Roles — responsibility boundaries for an AI session
Context — project truth and temporary workspace state
Templates — minimal records created only when needed

It is not an application framework. Orchestration adds isolated workers, dependency-aware scheduling, and fewer unnecessary interruptions to the same discipline. There is no daemon, broker, queue, database, or server; no automatic merging, no bypassing review, and no unlimited agents.

There is no required application framework, package manager, database, programming language, hosting platform, Git model, agent swarm, or background service.

It is also not autopilot. Agents may recommend and execute work, but the human owns approval, acceptance, merge, release, and other consequential decisions.

The workflow contracts are readable Markdown. Orchestrator mode and visual artifact generation use optional Node engines; orchestration also uses Git and, with GitHub Issues, gh. Human-in-the-loop delivery needs no runtime.

Start a project

mkdir my-project
cd my-project
git init
npx create-pathfinder

The installer copies Pathfinder into the repository and exits. It does not add a runtime dependency to your application.

If you configure Claude Code or Codex during installation, Pathfinder also generates native skill adapters so its skills appear directly in that tool.

Then start with:

/kickstart-pathfinder

Kickstart learns enough about the project to establish its durable context without writing product code or silently choosing unresolved decisions.

Without native skill support, use:

Use skills/kickstart-pathfinder/SKILL.md to initialize this project.

Claude Code users can install Pathfinder as a plugin instead, which brings the commands without copying anything into the repository:

/plugin marketplace add rikilamadrid/pathfinder
/plugin install pathfinder@lamadrid-labs

Plugin commands are namespaced — /pathfinder:kickstart-pathfinder, /pathfinder:ticket load — and the plugin installs no project files. See Getting started for what each path installs and when to use both.

Getting started walks through the first session.

The workflow

The core delivery flow is deliberately small:

idea
  ↓
kickstart / debate / prototype
  ↓
to-specs
  ↓
to-tickets
  ↓
choose the coordinator
  ├─ human-in-the-loop: you drive one ticket session
  └─ orchestrator: /orchestrate start coordinates isolated workers
  ↓
each worker: /ticket load → /ticket start → review → acceptance
  ↓
integration safety + human merge authority
  ↓
/ticket complete → next eligible work

A prototype is optional.

Features are small, focused, and independently verifiable.

Debugging, learning, external-reference analysis, handoff, reflection, and ticket-store selection are supporting workflows you invoke when useful rather than mandatory stages every Feature must pass through.

When it is not obvious which one applies:

reverse-engineer = understand an external reference
learn-codebase   = understand the current codebase
debug-issue      = an observed failure needs an explanation
/ticket start    = planned construction is difficult

See the full workflow.

Automatic roles

Pathfinder ships five roles:

Role	Responsibility
`planner`	Discovers project direction and produces Features and tickets
`orchestrator`	Coordinates dependency-safe workers without implementing their tickets
`developer`	Implements approved work without accepting its own work
`tester`	Independently verifies delivered work and reports findings
`integrator`	Checks whether reviewed work can land, under human merge authority

Lifecycle skills read the responsible role automatically: planning assumes planner, ticket load/start/complete assume developer, and ticket review assumes tester. Orchestration assumes orchestrator; integration assumes integrator. Roles do not call one another: the skills coordinate the sessions.

Use /role only to override that default explicitly or debug a workflow under a particular boundary:

/role developer

Roles do not grant authority. They only narrow what the current AI session is responsible for.

The human coordinates in human-in-the-loop mode and keeps approval, acceptance, merge, and release authority in both modes.

Learn about roles.

Know where you are

During a session:

/whereami

gives you a compact view of the current role, execution mode, Feature, Git state, and next action without loading broad project history. In orchestrator mode, /orchestrate status shows workers, worktrees, gates, and blockers.

When you need to stop and continue later:

/handoff

records the minimum factual state another session needs to continue safely.

Context grows only when needed

A fresh Pathfinder project starts with only:

context/
├── ai-interaction.md
└── coding-standards.md

Choosing a mode also writes context/execution-mode.md. Other context appears only when a workflow actually needs it.

Durable project truth is tracked in Git:

context/project-overview.md
context/features/
context/tickets/          # when local Markdown is the ticket store
context/history.md
context/tracker.md        # when it is not
context/execution-mode.md # when explicitly selected

Temporary workspace state is normally ignored:

context/current-ticket.md
context/handoff.md

In orchestrator mode, also ignore /.pathfinder/, which holds local worker worktrees. Each worker has its own ignored context/current-ticket.md.

Do not ignore context/ wholesale. That would also hide the project truth future sessions need.

Human judgment stays human

Pathfinder deliberately stops rather than silently deciding things such as:

product scope
architecture and technology choices
dependencies
destructive operations
prototype adoption
Git and delivery decisions
acceptance
merge and release

An unresolved decision stays unresolved. TBD means a human decision is still required, and an agent must not quietly resolve one while implementing a Feature.

Human approval explains the boundary in detail.

Add it to an existing repository

Run the same installer inside an existing Git repository:

npx create-pathfinder

Existing files are preserved unless you explicitly choose to replace them.

Then run:

/kickstart-pathfinder

Kickstart separates facts already established by the repository from decisions that still need human input.

For deeper understanding of an existing codebase:

/learn-codebase

Where tickets live

Every project has a ticket store. With no configuration it is local Markdown files under context/tickets/.

If your tickets belong in GitHub Issues, Jira, Linear, Azure DevOps, or something internal:

/setup-tracker

The store you choose is canonical — one ticket artifact, no copy in the repository, nothing to sync. Feature specs are not tickets and stay in the repository whatever you choose.

Ticket stores explains the model.

Who Pathfinder is for

Pathfinder is a good fit when you want AI agents to do substantial software work while you retain control of the important decisions.

It is probably not a fit if you want:

an autonomous agent to choose the product and architecture for you
an always-running service or unlimited autonomous agents
a software framework your application builds against
a process enforced by infrastructure rather than readable instructions

Pathfinder is intentionally simpler than that.

Read the kit

The documentation renders the same skills and project guidance the agent reads.

Start with:

kickstart-pathfinder

or browse:

All skills

For the deeper model, continue with: