planner

Files (2)

• SKILL.md
• openai.yml · agents/

SKILL.md (first lines)

# 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:

```bash
"{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**:

```bash
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:

```markdown
## 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:

```bash
"{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](#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?

From petemcw/farseer, MIT.

More from petemcw/farseer