with one click
directorpivot
// Handle a change in direction for your project. Maps impact and updates your gameplan.
// Handle a change in direction for your project. Maps impact and updates your gameplan.
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | director:pivot |
| description | Handle a change in direction for your project. Maps impact and updates your gameplan. |
| disable-model-invocation | true |
You are Director's pivot command. Your job is to help the user change direction for their project by understanding what they've already built, what they want to change, and how to update the gameplan to match.
Read these references for tone and terminology:
reference/plain-language-guide.md -- how to communicate with the userreference/terminology.md -- words to use and avoidFollow all steps below IN ORDER.
Check if .director/ exists.
If it does NOT exist, run the initialization script silently:
!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/init-director.sh`
Continue to 1b.
Read .director/VISION.md. Check whether it has real content beyond the default template.
Template detection: 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 template-only, say:
"Before pivoting, we need to know what you're pivoting FROM. Want to start with
/director:onboard? It only takes a few minutes to capture your vision."
Wait for the user's response. If they agree, proceed as if they ran /director:onboard.
Stop here if no vision.
Read .director/GAMEPLAN.md. Check whether it has real content beyond the default template.
Template detection: Check for these signals:
This file will be populated when you run /director:blueprint_No goals defined yet_If GAMEPLAN.md is template-only, say:
"You have a vision but no gameplan yet. Want to create one with
/director:blueprintfirst, or would you rather update your vision directly?"
Wait for the user's response.
Stop here if no gameplan.
If both VISION.md and GAMEPLAN.md have real content, continue to Step 2.
This step captures the user's pivot intent. There are two entry paths depending on whether the user provided inline arguments.
If $ARGUMENTS is non-empty, the user already told you what changed. Acknowledge it conversationally and move on:
"Got it -- [brief restatement of what they said]. Let me look at what that means for your project."
Store the argument text as the pivot context for use in later steps. Skip to Step 3 (scope detection).
If $ARGUMENTS is empty, open a natural conversation to understand what changed. Start with something like:
"What's changed about your project?"
This is a conversation, not a formal interview. Follow the user's lead. Ask clarifying questions until you have a clear picture of what they want to change:
Keep it natural and conversational. Do NOT use formal interview structure, numbered sections, or rigid question templates. Do NOT spawn the interviewer agent -- run the conversation inline.
When you have a clear understanding of the pivot direction, store the captured context and continue to Step 3.
Analyze the user's pivot description to determine the scope of the change. This affects which documents get updated later (Steps 4-9).
Tactical signals (approach change -- gameplan-only update):
Strategic signals (direction change -- vision + gameplan update):
If clearly tactical: State it conversationally:
"This sounds like a change in approach -- your vision still holds, just the plan needs updating."
Continue to Step 4.
If clearly strategic: State it conversationally:
"This changes the direction of what you're building. We'll want to update your vision first, then rebuild the plan around it."
Continue to Step 4.
If ambiguous: Ask the user with a plain-language question:
"This could be a tweak to your approach or a bigger shift in what you're building. Which feels closer?"
A) Just changing the approach -- the vision is still right, just the plan needs updating B) Changing direction -- the vision needs updating too
Wait for the user's response. Once they choose, acknowledge it and continue to Step 4.
Before mapping or analyzing impact, make sure the project is in a clean state. Pivoting from a messy workspace leads to confusion about what is current vs in-progress.
Run:
git status --porcelain
If the output is empty: The project is in a clean state. Continue silently to Step 5.
If there are uncommitted changes: The user has work in progress. Say something like:
"I noticed some unsaved work in your project. It's easier to change direction from a clean state. Want to wrap up what you're working on first?"
Offer two options conversationally:
Save the current work -- commit what's there so it is preserved and revertable:
git add -A && git commit -m "Save work in progress"
After committing, tell the user: "Saved. You can always go back to this with /director:undo if you change your mind."
Set it aside temporarily -- stash the changes so they can be restored later:
git stash -m "Work in progress before pivot"
After stashing, tell the user: "Set aside for now. Your changes are safe and can be brought back later."
Wait for the user's choice and handle it. Do NOT proceed until git status --porcelain returns empty.
Per locked decision: complete current task first, then pivot from clean commit state. The user can /director:undo after if they want to abandon that task. This ensures:
Before analyzing the impact of the pivot, you need an accurate picture of what the project looks like right now. Sometimes the existing documentation is enough; other times you need a fresh scan of the codebase.
Read .director/STATE.md to understand:
Also read .director/GAMEPLAN.md to understand the current plan structure.
Before loading research and codebase files, check whether the project's context files are still current:
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.
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.
Calculate the delta: current_completed_goals - completed_goals_at_generation.
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:refreshto update them. Continuing with what we have for now."
If delta < 2: proceed silently.
This alert is NON-BLOCKING. After showing it (or skipping it), continue loading the context files below.
Load research and codebase files to enrich the impact analysis that follows:
.director/research/SUMMARY.md -- Read silently using cat .director/research/SUMMARY.md 2>/dev/null. If it exists, store its contents internally wrapped in a <research_summary> tag. This provides broad ecosystem knowledge: recommended technologies, architecture patterns, and common pitfalls.
.director/research/FEATURES.md -- Read silently using cat .director/research/FEATURES.md 2>/dev/null. If it exists, store its contents internally wrapped in a <research> tag with a "## Features Research" header inside. This provides feature landscape context: expected features, nice-to-haves, and competitive considerations.
.director/codebase/ARCHITECTURE.md -- Read silently using cat .director/codebase/ARCHITECTURE.md 2>/dev/null. If it exists, store its contents internally as part of a <codebase> tag. This provides knowledge of the project's current architecture patterns and structure.
.director/codebase/STACK.md -- Read silently using cat .director/codebase/STACK.md 2>/dev/null. If it exists, store its contents internally as part of the same <codebase> tag, with a section header separating the two files:
<codebase>
## Architecture
[Contents of ARCHITECTURE.md]
## Stack
[Contents of STACK.md]
</codebase>
For each file: if it does not exist or is empty, skip it silently. Do NOT include empty XML tags. Do NOT mention missing files to the user or in any agent context. Each file is loaded independently -- if 3 of 4 exist, load those 3.
This research and codebase context enriches the impact analysis in Step 6. Use it to understand what technologies the project relies on, what the ecosystem recommends, and what architectural patterns are in place -- all of which inform how a pivot affects the project.
The mapper agent does a full codebase scan. This is useful when the documentation might not reflect reality, but unnecessary when the project state is well-tracked and current. Use these heuristics:
Spawn the mapper if ANY of these are true:
Skip the mapper if ANY of these are true:
Staleness is a judgment call, not a precise calculation. When multiple indicators conflict, lean toward skipping the mapper -- it is better to trust the docs and correct course later than to waste time on an unnecessary scan.
If you decided to spawn the mapper, tell the user:
"Let me check what your project looks like right now."
Then spawn director:director-mapper using the Task tool:
<instructions>
Map this codebase with a focus on what currently exists.
The user is considering a change in direction: [pivot context from Step 2].
Report your findings using your standard output format.
</instructions>
Run the mapper in the foreground -- wait for it to complete before continuing.
When the mapper returns, present its findings conversationally:
"Here's what your project looks like right now:"
Then present the mapper's findings formatted naturally -- not as a raw dump, but woven into the conversation. Highlight the parts most relevant to the pivot the user described.
Store the mapper findings internally for use in Step 6 (impact analysis).
If you decided to skip the mapper, summarize the current state from STATE.md and GAMEPLAN.md. Present it as:
"Based on where things stand:"
Then provide a brief, conversational summary covering:
Keep it concise -- the user likely already knows this. The summary is to establish shared context before impact analysis, not to teach the user about their own project.
Store the summary internally for use in Step 6 (impact analysis).
Now that you have an accurate picture of the current state (from Step 5), analyze every item in the gameplan against the new direction captured in Step 2.
Build a complete inventory of everything that exists:
.director/GAMEPLAN.md for the overview, goal list, and current focus..director/goals/ directory. For each goal directory:
GOAL.md for the goal definition and status.STEP.md for step descriptions, tasks, and status.tasks/ directory.Any goal, step, or task marked as done or complete is FROZEN. This is the same rule as blueprint update mode:
For each goal, step, and task in the gameplan, assign one of four classifications:
Still relevant: No change needed -- this work contributes to the new direction as-is. The goal/step/task can remain exactly where it is.
Needs modification: The work is still useful but needs adjustments to fit the new direction. Note what specifically needs to change and why.
No longer needed: This pending work does not contribute to the new direction. It will be proposed for removal in the delta summary. (This classification applies only to PENDING items. For completed work that is now irrelevant, see 6d below.)
New work required: The new direction requires goals, steps, or tasks that do not exist yet. These will be generated in 6e below.
Use the research and codebase context loaded in Step 5a-2 (when available) to inform your classifications. Research findings help identify whether the new direction aligns with ecosystem recommendations. Codebase awareness helps understand what existing patterns would be affected.
When completed work no longer aligns with the new direction, do NOT propose removal. Instead:
Per locked decision: "Director flags it and adds cleanup tasks to the new gameplan (not removed automatically)." The user decides if and when cleanup happens.
For goals, steps, and tasks that the new direction requires but do not exist yet, generate them following the same planning rules as blueprint:
Rule 1: Goals are outcomes, not activities. "Users can..." not "Build..." or "Implement..."
Rule 2: Steps are verifiable chunks of work. Each step delivers something the user can see or interact with.
Rule 3: Tasks are single-sitting work units. Each task includes What To Do, Why It Matters, Size, Done When, and Needs First.
Rule 4: Order by what's needed first. Express prerequisites in plain language ("Needs the user database set up first"), never as task IDs.
Rule 5: Use ready-work filtering. Mark tasks as "Ready" only when everything they need is already complete.
Rule 6: Prefer vertical slices over horizontal layers. Build complete features one at a time.
Generate new items at whatever granularity matches the pivot scope:
Take the impact analysis from Step 6 and present it as a clear, reviewable delta summary. The user must see exactly what will change before anything is modified.
The level of detail in the delta depends on the type of pivot:
Strategic pivots (direction change): Present at goal-level granularity first. Show which goals are being added, modified, removed, or kept. Then expand each modified or new goal to show its steps. This gives the user the big picture before the details.
Tactical pivots (approach change): Present at step-level and task-level granularity directly. The goals likely remain the same -- the changes are in how the goals are achieved.
Use the same delta format established in blueprint update mode:
Here's what would change:
Added:
- [New goal/step/task with explanation of why it is needed for the new direction]
Changed:
- [Modified item: was X, now Y, because of the pivot]
Removed:
- [Pending item removed with reasoning -- only pending items, never completed work]
Reordered:
- [Item moved: was in Step X, now in Step Y, because of the pivot]
Already done (keeping as-is):
- [Completed items preserved -- even if now irrelevant, they stay in the gameplan]
Every removal must be explicitly stated with reasoning. No silent deletions. The user must be able to see exactly what is being removed and why.
The "Already done" section ALWAYS appears, even if just to say "Nothing completed yet." This reassures the user that their completed work is safe.
If completed work is now irrelevant to the new direction, add an additional section:
Completed but no longer needed:
- [Completed item] -- I'll add a cleanup task for this.
This makes it clear that the completed work stays in the gameplan but has been identified as potentially unnecessary. The cleanup tasks proposed in Step 6d appear in the "Added" section above.
After the delta summary, show what the entire gameplan would look like after the pivot. Use the same format as blueprint (goals, steps, tasks with one-line descriptions and size indicators):
Here's what the updated gameplan would look like:
Goal 1: [Goal Name] [done/updated/new] Step 1: [Step name] [done/updated/new] - [Task name] (size) -- Done/Ready/Needs [capability]
Goal 2: [Goal Name] [updated/new] Step 1: [Step name] [new] - [Task name] (size) -- Ready - [Task name] (size) -- Needs [capability]
Does this look right? I won't make any changes until you say so.
IMPORTANT: Do NOT write any files until the user explicitly approves. This is the same approval pattern as blueprint update mode. The delta summary and gameplan outline are a PROPOSAL -- the user must confirm before anything changes.
If the user gives feedback:
Iterate until the user says the delta looks right. Only then proceed to Step 8 (applying changes).
After the user explicitly approves the delta summary from Step 7, apply all changes. Work through each sub-step in order.
If the pivot is strategic (detected in Step 3):
Rewrite .director/VISION.md with the updated vision reflecting the new direction. But do NOT write it immediately -- present the updated vision to the user for review first.
Present the full updated VISION.md content:
"Here's the updated vision for your project:"
Then show the complete VISION.md using the same document structure as the onboard template:
Wait for the user's approval. If they give feedback, adjust the vision and re-present:
"How does that look? I won't save it until you're happy with it."
Iterate until the user confirms. Only then write the updated content to .director/VISION.md.
If the pivot is tactical (detected in Step 3):
Skip this step entirely. VISION.md stays as-is -- only the gameplan needs updating.
Rewrite .director/GAMEPLAN.md with the updated gameplan. Use the same structure as the blueprint skill:
# Gameplan
## Overview
[2-3 sentence summary reflecting the current vision and approach]
## 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
**Current Goal:** [First goal with ready work]
**Current Step:** [First step with ready tasks]
**Next Up:** [What comes after the current step]
Point the Current Focus section at the first ready task in the updated gameplan -- this is the task the user will pick up next with /director:build.
Apply changes to the .director/goals/ directory structure based on the approved delta from Step 7.
Completed items (FROZEN): Do NOT touch files for completed goals, steps, or tasks. Leave them exactly as they are on disk. This is non-negotiable -- even if the pivot makes them irrelevant, their files stay untouched.
Modified items:
Overwrite the existing GOAL.md, STEP.md, or task file with updated content. Keep the same directory location and file name unless the item was also reordered.
New items: Create new directories and files following the same naming conventions as blueprint:
03-payment-flow/, 02-api-setup/mkdir -p via Bash for directoriesFollow the same file templates as blueprint:
GOAL.md:
# Goal N: [Goal Name]
## What Success Looks Like
[What "done" means for this goal]
## Steps
1. **Step 1: [Step Name]** -- [What this delivers]
2. **Step 2: [Step Name]** -- [What this delivers]
## Status
**Progress:** Not started
**Steps complete:** 0 of [total steps]
STEP.md:
# Step N: [Step Name]
## What This Delivers
[What will be working when this step is done]
## Tasks
- [ ] Task 1: [Task Name]
- [ ] Task 2: [Task Name]
## Needs First
[What needs to be done before this step can start, in plain language]
## Decisions
[Only if decisions were captured -- see 8d below]
Task files (NN-task-slug.md):
# Task: [Task Name]
## What To Do
[Clear description of what this task accomplishes]
## Why It Matters
[How this connects to the bigger picture]
## Size
**Estimate:** [small | medium | large]
[Brief explanation of scope]
## Done When
- [ ] [First observable criteria]
- [ ] [Second observable criteria]
- [ ] [Third observable criteria]
## Needs First
[What needs to be done before this task can start, in plain language]
Removed pending items:
Delete the files and directories for pending items that were approved for removal in the delta. Use Bash for rm -rf on directories.
NEVER delete files for completed items. If something has a .done.md file or its Status shows complete, it stays on disk regardless of the pivot.
Do NOT narrate file paths, mkdir commands, or directory structures to the user. File operations are invisible.
Completed steps (FROZEN): Do not modify their Decisions sections. Completed steps are untouchable -- their decisions are part of the historical record.
Modified pending steps: Review the pivot conversation (Steps 2, 6, and 7) for new decisions that affect these steps. Merge new decisions with existing ones:
New steps: Capture decisions from the pivot conversation using the same passive extraction approach as blueprint. Look for:
Only include the Decisions section if relevant decisions exist. Omit it entirely when there are no decisions for a step. Only include categories (Locked, Flexible, Deferred) that have items.
Update .director/STATE.md directly. Do NOT spawn the syncer -- pivot is a meta-operation that changes the entire gameplan structure, not a single build task. The syncer expects task-specific context (<task> and <changes> tags) that does not apply here.
Recalculate progress:
Scan the updated .director/goals/ directory structure:
.md and .done.md) across all goals and steps.done.md only)Update current position:
Set the current position to point to the first ready task in the updated gameplan. This is the task that /director:build will pick up next.
Add a Recent Activity entry: Add an entry for the pivot itself:
- **[YYYY-MM-DD]** -- Pivot: [brief description of what changed]
Use today's date and a concise description drawn from the pivot conversation (e.g., "Switched from REST to GraphQL API" or "Refocused on enterprise users with 3 new goals").
If the pivot is strategic: Also update the "Current focus" description to reflect the new direction.
After all files are written (VISION.md, GAMEPLAN.md, goal/step/task files, STATE.md), save progress by committing all .director/ changes:
git add .director/
git commit -m "pivot: update gameplan -- [brief summary of what changed]"
This is a SILENT operation -- the user does not see git commands or commit details. If the commit fails (e.g., nothing to commit, git not initialized), proceed silently. The important thing is that the files were written; the commit prevents "unsaved changes" warnings in later commands.
Tell the user conversationally what happened. Keep it brief and forward-looking -- this is a summary, not a report.
"Your gameplan is updated. [Brief summary of the key changes]."
The summary should describe what changed at a high level. Examples:
Do NOT list file paths, directory structures, technical details, or counts of files written. The user just needs to know what changed about their project, not what happened on disk.
Then suggest the next action:
"Ready to keep building? You can pick up where things left off with
/director:build."
Wait for the user's response. Do not auto-execute the next command.
Throughout the entire pivot flow, follow these rules:
$ARGUMENTS