Planner

Transform feature requests into structured plans with task breakdowns, dependencies, and TDD requirements for parallel autonomous execution.

All multi-sentence output for user presentation should trigger the Skill using /farseer:humanize to give a more human voice to the text.

Glossary

<glossary> @.farseer/glossary.md </glossary>

Project Architecture

<architecture> @.farseer/architecture.md </architecture>

Project Context

Agents spawned by this skill read the project's context files themselves. Before the first spawn, resolve the project root once:

"{skill-base-dir}/../../hooks/resolve-project-dir.sh"

Build the list from the printed path (call it $PROJECT_DIR, and write it literally into later commands). Include each file only if it exists:

for f in glossary.md architecture.md code-standards.md; do
  if [ -f "$PROJECT_DIR/.farseer/$f" ]; then printf '%s\n' "$PROJECT_DIR/.farseer/$f"; fi
done

Pass it to every agent as:

## Project Context

Read the files below that bear on your job:

{the list, one absolute path per line}

Never paste or summarize these files' contents into a prompt. The agent reads the originals.

Execution Flow

Phase 0: Pre-plan hook

Run this once, at the very start, before Phase 1 discovery.

Run the pre-plan hook.

Run the discovery script — never enumerate agent files by hand:

"{skill-base-dir}/../../hooks/discover-hooks.sh" --hook=pre-plan

{skill-base-dir} is the Base directory for this skill value stated when this skill loaded. ${CLAUDE_PLUGIN_ROOT} is not available in a skill's Bash calls.

• Exit 0, empty stdout → empty hook. This is the default. Return immediately: print nothing, spawn nothing, say nothing about the hook at all, and proceed to Phase 1. Do not narrate that the script returned no agents — that is the narration HOOKS.md forbids.
• Exit 0, output → print the output verbatim as the resolved agent order, then spawn each listed agent in order per its mode, with the Agent tool and subagent_type chosen by the row's origin: farseer:{agent-name} for plugin, {agent-name} for local.
• Any non-zero exit → stop. Surface the script's stderr verbatim and do not continue planning. Exit 3 means an agent file declares an invalid phase or mode; exit 4 means enrollment drifted. Neither is an empty hook. If the script is missing or not executable, that is also a hard stop — there is no fallback, and you must not reconstruct the routine by hand.

IMPORTANT — no plan name exists yet. The pre-plan hook fires before Phase 1 discovery. The plan name and plan directory are not created until Phase 3, so there is no plan name to pass. Each pre-plan agent receives only:

1. The raw feature request (the user's verbatim ask).
2. The Project Context list.

Do not attempt to pass a plan name or plan directory to a pre-plan agent — neither exists yet. The pre-plan hook is thin by design (policy gate / house-context injection).

Phase 1: Discovery & Assumption Brainstorm

Approach this phase like a solution architect meeting with a client to flush out scope and requirements. Your job is not to ask everything — it's to think hard about the shape of the solution before asking grounded questions. Find the integration points, then enumerate the design axes the user probably hasn't thought about.

If a question can be answered by exploring the codebase, explore the codebase instead.

Quick scope check first. If the ask already specifies data model, scope boundaries, and integration points (e.g., "Add an email_verified_at column to users and a SendVerificationEmail job"), do a brief existence-check (do the named files/models exist?) and skip ahead to Phase 2 — the brainstorm below is for under-specified asks.

1. Codebase discovery

Read files specifically related to the ask. Architecture context is already loaded via the <architecture> block at the top of this skill — do not re-read .farseer/architecture.md. Instead:

• Use the terms in the <glossary> block (already loaded; do not re-read it) for task names, test names and issue titles. If a concept you need is missing, propose it to the user as a new entry rather than inventing a synonym.
• Read any .farseer/adr/*.md files for existing architectural decisions, especially before planning changes to a business-critical path listed in architecture.md. If the plan contradicts an ADR, say so explicitly rather than silently overriding it.
• Glob for domain-related files (e.g., for "track books", look for book*, *Book*, library/reading-list files)
• Read existing models, controllers, or components that overlap with the ask
• Note existing patterns the new feature must conform to or extend
• Identify what's already built vs. greenfield

Code Mining Sources (scan entries, expand along call chains)

For every behavioral assertion you encounter — regardless of whether it looks like an "API contract", a "business rule", a "calculation", or a "state transition" — capture it. Sources include:

• Public function signatures: input/output types, error conditions, side effects
• Service-layer conditionals: if/guard clauses that throw or return early based on domain state
• Status transition code: every path that changes an entity's status field
• Validation logic: beyond schema — domain-level validation like "start date before end date"
• Calculation functions: pure computations with domain inputs
• Authorization checks: role-based gates, ownership checks, rate limiters
• Assert statements and database constraints: invariants the code guarantees
• Event emissions and side effects: what happens after a behavior completes
• Saga / compensating actions: rollback logic when multi-step processes fail

Do not skip a behavior because it doesn't fit a category. If the code enforces something, it goes in the spec.

2. Permutation & assumption brainstorm

For each noun and verb in the ask, enumerate plausible interpretations. Then enumerate the hidden axes — design decisions the user almost certainly hasn't specified but the implementer needs to know. Surface the non-obvious ones a senior engineer would catch and a junior would miss.

Focus on permutations that meaningfully change scope, data model, or architecture. Avoid minutiae (button colors, field naming, trivial config defaults).

Example for "track books I'm reading":

• Book schema: title only? +author/ISBN/cover/genre/pages/publication date?
• List structure: one global list, or multiple states ("want to read", "reading", "finished")?
• "Finished" semantics: boolean state, dated event, or reversible?
• Hidden axes the ask didn't mention: auth/multi-user, persistence layer, edit/delete operations, search/filter/sort, ratings/notes, web vs mobile UI, external lookups (ISBN APIs).

3. Diff against codebase

Produce a short "what I found vs. what you asked" comparison. Examples:

• "You have a User model with auth — books would extend it for per-user lists"
• "No models exist yet — this is greenfield"
• "Your existing controllers follow a ResourceController pattern; book routes would conform"

Issue Detection: If the user references a GitHub issue (e.g., "#18", "issue 18", a GitHub issue URL), capture it for the ## Related Issues field in _plan.md. Use Closes #N for issues that will be fully resolved by this plan, or Relates to #N for partial/tangential references. If no issue is mentioned, set the field to "none".

Phase 2: Grounded Clarification

Surface findings to the user, before asking categorized questions. The goal is to flush out enough to write a confident plan — like a solution architect leaving a client meeting with the spec they need.

Invoke the interviewer skill to begin questioning. The interviewer skill will ask the user for clarifications, and you will use the returned answers to refine the plan.

Format your response so users can skim past findings if they want

Present in this order:

What I Found

• {codebase findings: existing models, patterns, integration points, greenfield vs. extension}

Key Permutations to Resolve {1-3 sentences naming the design axes that meaningfully shape scope/data model/architecture, derived from the brainstorm}

Interview

<results from the interviewer skill, with each question and answer clearly labeled>

Phase 3: Define the Plan

Once you understand the requirements, create the plan overview:

Create feature branch:

git checkout -b feature/{plan-name}

If the branch already exists (resuming a plan), check it out instead:

git checkout feature/{plan-name}

Resolve the plans directory, once. It is .farseer/plans. The script prints an absolute path resolved from the project root, so the result does not depend on the working directory:

"{skill-base-dir}/../../hooks/resolve-plans-dir.sh"

Shell variables do not survive between Bash calls. Every $PLANS_DIR below stands for the path the script printed: write that literal path, quoted, into each later command. Never run a command with an unset $PLANS_DIR. An empty value turns mkdir -p "$PLANS_DIR/{plan-name}" into mkdir -p "/{plan-name}".

Never substitute a hand-written jq line or a literal .farseer/plans. A non-zero exit means the project root or the configured value is unusable; surface the script's stderr verbatim and stop rather than falling back to the default — writing plans somewhere the project did not ask for is the failure this indirection exists to prevent.

Create plan directory:

mkdir -p "$PLANS_DIR/{plan-name}"

Use a kebab-case name derived from the feature (e.g., user-authentication, payment-processing). Quote every path built from $PLANS_DIR — a configured directory may contain spaces.

Record the enrollment fingerprint so Phase 6 and orchestrate can detect that hook enrollment changed after planning. Write it by redirecting the script's output:

"{skill-base-dir}/../../hooks/discover-hooks.sh" --fingerprint > "$PLANS_DIR/{plan-name}/.hook-fingerprint"

The file holds exactly that one line and nothing else. Never type a fingerprint value into a command. Every later check reads this file.

Create _plan.md:

# Plan: {Feature Name}

## Created

{date}

## Status

planning | ready | in_progress | completed | blocked

## Objective

{1-2 sentence description of what this plan achieves}

## User Stories

A LONG, numbered list of user stories. Each user story should be in the format of:

`As an <role>, I want a <feature>, so that <benefit>`

Example:

> As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending

**This list of user stories should be extremely extensive and cover all aspects of the feature.**

## Related Issues

{list of GitHub issue references, e.g., "Closes #18", "Relates to #42", or "none"}

## Discovery Notes

{Brief summary of Phase 1 findings: existing models/patterns to extend, integration points, greenfield vs. existing code, key assumptions resolved during clarification. Captures context for future readers and resumed sessions.}

## Scope

### In Scope

- {bullet points of included functionality}

### Out of Scope

- {bullet points of explicitly excluded functionality}

## Success Criteria

- [ ] {measurable outcome 1}
- [ ] {measurable outcome 2}
- [ ] All tests passing
- [ ] Code follows project standards

## Task Overview

| Task | Description | Depends On | Status  |
| ---- | ----------- | ---------- | ------- |
| 001  | {title}     | -          | pending |
| 002  | {title}     | 001        | pending |
| ...  | ...         | ...        | ...     |

## Architecture Notes

{Any architectural decisions or patterns to follow}

## Risks & Mitigations

- {potential risk}: {mitigation strategy}

Phase 4: Break Down into Tasks

Create plan issues directory:

mkdir -p "$PLANS_DIR/{plan-name}/issues"

Break the plan into independently-actionable issues using vertical slices (tracer bullets). Each issue cuts a narrow but complete path through every layer, sized to fit one fresh context window. Create as numbered task files in the plan issues directory. Follow these principles:

Task Sizing:

• Each task is a thin vertical slice that cuts through ALL integration layers end-to-end, NOT a horizontal slice of one layer
• Any pre-factoring should be done first - if the plan needs an existing structure reshaped before the new feature lands cleanly, that is issue number one and everything else blocks on it
• Sizing is context-dependent, not effort. A mechanically large but repetitive change is one issue; a small change requiring the whole plan in mind is another. Use your judgment to size tasks for a single TDD cycle.
• A task typically has 3-7 requirements
• If a task has >7 requirements, split it
• If a task has <3 requirements, consider combining with related task unless it is genuinely independent

Wide refactors are the exception to vertical slicing. A wide refactor is one mechanical change (rename a column, retype a shared symbol) whose blast radius fans across the whole codebase, so a single edit breaks thousands of call sites at once and no vertical slice can land green. Don't force it into a tracer bullet; sequence it as expand–contract. First expand: add the new form beside the old so nothing breaks. Then migrate the call sites over in batches, sized by blast radius (per package, per directory), each batch its own ticket blocked by the expand, keeping tests green batch-to-batch because the old form still exists. Finally contract: delete the old form once no caller remains, in a ticket blocked by every migrate batch. When even the batches can't stay green alone, keep the sequence but let them share an integration branch that all block a final integrate-and-verify ticket; green is promised only there.

Dependency Rules:

• Tasks with no dependencies can run in parallel
• Explicitly declare ALL dependencies (not just immediate ones)
• Avoid circular dependencies
• Maximize parallelism by minimizing unnecessary dependencies

Required Tasks:

• If the plan creates a new package, the final task must create a README.md following the project's Package README Standards (see code-standards.md). This task depends on all other tasks so the README accurately reflects what was built.

Task File Format ({NNN}-{task-name}.md):

# Task {NNN}: {Title}

**Status**: pending
**Depends on**: [{comma-separated task numbers, or "none"}]
**Retry count**: 0

## Description

{2-4 sentences describing what this task accomplishes and why}

## Context

{Any relevant context the implementer needs to know}

- Related files: {list key files to modify or reference}
- Patterns to follow: {reference to existing patterns in codebase}

## Requirements (Test Descriptions)

Write requirements as exact test names. These become the test method names.

- [ ] `it creates a new user with valid email and password`
- [ ] `it rejects duplicate email addresses with validation error`
- [ ] `it hashes passwords before storing in database`
- [ ] `it returns user object with id after successful creation`

## Acceptance Criteria

- All requirements have passing tests
- Code follows code standards
- No decrease in test coverage

## Implementation Notes

(Left blank - filled in by programmer during implementation) {Exception: if the plan produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it here and note briefly that it came from planning. Trim to the decision-rich parts — not a working demo, just the important bits.}

Phase 5: Validate Dependencies

After creating all tasks, verify:

1. No circular dependencies exist
2. Task 001 has no dependencies (or minimal bootstrap)
3. Dependencies form a valid DAG (Directed Acyclic Graph); mechanically check not by eyeball
4. Maximum parallelism is achieved
5. All context exists to complete all tasks autonomously (if not, revisit Phase 2 for additional clarifying questions)

Dependency Visualization: Show the user a simple dependency tree:

001 ─┬─► 002 ─┬─► 005
     │        │
     └─► 003 ─┘
     │
     └─► 004 ────► 006

Phase 6: Run the post-plan Hook

After validating dependencies, resolve and run the agents enrolled at the post-plan hook.

1. Resolve post-plan agents.

Run the discovery script, passing the fingerprint recorded at Phase 3 so a mid-planning change to agent files is caught:

"{skill-base-dir}/../../hooks/discover-hooks.sh" --hook=post-plan --expect="$(cat "$PLANS_DIR/{plan-name}/.hook-fingerprint")"

Never enumerate agent files by hand.

2. Empty-hook fast path.

Exit 0 with empty stdout is an empty hook: return immediately — print nothing, spawn nothing, do no work, say nothing about the hook — and proceed to Phase 7. (No agent declaring phase: post-plan is a valid, clean configuration.) Do not narrate that the script returned no agents.

3. Print the resolved agent order.

On exit 0 with output, PRINT that output verbatim before spawning anything, so the run is auditable.

On any non-zero exit, stop. Surface the script's stderr verbatim and do not proceed to Phase 7. Exit 3 means an agent file declares an invalid phase or mode; exit 4 means enrollment changed since Phase 3. Tell the user to delete .hook-fingerprint and re-run planner to re-baseline. A missing or non-executable script is a hard stop with no fallback.

4. Spawn each agent in the resolved order, sequentially:

Use the Agent tool with subagent_type="farseer:{agent-name}" for an origin=plugin row and subagent_type="{agent-name}" for an origin=local row. The sub-agent prompt must include:

1. The plan name.
2. The resolved plan directory, so the agent never has to read config.json or guess a default:

## Plan Directory

$PLANS_DIR/{plan-name}

3. The Project Context list.

Pass the concrete path, not the literal $PLANS_DIR. Sub-agents stay configuration-unaware by design: one resolver runs here, and every agent is handed a finished path.

5. After each sub-agent completes, read any updated plan files to prepare the recap for the user.

Agents enroll in post-plan by declaring phase: post-plan in their own frontmatter (see HOOKS.md). There is no hardcoded default list here — for example, devils-advocate participates because it declares phase: post-plan in its frontmatter, not because planner names it. To add, remove, or reorder agents at this hook, edit their frontmatter phase/order (or override a plugin agent with a .claude/agents/ file of the same name; phase: none there switches it off).

Phase 7: Review with User

Present the refined plan along with a summary of whatever post-plan agents actually ran in Phase 6.

Here's the plan I've created for {feature name}:

Tasks: {N} total Longest dependency chain: {number of tasks on the longest path through the dependency graph}

#	Task	Dependencies
001	{title}	none
002	{title}	001
...	...	...

If one or more post-plan agents ran, include a review section that summarizes what those specific agents changed. Title it after the agents that ran (e.g. "Post-Plan Review by {agent names that ran}"), and attribute the changes to the agent that made them. Do not assume a single fixed reviewer or hardcode "devil's advocate" — render whatever the resolved Phase 6 hook produced:

Post-Plan Review ({names of agents that ran})

The plan was reviewed by the agents enrolled at the post-plan hook. Here's what each refined:

{for each agent that ran, summarize its changes, e.g.:}

• Added missing dependency: task 005 now depends on 003 (shared interface needed)
• Split task 008 into 008 and 009 (too large for single TDD cycle)
• Added edge case requirements to task 004 (empty state handling)
• Fixed method signature in task 012 (verified against source)

{if there are deferred items from any agent, list them:} Items for your consideration:

• {Items the user may want to weigh in on}

If no post-plan agents ran (the hook was empty), omit the "Post-Plan Review" section entirely — do not print an empty heading or any "reviewed by" line. Present the plan table and go straight to the approval prompt below.

Then, in all cases, ask:

Does this breakdown look correct? Would you like to:

1. Approve and proceed
2. Add/remove tasks
3. Adjust dependencies
4. Modify requirements for a specific task

Make adjustments based on feedback.

Phase 8: Finalize

Once approved:

1. Update _plan.md status to ready
2. Confirm all task files are created
3. Output completion summary:

Plan created: {plan-name}

Location: .farseer/plans/{plan-name}/
Total tasks: {N}
Independent tasks (batch 1): {count of tasks with no dependencies}

4. Ask the user if they want to start execution now:

Ready to begin autonomous implementation?

1. Yes, start now - I'll trigger orchestrate immediately
2. No, I'll run it later - Say "run the {plan-name} plan" anytime to start

Optional, for large plans: set a goal first so execution completes unattended — /goal the {plan-name} plan run reached a terminal state: /farseer:orchestrate output ALL_TASKS_COMPLETE or TASKS_BLOCKED

5. If user chooses to start now:

   • Invoke the /farseer:orchestrate skill with the plan name to begin parallel execution
   • Runs until every task is complete or blocked, starting each task as soon as its dependencies finish

6. If user chooses later:

   • Confirm they can start anytime by saying "run the {plan-name} plan" or "execute the plan"
   • End the skill

Writing Good Requirements

Requirements MUST be written as test descriptions. They should:

Be specific and testable:

• Good: it returns 401 when authentication token is missing
• Bad: it handles authentication errors

Describe behavior, not implementation:

• Good: it sends welcome email after successful registration
• Bad: it calls EmailService.sendWelcome()

Cover edge cases explicitly:

• Good: it rejects passwords shorter than 8 characters
• Bad: it validates password

Be atomic (one assertion per requirement):

• Good: it stores user in database + it returns created user
• Bad: it stores user in database and returns it

Task Examples

Example: User Model Task

# Task 001: Create User Model

**Status**: pending
**Depends on**: none
**Retry count**: 0

## Description

Create the User Eloquent model with authentication fields and basic validation.

## Context

- Related files: `app/Models/User.php` (may exist, needs modification)
- Patterns to follow: Existing models in `app/Models/`

## Requirements (Test Descriptions)

- [ ] `it creates a user with email and password`
- [ ] `it hashes the password automatically when setting`
- [ ] `it validates email is required`
- [ ] `it validates email format is valid`
- [ ] `it validates email is unique`
- [ ] `it validates password minimum length is 8 characters`

## Acceptance Criteria

- All requirements have passing tests
- Migration exists for users table
- Model follows existing patterns

Example: API Endpoint Task

# Task 003: Create Registration Endpoint

**Status**: pending
**Depends on**: 001, 002
**Retry count**: 0

## Description

Create POST /api/register endpoint that creates new users and returns JWT token.

## Context

- Related files: `routes/api.php`, `app/Http/Controllers/AuthController.php`
- Patterns to follow: Existing API controllers

## Requirements (Test Descriptions)

- [ ] `it returns 201 with user data on successful registration`
- [ ] `it returns JWT token in response`
- [ ] `it returns 422 when email already exists`
- [ ] `it returns 422 when email format is invalid`
- [ ] `it returns 422 when password is too short`
- [ ] `it stores user in database on success`

## Acceptance Criteria

- All requirements have passing tests
- Route registered in api.php
- Uses form request for validation

Error Handling

• If user provides vague requirements: Ask specific clarifying questions
• If dependencies create a cycle: Identify and ask user to resolve
• If tasks are too large: Suggest splitting with specific recommendations
• If plan seems incomplete: Ask about edge cases, error handling, security

Output Format

Always end with the clear next steps showing how to execute the plan.