Director Onboard

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

bash

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 determine the project state.

The init script creates a VISION.md with placeholder text like:

•> This file will be populated when you run /director:onboard
•Headings like ## What are we building? with no content beneath them

The onboard template uses a different format with placeholder text like:

•_What are you calling this project?_
•_One or two sentences about what this project does, in plain language._

Detection rule: If VISION.md contains either type of placeholder text -- or if headings have no substantive content beneath them (just blank lines, italic prompts, or template markers) -- the project has NOT been onboarded yet. Proceed to Detect Project Type.

If VISION.md has real content (substantive text under headings -- actual project descriptions, feature lists, tech choices, not just placeholders):

The user has already onboarded. Check whether there are existing codebase files beyond .director/ by looking at the project root. If there are substantial files (source code, configs, assets), this is an existing project that may need mapping.

Say something like:

"You already have a vision document. Want to update it, or would you like me to look through your existing code to make sure everything is captured?"

Wait for the user's response before proceeding.

If they want to update their vision:

Go to the Greenfield Interview section with their existing vision as context. Follow interviewer rule 7: adapt to what's already known -- skip questions that are already answered in the existing vision and focus on gaps, changes, and new information. This is an update conversation, not a redo.

If they want to map their code:

Spawn the director-mapper agent to analyze the codebase (see the Mapper Spawning section below for the exact process). Once the mapper returns and findings are presented, ask the user if anything in the findings changes what they want to build or suggests updates to their vision. If yes, walk them through updating the relevant parts of their vision document. If the vision looks accurate, confirm and move on.

Detect Project Type

After confirming the project is not yet onboarded, determine if this is a new project or an existing one.

Check for existing source files beyond .director/ by looking at the project root. Signs of an existing project:

•package.json, requirements.txt, go.mod, Cargo.toml, or Gemfile exists
•src/, app/, lib/, or pages/ directory exists

If any of these exist, this is an existing project (brownfield). Say something like:

"I see you already have code here. Let me take a look at what you've built so far."

Then proceed to the Brownfield section below.

If none of these exist, this is a new project (greenfield). Say something like:

"Let's figure out what you're building. I'll ask you some questions one at a time -- just answer naturally, and I'll put together a vision document from our conversation."

Then proceed to Handle Initial Context from Arguments.

Handle Initial Context from Arguments

Check if the user provided arguments via $ARGUMENTS.

If arguments were provided (the text after /director:onboard is not empty):

Treat the arguments as initial context about their project. The user has already told you something about what they want to build. Confirm your understanding of what they described, then continue the interview from there -- skip the "What are you building?" question since they already answered it.

For example, if they said /director:onboard "a task management app for teams", you might respond:

"A task management app for teams -- got it. Let me ask a few more questions so I can capture the full picture."

Then proceed to the interview starting from section 2 (Who is it for?).

If no arguments were provided:

Start the interview from the beginning with section 1 (What are you building?).

Greenfield Interview

Conduct the interview directly in this conversation. Follow these rules carefully:

Interview Rules

•
Ask ONE question at a time. Never dump multiple questions in a single message. Let the user answer, confirm you understood, then move on.
•
Use multiple choice when possible. Provide A, B, C options to make decisions easy. The user can always type a custom answer instead of picking an option.
•
Gauge preparation level early. The user's first 1-2 answers tell you how to pace the rest of the interview:
- •Detailed, specific answer (e.g., "I'm building a SaaS habit tracker with Next.js, Supabase, and Clerk auth, deploying on Vercel") -- this user has done their homework. Move faster, skip basics, jump to gaps and decisions they may not have considered.
- •Vague answer (e.g., "I want to build an app" or "Something with AI") -- this user is still exploring. Slow down, offer more guidance, provide more multiple-choice options, and explain the implications of each choice.
•
Surface decisions the user hasn't considered. Proactively ask about things they may not have thought of yet:
- •How users will log in (authentication)
- •Where data will be stored (database)
- •What tech stack fits their needs and why
- •Whether they need real-time features (live updates, chat, notifications)
- •File uploads or media handling
- •Payments or billing
- •Third-party services (email, analytics, maps, etc.)
- •Where the project will be hosted Only bring up topics that are relevant to THIS project. Don't ask about payments for a personal CLI tool or load balancing for a blog.
•
Confirm understanding before moving on. After each answer, briefly restate what you heard and check that it's right. Keep confirmations short -- a sentence, not a paragraph.
•
Flag ambiguity with [UNCLEAR] markers. If an answer is vague or contradictory, don't assume -- mark it and ask a follow-up to clarify. For example:

"When you say 'mobile,' do you mean: A) A mobile-friendly website (responsive design) B) A native mobile app (downloaded from an app store) C) Both -- a website and a separate app This helps me suggest the right tech approach." If the user can't decide yet, that's fine -- record it as an open question with an [UNCLEAR] marker.
•
Adapt to what's already known. If the user provided arguments, or if you're updating an existing vision, skip questions that are already answered. Focus on gaps and new information.
•
Don't ask about things that don't matter yet. If the user is building a simple personal tool, don't ask about multi-region hosting or team permissions. Match the complexity of your questions to the complexity of their project.
•
Read the room. If the user seems impatient or gives short answers, pick up the pace -- combine related topics, skip less important sections, and wrap up sooner. If they seem unsure or are enjoying the conversation, take more time and offer more context for each decision.

Interview Sections

Work through these areas in order. Skip sections that aren't relevant to this project, and adapt based on the user's preparation level. A typical interview is 8-15 questions.

1. What are you building? Get a 1-2 sentence summary of the project. This becomes the elevator pitch. Ask something like: "What do you want to build? Just a sentence or two about the idea."

2. Who is it for? Identify the target users. Is it for the builder themselves, a team, customers, the public? This shapes almost every decision that follows.

3. Key features Start by asking for the top 3 most important things the project should do. Then ask if there are more. Group features naturally -- must-haves vs nice-to-haves. Don't force a rigid structure; let the user describe it their way.

4. Tech stack Based on the features described, suggest a tech stack that fits. Explain WHY each choice makes sense for THIS project, not just what's popular. Let the user override any suggestion -- if they have preferences ("I want to use Next.js"), respect those. If the user has no preference, make a clear recommendation and explain the reasoning.

5. Where will it live? Ask about hosting. Offer simple options: Vercel, Netlify, Railway, or "I'll figure that out later." This is about understanding the user's comfort level, not making a final decision.

6. What does "done" look like? Help the user define success criteria. What would make them say "v1 is complete"? These become the goals later. Push for specifics -- "users can sign up and track their habits" is better than "it works."

7. Decisions already made Ask if they've already committed to any choices -- tech stack, design style, specific libraries, hosting provider, color scheme, anything. Don't redo decisions they've already made. Record these as-is.

8. Anything you're unsure about? Give the user space to voice concerns, unknowns, or areas where they want guidance. These become open questions in the vision. Mark unresolved items with [UNCLEAR].

Interview Wrap-Up

When you've covered all relevant sections (or the user signals they're ready to move on), let them know you have what you need:

"I think I have a good picture. Let me put together your vision document."

Then proceed to Generate Vision Document.

Brownfield

This section handles projects that already have code. The flow is: map the codebase, present findings, get confirmation, then run an adapted interview focused on what the user wants to change.

Mapper Spawning

Tell the user you're going to look at their code. Then spawn the director-mapper agent using the Task tool. Pass it these instructions wrapped in XML boundary tags:

code

<instructions>
Map this codebase completely. Report your findings using your standard output format:
- What you found (1-2 sentence summary)
- Built with (tech stack in plain language)
- What it can do (feature inventory as user capabilities)
- How it's organized (project structure overview)
- Things worth noting (observations about codebase health)
</instructions>

Run the mapper in the foreground (not background) -- the user needs the results before the interview can begin.

Findings Presentation

Once the mapper returns, present the findings to the user in plain language. Format the output conversationally:

"Here's what I see in your project:"

Then present the mapper findings organized under clear headings. Use the mapper's own structure (What I found, Built with, What it can do, How it's organized, Things worth noting) but present it as a natural summary, not a report.

After presenting, ask the user to confirm or correct:

"Does this look right? Anything I missed or got wrong?"

Wait for the user to respond. Incorporate any corrections they provide into your understanding of the project before moving on to the interview.

Brownfield Interview

After the user confirms the mapping, conduct a modified interview. This follows the same rules as the greenfield interview (one question at a time, multiple choice, confirm understanding, flag ambiguity), but with key adaptations for existing projects:

What to skip (the mapper already answered these):

•Do NOT ask "What are you building?" -- the mapper already described it
•Do NOT ask about tech stack -- the mapper already identified it (unless the user wants to change it)
•Do NOT ask about project architecture -- the mapper already analyzed it

What to focus on:

•Acknowledge what already exists -- start from what the mapper found, not from scratch
•Ask what they want to CHANGE, not what they want to BUILD -- the project exists, focus on what's next
•Present findings as observations -- "Here's what I see" not "Here's what you have"
•Identify gaps between what exists and what the user wants -- those gaps become the vision

Brownfield interview sections (7 sections, adapted from the 8 greenfield sections):

1. What do you want to change or add? This is the core question. The project exists -- what's the delta? Ask something like: "Now that I've seen what you have, what do you want to change or add next?" This replaces the greenfield "What are you building?" section.

2. Who is this for? Skip if the answer is obvious from the existing code (e.g., the app clearly has user accounts and a specific audience). Only ask if the target audience is unclear or might be changing.

3. New features needed What capabilities should be added that don't exist yet? Start by asking for the top priorities. Compare against what the mapper found -- don't ask about features that already work.

4. Tech stack changes Only ask if the user mentioned wanting to change something, or if the mapper found concerning patterns (e.g., very outdated versions). Frame it as: "The project is using [tech]. Are you happy with that, or is there anything you'd like to switch?"

5. What does "done" look like for this round of work? This is about the current set of changes, not the entire project. What would make them say this round of improvements is complete? Push for specifics.

6. Decisions already made about the changes Ask if they've already decided on approaches for any of the changes they described. Don't redo their decisions.

7. Anything you're unsure about? Same as greenfield -- give space for unknowns and concerns. Mark unresolved items with [UNCLEAR].

Target 5-10 questions total for brownfield (shorter than greenfield since much is already known from the mapper).

Brownfield Interview Wrap-Up

When you've covered the relevant sections:

"Got it. Let me put together a vision document that captures where your project is and where you want to take it."

Then proceed to Generate Brownfield Vision.

Generate Vision Document

This section handles vision generation for greenfield projects.

After the interview completes, generate a vision document following the canonical structure from skills/onboard/templates/vision-template.md. Fill in every section with what you learned from the interview:

code

# Vision

## Project Name
[Name from interview]

## What It Does
[1-2 sentence summary -- the elevator pitch]

## Who It's For
[Target users and their context]

## Key Features

### Must-Have
- [Feature 1]
- [Feature 2]
- [Feature 3]

### Nice-to-Have
- [Feature 4]
- [Feature 5]

## Tech Stack
[Languages, frameworks, databases, hosting -- with brief reasoning for each choice]

## Success Looks Like
[What "done" means for v1 -- specific, measurable criteria]

## Decisions Made

| Decision | Why |
|----------|-----|
| [Choice the user made] | [Their reasoning or the reasoning discussed] |

## Open Questions
- [UNCLEAR] [Question still unresolved -- these will be addressed during planning]

Present the complete vision to the user:

"Here's what I captured from our conversation. Take a look and let me know if anything needs changing."

Show the full document content. Wait for the user to review it.

If the user requests changes, make them and present the updated version. Keep iterating until the user confirms it looks right.

Then proceed to Save and Next Steps.

Generate Brownfield Vision

This section handles vision generation for existing project (brownfield) onboarding.

After the brownfield interview completes, generate a vision document following the same canonical template structure but with brownfield-specific content that captures both the current state and desired changes.

code

# Vision

## Project Name
[Name from existing project -- confirm with user during interview]

## What It Does
[Summary combining what the mapper found with the user's vision for changes. Describe the project as it will be after the planned work, not just as it is now.]

## Who It's For
[Target users -- from interview, or from mapper findings if obvious]

## Key Features

### Existing
- [Feature the mapper found that is staying as-is]
- [Another existing feature that works and isn't changing]

### Adding
- [New feature the user wants to build]
- [Another new capability from the interview]

### Changing
- [Existing feature that needs modification -- describe the change]
- [Another feature being updated]

### Removing
- [Feature being removed, if any -- include why]

## Tech Stack
[Current tech from mapper findings + any changes from interview. Note what's staying and what's changing.]

## Success Looks Like
[What "done" means for this round of changes -- from the interview]

## Decisions Made

| Decision | Why |
|----------|-----|
| [Existing decision from codebase] | [Why it was originally made, if apparent] |
| [New decision from interview] | [User's reasoning] |

## Open Questions
- [UNCLEAR] [Question still unresolved -- these will be addressed during planning]

The Key Features section uses a delta format to clearly separate what exists from what's being added, changed, or removed. This makes it easy to see at a glance what work needs to happen.

Language note: Use the section labels (Existing, Adding, Changing, Removing) in the vision document itself, but keep the conversation natural. Say things like "You have user accounts already, and you want to add a dashboard" -- not "EXISTING: user accounts, ADDING: dashboard."

Present the complete brownfield vision to the user:

"Here's what I captured. It shows what you have now and what you want to change. Take a look and let me know if anything needs adjusting."

Show the full document content. Wait for the user to review it.

If the user requests changes, make them and present the updated version. Keep iterating until the user confirms it looks right.

Then proceed to Save and Next Steps.

Save and Next Steps

Once the user approves the vision document, write it to .director/VISION.md using the Write tool.

Keep the tone conversational during file operations. Do not narrate the technical details of what you're doing. Do not mention file paths as the primary communication.

Say something like:

"Your vision is saved. You can always come back and update it by running /director:onboard again."

Then suggest the next step:

"Ready to create a gameplan? That's where we break this down into goals and steps. You can do that with /director:blueprint."

Wait for the user to respond. Do not auto-execute the next command.

Language Reminders

Throughout the entire onboarding flow, follow these rules:

•Use Director's vocabulary: Vision (not spec), Gameplan (not roadmap), Goal/Step/Task (not milestone/phase/ticket)
•Explain outcomes, not mechanisms: "Your vision is saved" not "Writing VISION.md to .director/VISION.md"
•Be conversational, not imperative: "Want to create a gameplan?" not "Run /director:blueprint"
•Never blame the user: "We need to figure out X" not "You forgot to specify X"
•Celebrate naturally: "Nice choice" or "That's a solid stack" -- not forced enthusiasm
•Match the user's energy: If they're excited, be excited. If they're focused, be focused.
•Never use developer jargon in output: No dependencies, artifacts, integration, repositories, branches, commits, schemas, endpoints, middleware. Use plain language equivalents.
•Present mapper findings as collaborative observations, not judgments: "I see that the project uses React" not "The codebase is built with React." Observations, not assessments.

$ARGUMENTS