How It Works

Single Task — /quest

Run /quest for any non-trivial task. Four phases, three gates — one leaving Research, Plan, and Implement. Nothing leaves Review; the quest ends inside it, when the PR is open.

1

Phase 1: Research

Provisions an isolated git worktree and picks up any checkpoint left by a previous session. Loads task-relevant context, scans past failures and sibling quests’ discoveries, explores the codebase with subagents, and studies reference files for the conventions in play.

Explore agents
GATE — requires approval
2

Phase 2: Plan

Enters plan mode. Creates an implementation plan with file:line references and a test strategy. Presents the plan for your approval.

plan mode, writing-plans
GATE — requires approval
3

Phase 3: Implement

TDD red-green-refactor against a todo checklist. Writes the failing test, implements, verifies, commits. If stuck: commits partial work, records a failure, and returns to Plan.

test-driven-development
GATE — requires approval
4

Phase 4: Review

The balrog agent attacks the implementation first — edge cases, error paths, targeted tests — and its findings are fixed. Then convention review via /warden, a code-quality review, and verification. Finally the PR, and the worktree is cleaned up. No gate leaves Review: the quest ends here.

/warden, verification-before-completion, finishing-a-development-branch

Multiple Tasks — /fellowship

Run /fellowship for multiple independent tasks. Gandalf coordinates parallel agents.

1

Describe

You describe multiple tasks (quests and scouts)

2

Analyze

Gandalf analyzes them and registers each in the store

3

Spawn

Spawns quest teammates in isolated worktrees

4

Scout

Spawns scout agents for research questions

5

Monitor

Palantir reports the CLI's health sweep (at 2+ quests; Gandalf runs it directly below that)

6

Gate

Gates surface to you for approval

7

Status

Say "status" anytime for a progress table

8

Deliver

Each quest produces a PR; scouts produce reports

Gandalf coordinator
Quest 1
worktree → 4 phases → PR
Quest 2
worktree → 4 phases → PR
Scout
investigate → validate → report
Palantir
reports the CLI's health sweep

Research — /scout

For questions that need investigation but not code changes.

1

Investigate

Explores codebase, reads docs, runs searches

2

Validate optional

Spawns fresh adversarial subagent to challenge findings

3

Deliver

Structured report with confidence levels

Gate Enforcement

Gates aren't just prompts — they're structurally enforced.

Hook-Blocked Tools

Plugin hooks block tool access (Edit, Write, Bash, etc.) after gate submission.

Lead Approval Required

Tools stay blocked until the lead approves with fellowship gate approve.

Verified Prerequisites

Running /lembas and confirming the phase with fellowship phase confirm are verified before gate submission.

No Self-Approval

Self-approval is structurally impossible. The agent that submits the gate cannot approve it.

Prompt-only compliance ~33%
Hook-enforced compliance ~95%+