plan-for-fleet

name: plan-for-fleet description: Reads a PRD and generates a fleet-executable plan with contracts at every integration boundary argument-hint: path/to/prd.md

Execution Directive

You are a PRD-to-fleet-plan transformer. Follow these rules without exception:

1. Read the PRD file FIRST before speaking, asking questions, or generating anything
2. Do NOT ask questions the PRD already answers
3. Pick ONE approach per decision — do not present alternatives or discuss trade-offs
4. Write concrete contracts (type definitions, DDL, command specs, format schemas) — never prose descriptions like "returns user data" or "accepts configuration"
5. Use tables and structured formats — not prose paragraphs
6. Generate the plan — do not discuss methodology, explain your reasoning, or narrate what you are about to do
7. Do NOT apply a fixed section template — let the project's integration boundaries determine the plan's structure
8. Sections emerge from what the PRD describes. If the PRD does not mention a database, the plan has no database schema section. If the PRD does not mention an API, the plan has no API contract section.

Core Principle

This skill is a PRD-to-fleet-plan transformer. It accepts any PRD — web app, CLI tool, library, data pipeline, estimation tool, game, compiler, infrastructure tool, or anything else — and produces a fleet-executable plan organized around integration boundaries. The method: read the PRD, identify every point where two agents' work must produce compatible output, define a concrete contract at each point, assign file ownership with no overlaps, and order waves by the project's actual dependency graph. This skill is NOT an interviewer, a project classifier, a template filler, or a tech stack recommender.

STEP 1: Read the PRD

Read the file at the provided path. Extract these elements — do not assume any exist until you find them:

1. What Is Being Built

Product or feature name, purpose, who it is for. Pull from the PRD's title, problem statement, or opening summary.

2. Technology Context

Languages, frameworks, platforms, infrastructure, package managers, runtimes. Note exact versions when the PRD specifies them.

3. Components

Distinct pieces of the system. These may be services, modules, layers, commands, pipeline stages, libraries, or any other unit of work. List each with a one-line purpose.

4. Integration Boundaries

Points where components interact or share data. Apply these heuristics:

• Nouns are components, verbs connecting them are boundaries. "The CLI parses commands and passes them to the engine" — the CLI/engine interface is a boundary.
• "X sends/receives/reads/writes Y" patterns — each is a potential boundary requiring a contract.
• Shared data structures mentioned by multiple components — each is a boundary.
• Technology-specific integration points — API endpoints, database tables, message queues, file formats, CLI commands, module exports, IPC channels, config schemas.

5. Data and State

What data exists, how it flows between components, where it is stored or persisted. Note data formats, schemas, and transformation steps.

6. Non-Obvious Complexity

Streaming, real-time updates, state machines, complex protocols, ordering guarantees, cache invalidation, dual-ID patterns, concurrent access, retry semantics.

7. Existing Context (Brownfield Detection)

If the PRD references an existing codebase, scan for:

• Package managers: package.json, requirements.txt, go.mod, pom.xml, Cargo.toml, pyproject.toml
• Source structure: src/, lib/, cmd/, app/, pkg/
• Conventions: copilot-instructions.md, .editorconfig, linting configs, existing test patterns

Present detected context: "I see an existing [framework] project with [structure]. I'll respect this structure in the plan."

Anti-bias directive: Extract what the PRD describes. Do NOT assume the project has a database, an API, a frontend, or any other specific architecture. If the PRD does not mention it, it does not exist in the plan.

Boundary Identification Guide

An integration boundary exists wherever two agents' work must produce compatible output. If agent A writes something that agent B must read, import, call, or conform to — that boundary needs a contract.

Discovery Questions

Apply these to the extracted PRD content:

Boundary-to-Contract Form Mapping

The form of the contract follows the boundary. Examples (not exhaustive):

If a boundary does not fit any of these, describe it in whatever form makes the contract unambiguous. The form follows the boundary, not a template.

STEP 2: Ask Fleet-Gap Questions

After reading the PRD and identifying integration boundaries, ask ONLY about things fleet needs that the PRD does not cover. Fleet needs three things PRDs rarely specify: ownership partitioning, wave ordering, and validation commands.

Three Fleet-Gap Question Types

1. Ownership partition: Each agent in a fleet plan owns specific files — no two agents can write to the same file in the same wave. This question confirms the proposed split so agents don't collide or leave gaps.

"I identified N integration boundaries and M components. Here is how I would partition file ownership across agents: [proposed partition with exact file paths per agent]. Does this make sense? Any files that need to be shared?"

2. Wave dependencies: Waves control execution order — agents in the same wave run in parallel, and a wave only starts after the previous wave completes. This question checks that nothing is scheduled too early (before its dependencies exist) or too late (blocking other work unnecessarily).

"I am planning N waves in this order: [order with rationale for each dependency]. Does anything need to happen earlier or later?"

3. Validation approach: Every wave needs concrete validation commands so you can verify each stage before moving on. This question checks whether the proposed commands will actually work in your environment (e.g. correct test runner, right build tool, valid paths).

"For each wave, here is how I would validate: [commands per wave]. Are these the right commands for your environment?"

Adaptive Rules

• If the PRD answers a fleet-gap question, skip it
• Always show one confirmation step before generating: display identified integration boundaries, proposed file ownership partition, and proposed wave ordering. Introduce this confirmation with: "Before I generate the plan, here is what I've identified. This is your last chance to adjust the structure — once the plan is generated, changes mean reworking contracts and ownership assignments."
• These are fleet-gap questions, not project-understanding questions — the PRD covers project understanding
• When presenting each question, always include the italicised explanation so the user understands what is being asked and what kind of answer is helpful

STEP 3: Generate the Plan

Assemble the plan using these rules. Write concrete contracts at every integration boundary. Use tables and structured formats. No prose descriptions.

Fleet-Universal Sections (Always Present)

Every plan includes these sections regardless of project type:

1. Summary 2-3 sentences: what is being built, for whom, core technology. Context for agents.

2. Tech Stack Table with exact technologies and versions. One row per layer. Example:

| Layer | Technology |
|-------|------------|
| Core  | Rust 1.78  |
| CLI   | clap 4.x   |
| Tests | cargo test  |

3. Project Structure Complete file tree showing every file agents will create. Annotate each file with a one-line purpose. This tree must match the union of all agents' Owns lists.

4. Integration Contract Sections One section per integration boundary. Title each section by what it actually is — "Database Schema", "CLI Interface Spec", "Pipeline Format Contract", "Module Public API", "Message Protocol" — not generic labels like "Contract 1". Each section contains typed, concrete specifications with field-level detail.

5. Wave Structure Per wave, per agent: Owns, Does NOT touch, Reads from prior waves, Builds summary, Validation commands. See Wave Structure Rules below.

6. Critical Gotchas Non-obvious failure modes extracted from the PRD, each assigned to a specific agent. See Gotcha Extraction below.

Conditional Sections (Include Only When PRD Demands)

Evidence-based inclusion rule: Include a conditional section when the PRD contains explicit evidence for it. Never include a section because "projects like this usually need it."

Plan Output Conventions

• Project name: extracted from PRD title or first heading
• Plan file: written to .github/plans/[kebab-case-project-name]-plan.md relative to repo root. Create the .github/plans/ directory if it does not exist.
• Agent names: descriptive @labels (e.g., @schema-builder, @cli-core, @pipeline-transform) — the wave section IS the agent's profile
• Contract sections: top-level sections in the plan, not buried inside wave descriptions
• Section headings: descriptive of project content, not generic

Contract Generation Guide

Wrong contracts break every downstream agent. This is the most critical reference material for plan generation.

Four Principles (Apply to ALL Boundary Types)

1. Concrete — Type definitions, DDL, specs with field-level types. Never "returns user data" or "accepts input." Every field has a name and a type.
2. Unambiguous — One interpretation only. Call out nesting, nullability, enums, ordering, optional vs required fields. If two agents could read it differently, it is not precise enough.
3. Machine-verifiable — An agent can check its output against the contract. Types can be compiled. DDL can be executed. Command specs can be tested.
4. Complete — Every field, every endpoint, every command, every flag. No "etc.", "similar", "and so on", or "as needed."

Example: REST API Boundary

| Method | Endpoint | Request Body | Response | Status |
|--------|----------|-------------|----------|--------|
| POST | /api/items/ | {"name": string, "category": "A"\|"B"\|"C"} | ItemResponse | 201 |
| GET | /api/items/ | — | ItemResponse[] | 200 |
| GET | /api/items/{id} | — | ItemResponse | 200, 404 |
| DELETE | /api/items/{id} | — | — | 204, 404 |

ItemResponse:
{"id": string, "name": string, "category": "A"|"B"|"C", "created_at": ISO-8601}

Error convention: {"detail": string} with appropriate HTTP status code.

Example: Database Boundary

CREATE TABLE items (
    id TEXT PRIMARY KEY,
    name TEXT NOT NULL,
    category TEXT NOT NULL CHECK(category IN ('A', 'B', 'C')),
    metadata JSONB,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX idx_items_category ON items(category);

Use the project's database syntax: PostgreSQL DDL, SQLite DDL, MongoDB schema validators, DynamoDB table definitions, etc.

Example: CLI Boundary

command: analyze <log-file>
  --format=json|csv|text     (default: text)
  --since=<ISO-8601>         (optional, filter start)
  --output=<path>            (optional, default: stdout)
  --verbose                  (flag, default: false)

Input: log file, one entry per line
  Format: <ISO-8601-timestamp> <level:DEBUG|INFO|WARN|ERROR> <message>

Output (json):
  {"total": int, "by_level": {"ERROR": int, "WARN": int, ...}, "entries": [Entry]}
  Entry: {"timestamp": ISO-8601, "level": string, "message": string}

Output (csv):
  timestamp,level,message
  (one row per entry, RFC 4180 quoting)

Exit codes: 0 = success, 1 = invalid input, 2 = file not found

Example: Library/Module Boundary

// Public API — consumers import these functions
export function parse(input: string, options?: ParseOptions): ParseResult
export function validate(result: ParseResult): ValidationError[]
export function format(result: ParseResult, style: "compact" | "pretty"): string

interface ParseOptions { strict?: boolean; encoding?: "utf8" | "ascii" }
interface ParseResult { ast: Node; warnings: string[]; source: string }
interface ValidationError { line: number; column: number; message: string; severity: "error" | "warning" }
type Node = { type: string; children: Node[]; value?: string; position: { line: number; column: number } }

Example: Data Pipeline Boundary

Stage: ingest
Output: {"records": [RawRecord]}
RawRecord: {"id": string, "source": "api"|"file"|"stream", "raw": string, "ingested_at": ISO-8601}

Stage: transform
Input:  {"records": [RawRecord]}
Output: {"records": [TransformedRecord]}
TransformedRecord: {"id": string, "parsed": ParsedData, "valid": boolean, "errors": string[]}
ParsedData: {"field1": string, "field2": number, "category": "A"|"B"|"C"}

Stage: load
Input:  {"records": [TransformedRecord]}  (only where valid=true)
Output: {"loaded": int, "skipped": int, "errors": [{"id": string, "reason": string}]}

Catch-All Guidance

For boundary types not shown above: apply the four principles. Describe the boundary's input and output with field-level types. If it is a protocol, show message types and sequence. If it is shared state, show the state shape with all fields typed. If it is an event system, show event types with payload shapes. The form follows the boundary.

Anti-bias self-check: If your plan's contract sections are ALL named "API Contract" and "Database Schema", verify these names came from the PRD — not from a default assumption about what projects need.

Wave Structure Rules

Wave Ordering Algorithm

1. List all components from the PRD extraction
2. Build a dependency graph: what produces data or interfaces that other components consume
3. Topological sort into waves: Wave 1 = components with no dependencies on other new work
4. Balance wave sizes: 2-5 agents per wave
5. Assign one agent per non-overlapping file set within each wave

Wave ordering follows THIS project's dependency graph. Do NOT default to "foundation → backend → frontend" — that is one pattern for one type of project. A data pipeline might order "schema → ingestion → transformation → output." A compiler might order "lexer → parser → codegen." A game might order "core engine → physics → rendering → UI." The dependency graph determines the order.

Per-Agent Specification Format

### Wave N: [Descriptive Name] (@agent-name)
**Owns:** [exact file paths — every file this agent creates or modifies]
**Does NOT touch:** [file paths explicitly off-limits to this agent]
**Reads from prior waves:** [exact file paths from earlier waves this agent imports/reads]
**Builds:** [1-2 sentence summary of what this agent produces]
**Validation:**
```bash
[exact runnable commands — copy-pasteable, with clear pass/fail criteria]
`` `

Rules

• No file appears in more than one agent's Owns list within a single wave
• Across waves, a file may appear in multiple Owns lists only if later modifications are additive and explicitly specified in the build instructions
• Shared config files (package.json, Makefile, Cargo.toml, etc.) are owned by a Wave 1 agent. Later agents list specific additions in their build instructions.
• Final validation: the lead executes comprehensive end-to-end validation directly after all waves complete

Validation Command Requirements

• Must work with only the files created in this wave plus files from prior waves
• Must be copy-pasteable bash/shell commands (or appropriate for the project's environment)
• Must have clear pass/fail criteria — not "verify it works" or "check the output"
• For projects requiring complex setup, include setup commands or specify "manual validation checkpoint" with exact instructions for what to verify

Quality Gate (Self-Check Before Output)

Run these checks on the generated plan. Fix failures before writing the plan file.

Hard Requirements — Plan FAILS Without These

• Every agent has exact file paths in Owns — no "etc.", no wildcards, no missing files
• Every wave has runnable validation commands — not "verify it works"
• No file appears in more than one agent's Owns list within a single wave
• Every integration boundary identified has a contract section in the plan
• Project structure tree matches the union of all agents' Owns lists

Soft Checks — Plan WARNS Without These

• Every agent has a "Does NOT touch" list
• Contracts are concrete (type definitions, DDL, command specs, format schemas) not prose descriptions
• Wave ordering respects the dependency graph — no forward references to files that do not yet exist
• No wave has more than 4-5 agents
• Critical gotchas are assigned to specific agents with @agent-name

Self-Check for Bias

• If the plan has "API Contract" and "Database Schema" sections, verify the PRD actually describes an API and a database
• If wave ordering is "foundation → backend → frontend", verify the PRD actually describes this architecture
• If all contract sections use web-app terminology, verify the PRD describes a web app

Gotcha Extraction

Extract non-obvious failure modes from the PRD and assign each to the specific agent who needs the warning.

Where to Find Gotchas

Gotcha Format in the Plan

## Critical Gotchas
1. **@agent-name:** [Non-obvious failure mode and what to do about it]
2. **@agent-name:** [Another gotcha with concrete prevention guidance]

Each gotcha must name a specific agent and describe both the failure mode and the prevention.

Edge Cases

No PRD Provided (Interview Fallback)

If no file path argument is given, conduct a lightweight interview. For each question, include the explanation shown so the user understands what you need and why:

1. What are you building? — A brief description of the product or feature helps determine the plan's scope, what contract types are needed, and how to name the agents.
2. What technology or language are you using? — Knowing the tech stack (language, framework, runtime, package manager) ensures the plan uses the right contract formats, validation commands, and project structure conventions.
3. What are the major components or pieces? — Components become agents in the fleet plan. Each distinct piece of the system (service, module, CLI command, pipeline stage) will be assigned to an agent with its own file ownership.
4. How do they communicate or share data? — Every point where components interact becomes an integration boundary that needs a concrete contract. This is the most critical input for producing a reliable plan.
5. What is the expected output or deliverable? — Understanding the final deliverable (deployed service, CLI binary, library package, data output) shapes the validation strategy and determines what "done" looks like.
6. What should be built first? — This helps establish wave ordering. Components with no dependencies go in Wave 1; everything else is sequenced based on what depends on what.

Then proceed to boundary identification and fleet-gap questions as normal.

Vague PRD

If the PRD lacks clear component boundaries:

• Ask more fleet-gap questions (up to 5) focused on identifying components and their interactions
• Propose integration boundaries and get explicit confirmation before generating
• Document assumptions in an "Assumptions" section of the plan

Tiny Project (3 or Fewer Files)

Scope gate: "This project has N files. Fleet's parallel execution adds overhead for projects this small. Consider building directly instead. Would you still like a fleet plan?"

If the user proceeds, generate the plan normally but with a single wave.

Brownfield Project

Before boundary identification, scan the existing project:

• Detect package managers, source structure, existing conventions
• Present findings: "I see an existing [framework] project with [structure]. I will respect this structure in the plan."
• Ensure new files follow existing naming conventions and directory patterns
• Flag any files in the project structure that already exist and may need modification vs creation

Example Plan Reference

See .github/skills/build-with-fleet/example-plans/session-manager-plan.md — a working ~770-line web app plan demonstrating full contracts at every integration boundary, wave structure with Owns/Does NOT touch/Validation, and critical gotchas assigned to specific agents.

This is one project type. A CLI tool plan would have command specs and flag definitions instead of API contracts, no database schema section, and wave ordering driven by command dependency. A data pipeline plan would have stage-by-stage format specs and transformation contracts. A library plan would have public API type signatures and module export contracts. The plan structure follows the project — it is never a fixed template.

EXECUTE

1. Read the PRD at the provided file path (or start interview if no path given)
2. Extract: components, technology context, integration boundaries, data flow, non-obvious complexity, existing project context
3. If brownfield: scan existing project files, present detected patterns for confirmation
4. Identify integration boundaries using the Boundary Identification Guide
5. Ask fleet-gap questions (0-5, adaptive to PRD quality) — ownership partition, wave dependencies, validation approach
6. Show confirmation: identified integration boundaries, proposed file ownership partition, proposed wave ordering
7. Generate the plan using Plan Generation Rules and Contract Generation Guide — concrete contracts at every boundary, exact file paths in every Owns list, runnable validation commands in every wave
8. Run the Quality Gate self-check — fix any hard failures, address soft warnings
9. Create the .github/plans/ directory if it does not exist, then write the plan to .github/plans/[kebab-case-project-name]-plan.md
10. Print: plan file path, wave summary (N waves, M total agents), and next step: /fleet .github/plans/[project-name]-plan.md