Director:blueprint

Director Blueprint

First, check if .director/ exists. If it does not, run the init script silently:

bash "${CLAUDE_PLUGIN_ROOT}/scripts/init-director.sh"

Say only: "Director is ready." Then continue with the steps below.

---

Determine Project State

Read .director/VISION.md and check whether it has real content beyond the default template.

Template detection for VISION.md: If the file contains placeholder text like > This file will be populated when you run /director:onboard, or italic prompts like _What are you calling this project?_, or headings with no substantive content beneath them (just blank lines, template markers, or italic instructions), the project has NOT been onboarded yet.

If VISION.md is empty or still the default template:

Say something like:

> "Before creating a gameplan, we need to understand what you're building. Want to start with /director:onboard? It's a quick interview to capture your vision."

Wait for the user's response. If they agree, proceed as if they invoked /director:onboard -- run through the onboard flow to capture their vision first.

If VISION.md has real content, read .director/GAMEPLAN.md and check whether it has real content.

Template detection for GAMEPLAN.md: Check for ALL of these signals:

• The init template phrase: This file will be populated when you run /director:blueprint
• The placeholder text: _No goals defined yet_
• Whether there are actual goal headings with substantive content beneath them (real goal names, descriptions, steps -- not just template markers)

If GAMEPLAN.md contains only template/placeholder text and no actual goal definitions, this is NEW gameplan mode. Continue to Handle Arguments below.

If GAMEPLAN.md has real content (actual goal names with descriptions, steps listed, etc.), this is UPDATE mode. Skip to the Update Mode section below.

---

Handle Arguments (New Gameplan Mode)

This section applies only in new gameplan mode. Update mode has its own argument handling.

If $ARGUMENTS is non-empty, acknowledge it before proceeding:

> "You want to focus on [arguments]. Let me read your vision and create a gameplan."

If $ARGUMENTS is empty, say something like:

> "Let me read your vision and put together a gameplan."

---

Check for Open Questions

Before generating goals, scan the VISION.md content for [UNCLEAR] markers.

If [UNCLEAR] markers are found, present them to the user:

> "Before we plan, I noticed some open questions in your vision:" > > 1. [First UNCLEAR item] > 2. [Second UNCLEAR item] > > "Want to resolve these now, or should I plan around them? If we skip them, some tasks might need adjustment later."

Wait for the user's response. If they want to resolve the questions, work through each one conversationally. Update your understanding of the vision accordingly (but do NOT rewrite VISION.md here -- that happens via /director:onboard).

If the user wants to defer, note the unresolved items and proceed. Keep them in mind when generating tasks -- tasks affected by unclear items should note this in their "Needs First" section.

If no [UNCLEAR] markers are found, proceed directly to goal generation.

---

Check Context Freshness

Before loading research context, check whether the project's research and codebase analysis files are still current.

1. Read .director/config.json and extract context_generation.completed_goals_at_generation. If the context_generation field does not exist (backward compatibility with pre-Phase 16 projects), default to 0.
2. Count the current number of completed goals by scanning .director/goals/ directories. A goal is "completed" if its GOAL.md Status section shows "Complete" or all its steps' tasks are .done.md files.
3. Calculate the delta: current_completed_goals - completed_goals_at_generation.
4. If delta >= 2: show a brief, non-blocking alert to the user before proceeding. Something like:

> "Your project research and codebase analysis were done a while ago -- you've finished [N] goals since then. You might want to run /director:refresh to update them. Continuing with what we have for now."

1. If delta /dev/null`.

If the file exists and has content, store its contents internally wrapped in a `` tag:

[Contents of SUMMARY.md]

This research context informs goal generation and step planning -- use it to:

• Suggest goals that align with research-recommended architecture patterns
• Prefer technologies and approaches recommended by the research
• Incorporate "Don't Hand-Roll" warnings when relevant to goal/step sizing
• Reference research findings when explaining goal rationale to the user

If the file does not exist or is empty, proceed silently. Do NOT mention missing research to the user or agent. Do NOT include an empty `` tag.

This context is a bonus -- it makes planning smarter when available but changes nothing when absent.

---

Phase 1: Generate and Review Goals

Read the full content of VISION.md to understand the project. Then generate goals following the planning rules below.

Planning Rules

These rules govern how the gameplan is structured. Follow them throughout the entire planning process.

Rule 1: Goals are outcomes, not activities

A goal describes what the user will HAVE when it's complete, not what you'll DO to get there.

Good goals (outcomes -- what users can do):

• "Users can sign up, log in, and manage their accounts"
• "The dashboard shows real-time data with filters and search"
• "Payments work end-to-end: checkout, receipts, and refunds"

Bad goals (activities -- what you'll build):

• "Build authentication system"
• "Create dashboard components"
• "Implement Stripe integration"

If you catch yourself writing a goal that starts with "Build", "Create", "Implement", "Set up", or "Configure", rewrite it as what users can do when it's complete.

Rule 2: Steps are verifiable chunks of work

Each step delivers something the user can see or interact with. A step is complete when you can point to what it produced.

Good steps:

• "Login page with form validation and error messages"
• "Product listing page with search and filtering"
• "Email notifications for order confirmations"

Bad steps:

• "Set up database models"
• "Configure API routes"
• "Write utility functions"

Rule 3: Tasks are single-sitting work units

A task is something that can be completed in one focused session. It should be clear enough that someone could start working immediately.

Each task includes five fields:

• What To Do -- Plain-language description
• Why It Matters -- How this connects to the bigger picture
• Size -- Small, medium, or large (see Complexity Indicators below)
• Done When -- 3-5 specific, observable checklist items
• Needs First -- What capabilities the project must have before this task can start, in plain language

Rule 4: Order by what's needed first

If the login page needs user accounts in the database, the database setup comes before the login page. Express this as "Needs the user database set up first" not "Depends on TASK-03."

Never use task IDs, technical identifiers, or jargon for prerequisites. Users think in capabilities, not identifiers.

Never say: "Depends on TASK-03" or "Blocked by AUTH-01" or "Prerequisite: database migration" Always say: "Needs the user database set up first" or "Needs the login page built first"

Rule 5: Use ready-work filtering

Mark tasks as "ready" only when everything they need is already complete. When presenting the gameplan, make it clear which tasks can be started right now.

• Tasks with no prerequisites: marked "Ready"
• Tasks with unmet prerequisites: show what they need in plain language

Rule 6: Prefer vertical slices over horizontal layers

Build complete features one at a time, not all database models first, then all API routes, then all UI.

Good order (vertical slices -- users see working features sooner):

1. Complete login flow (database + API + UI for login)
2. Complete signup flow (database + API + UI for signup)
3. Complete profile page (database + API + UI for profiles)

Bad order (horizontal layers -- nothing works until everything is done):

1. Create all database models
2. Create all API routes
3. Create all UI pages

Complexity Indicators

Help users understand the scope of each task:

| Size | What It Means | Typical Scope | |------|--------------|---------------| | Small | Quick change, straightforward | Single file, clear approach, under 30 minutes | | Medium | Some decisions involved | Multiple files, a few choices to make, 30-90 minutes | | Large | Significant work, may need research | Multiple files, important decisions, possibly new tools or libraries, 90+ minutes |

These are effort indicators, not time estimates. "Small" means "simple and clear," not "exactly 15 minutes."

Generate Goals

Using the vision content and the rules above, generate 2-4 goals as outcomes. Each goal should have a name (what users can do) and a 1-2 sentence explanation of why it matters.

Present ALL goals together (not one at a time) in numbered format:

> Based on your vision, here are the goals I'd suggest: > > 1. [Goal as outcome] -- [Why this matters for the project] > 2. [Goal as outcome] -- [Why this matters for the project] > 3. [Goal as outcome] -- [Why this matters for the project] > > Does this feel right? Want to add, remove, or rearrange anything?

Wait for the user's response. If they give feedback (add a goal, remove one, rename one, reorder them), adjust the goal set and re-present. Iterate until the user approves.

Important: Do NOT generate Steps or Tasks yet. Goals must be approved before proceeding.

---

Save Goals Early

Once the user approves the goals (before generating Steps and Tasks), write an early version of GAMEPLAN.md immediately. This persists the high-level structure so the user can find it outside the chat.

Write .director/GAMEPLAN.md with the approved goals:

# Gameplan

## Overview

[A brief summary of what this project is building and how we're approaching it. 2-3 sentences drawn from the vision.]

## Goals

1. **Goal 1: [Goal Name]** -- [One-line description]
2. **Goal 2: [Goal Name]** -- [One-line description]
3. **Goal 3: [Goal Name]** -- [One-line description]

## Current Focus

Steps and tasks are being planned...

This is a SILENT operation -- do NOT tell the user you wrote the file. The full gameplan (with steps and tasks) will overwrite this file later in "Write Gameplan." The purpose is to persist the goal structure early so it's not trapped in the chat window.

---

Phase 2: Generate Full Hierarchy

After the user approves the goals, generate Steps and Tasks for each goal.

For each approved goal:

• Generate Steps as verifiable chunks of work (Rule 2). Each step delivers something visible.
• For each step, generate Tasks with all five required fields (Rule 3): What To Do, Why It Matters, Size, Done When, Needs First.
• Order steps and tasks following vertical slices (Rule 6) and dependency ordering (Rule 4).
• Mark tasks with no unmet prerequisites as "Ready".
• Target 2-5 steps per goal and 2-7 tasks per step.

Present the full outline with one-line descriptions and size indicators:

> Here's the complete gameplan: > > Goal 1: [Goal Name] > > Step 1: [Step name] > - [Task name] (size) -- Ready > - [Task name] (size) -- Needs [capability] > > Step 2: [Step name] > - [Task name] (size) -- Needs [capability] > - [Task name] (size) -- Needs [capability] > > Goal 2: [Goal Name] > > Step 1: [Step name] > - [Task name] (size) -- Needs [capability from Goal 1] > - [Task name] (size) -- Needs [capability] > > Does this look good? Want to change the order, add anything, or remove anything?

Wait for explicit approval. If the user gives feedback, adjust and re-present. Iterate until they approve.

Important: Do NOT write any files until the user explicitly approves this outline.

---

Capture Step-Level Decisions

After the user approves the full hierarchy outline and before writing files, extract decisions from the conversation.

What counts as a decision

A decision is a statement the user made about HOW something should be built. Look for:

• Technology choices: "use Supabase", "stick with REST", "use Tailwind"
• Design direction: "keep the UI simple", "no animations", "single-page layout"
• Implementation approach: "server-side rendering", "use existing auth library"
• Scope boundaries: "skip dark mode for now", "don't worry about mobile yet"

What is NOT a decision (these belong in vision or task descriptions):

• General project descriptions ("it's a task management app")
• Feature requests ("I want users to be able to share lists")
• Goal definitions ("users can manage their accounts")

How to capture decisions

1. Review the entire conversation (both Phase 1 goal discussion and Phase 2 hierarchy discussion) for statements matching the categories above.

1. For each decision found, determine which step it most affects. If a decision is cross-cutting (e.g., "use PostgreSQL for everything"), assign it to EVERY step where it is relevant. Duplicate the decision into each affected step rather than creating an inheritance mechanism.

1. Categorize each decision:

• Locked: User said "use X" or "I want Y" or "make sure Z" -- an explicit directive about how to build something.
• Flexible: User said "I don't care about X" or "whatever works" or simply did not express a preference on a choice point that the planner surfaced. Include brief context when available (e.g., "Styling approach -- user has no preference").
• Deferred: User said "not now" or "save for later" or "skip X for now" -- explicit scope boundary.

1. Associate each decision with the step(s) it affects.

Important rules

• Do NOT ask the user to enumerate their decisions. Extract them passively from the natural conversation. This should be invisible to the user -- they see their gameplan written, and the decisions they expressed are captured without any additional interaction.
• Do NOT create Flexible items for every conceivable choice. Only include Flexible items where the conversation specifically surfaced a choice point and the user expressed no preference. Silence on a topic is not a Flexible decision -- it just means the builder has normal discretion.
• If a step has no relevant decisions from the conversation, OMIT the Decisions section entirely from that step's STEP.md. Do not write empty categories.

---

Step-Level Research

After capturing step-level decisions and before writing gameplan files, run step-level research for steps that need it. This investigates the technical domain of each qualifying step and produces a RESEARCH.md in the step directory for the planner to use when writing task files.

Skip Conditions

Skip this entire section if ANY of the following are true:

• workflow.step_research is false in .director/config.json (read with fallback: default to true if the field doesn't exist -- backward compatibility for projects initialized before this feature)
• $ARGUMENTS includes --skip-research
• This is update mode and no pending/new steps have changed (all steps are either frozen/completed or unchanged)

Force fresh research for all pending steps if $ARGUMENTS includes --research (delete existing RESEARCH.md files for pending steps and re-research).

Assess Step Complexity

For each step in the approved outline, determine whether it needs research. This is a judgment call -- not every step warrants investigation.

Research likely NEEDED when:

• Step involves technology the project hasn't used before
• Step includes Large-sized tasks
• Step involves third-party integrations or APIs
• Onboarding research flagged this domain fo

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: noahrasheta
• Source: noahrasheta/director
• License: MIT
• Homepage: https://director.cc/

Install and usage instructions live in the source repository linked above.