DeepWorkPlan — Create
Create a new Deep Work Plan through a smooth, unified flow: the developer
provides information once, you generate a single refined draft, the developer
reviews it, and you materialize the final plan under .dwp/plans/PLAN_{name}/.
Single-step change (vs legacy): DeepWorkPlan generates the refined draft
directly. There is no separate raw-draft file. This replaces the legacy
draft → refined-draft two-step (which wrote PLAN_{name}_draft.md and then
PLAN_{name}_draft_refined.md). The only reviewable draft artifact is now
.dwp/drafts/PLAN_{name}_draft_refined.md.
Philosophy
The goal is a delightful, smooth experience. The user provides information once;
the system handles all intermediate steps (refined-draft creation, review, final
plan generation) automatically.
Shared resources (read these)
Parameter Reference
| Input |
Classification |
Mode |
Behavior |
Example |
| (none) |
— |
guided |
Ask for name, then ask questions |
/dwp-create |
{short text} |
name-only |
guided |
Extract name, ask questions immediately |
/dwp-create improve error handling |
{long text} |
full-context |
guided |
Infer name, proceed to refined draft directly |
/dwp-create Refactor auth to use JWT across all services. Currently using sessions... |
trust or auto |
— |
trust |
Ask for name, then ask questions (no confirmations) |
/dwp-create trust |
{short text} trust |
name-only |
trust |
Extract name, ask questions (no confirmations) |
/dwp-create improve-error-handling trust |
{long text} trust |
full-context |
trust |
Infer name, proceed directly (no confirmations) |
/dwp-create Refactor auth... trust |
refined-draft {name} |
— |
refined-draft-only |
Produce ONLY the refined draft (no final plan) |
/dwp-create refined-draft my_plan |
from-refined-draft {file} |
— |
from-refined-draft |
Build final plan from an existing refined draft |
/dwp-create from-refined-draft PLAN_x_draft_refined.md |
from {file} |
— |
from-refined-draft |
Alias for from-refined-draft |
/dwp-create from PLAN_x_draft_refined.md |
Name format: users type names in any format; you auto-convert to
snake_case internally.
Modes
Guided Mode (default)
- Collects information from the user.
- Creates the refined draft → shows it for review.
- Asks for confirmation before creating the final plan.
- User can request adjustments before final generation.
Trust Mode (trust or auto)
- Collects information from the user.
- Creates the refined draft → final plan automatically (no intermediate
confirmations).
Trust boundary (write scope)
allowed-tools includes write-capable Edit, Write, and Bash.
Writes: plan artifacts under the gitignored .dwp/ directory only —
.dwp/drafts/ during drafting, .dwp/plans/PLAN_{name}/ for the materialized
plan (README, task files, analysis outputs). "Trust mode" skips intermediate
confirmations of plan content, not of the write boundary.
It MUST NOT: modify source files (that is execute's job), write outside
.dwp/, read or include secrets in plan content, or materialize a plan whose
tasks lack acceptance criteria and validation gates.
Unified Workflow
Step 0 — Parse Parameters & Determine Mode
0.1 Detect trust mode: if the LAST word is trust or auto, remove it and
set trust_mode = true; otherwise false.
0.2 Detect special modes (check FIRST word):
refined-draft → mode = "refined-draft-only", remaining text = plan name.
from-refined-draft or from → mode = "from-refined-draft", remaining text
= refined-draft file path.
- Otherwise → continue to input classification (0.3).
0.3 Classify remaining input:
| Condition |
Classification |
What to do |
| No remaining text |
no input |
Go to Step 1, then Step 2 (ask for name + all info) |
| ≤10 words AND no complete sentences AND no line breaks |
name-only |
Convert to snake_case → plan name. Go to Step 1, then Step 2 (skip name question) |
| >10 words OR detailed sentences OR line breaks |
full-context |
Infer plan name → snake_case. Go to Step 1, then Step 3 (use provided context) |
Name auto-conversion to snake_case: lowercase; replace hyphens/spaces with
_; strip everything but a-z0-9_. Examples: improve Feature X →
improve_feature_x, add-stripe-payments → add_stripe_payments.
CRITICAL: when input is name-only, NEVER explore the codebase or
research the topic before asking questions. The name only says what to CALL the
plan, not what to DO. Go directly to Step 2.
Routing by mode:
from-refined-draft → skip to Step 4.3.
refined-draft-only → gather info, create only the refined draft, skip final
plan creation.
no input / name-only → Step 1, then Step 2.
full-context → Step 1, then Step 3.
Step 1 — Quick Introduction
Show a brief intro matching the mode (guided vs trust): what will happen and that
you'll create a refined plan, review it (guided) or proceed (trust), then
generate the final executable plan.
Step 2 — Gather Information (Conversational)
Skip this entire step for full-context input — go straight to Step 3.
Collect, conversationally:
- 2.1 Plan name (skip if already extracted) — auto-convert to snake_case, add
PLAN_ prefix internally.
- 2.2 Objective — one or two sentences.
- 2.3 Context — where the changes live, constraints/rules, tech notes.
- 2.4 Tasks — at least 2; if only 1, suggest breaking it down.
- 2.5 Guidelines (optional) — branch/commit format, coverage target, etc.
2.6 Orchestrator detection (automatic). After 2.3–2.4, auto-detect an
orchestrator plan when: the work spans 2+ sub-repositories with independent
feature work, or the user explicitly mentions child DWPs / orchestrator /
"create plans in each repo". If detected, offer the choice between an
orchestrator plan (creates child DWPs per repo, each following its own
AGENTS.md) and a direct multi-project plan. See ../guide/GUIDE.md §13 and
../shared/adaptation.md (orchestrator-hub archetype).
2.7–2.9 (orchestrator only): ask for target repositories (note each repo
root — for an orchestrator hub this is repositories/{repo}/), dependency order,
and execution mode (Distributed / Sequential with Output Handoff / Sequential
basic). Default to Distributed.
2.10 Team-agents detection (automatic — always runs, non-orchestrator plans).
Always analyze whether 2+ tasks touch different files/modules with no data
dependencies and would benefit from parallel execution. This is NOT opt-in.
- If parallelizable: in guided mode, inform the user (do not ask) and add the
team-agents configuration; in trust mode, do it silently. Team-agents
metadata is always additive and backward compatible (other agents ignore it).
- Auto-assign parallel groups (tasks with no cross-dependencies), teammate roles
(derived from task content), and default model
sonnet. Setup/integration and
the three mandatory final tasks are always sequential.
- If not parallelizable: add nothing, mention nothing.
Step 2.11 — Parallel Research Phase (Claude Code only, automatic). Before
drafting, if the plan spans 2+ repos or several independent modules and context
isn't already provided, spawn research teammates (subagent_type: "Explore",
one per repo/area) to read each AGENTS.md, identify relevant files, contracts,
and validation commands, then synthesize their findings into enriched context for
the refined draft. Skip for simple/single-module plans or full-context input.
Fallback: research sequentially if team agents are unavailable. In trust mode,
run silently.
Step 3 — Create the Refined Draft (Automatic, SINGLE STEP)
This is the single-step change. Produce the refined draft directly —
one file, written straight to .dwp/drafts/. Do NOT create a separate raw
PLAN_{name}_draft.md first.
Show a 2-step progress UI:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Creating your plan...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[1/2] Drafting refined plan...
3.1 Write the refined draft:
- Resolve
dwp_dir via ../shared/context.sh; ensure <dwp_dir>/drafts/ exists.
- Compose a professional, complete plan prompt following
../examples/CREATE_PLAN.md: objective, context (enriched with Step 2.11
research if applicable), well-formed tasks, guidelines. Expand every section
with full detail and clarity in one pass.
- Write only:
.dwp/drafts/PLAN_{name}_draft_refined.md.
[1/2] Drafting refined plan... ✓
[2/2] Preparing for review...
Step 4 — Review & Create Final Plan
4.1 Guided Mode — Show for Review
Present a summary (objective, task count + list, location, constraints) and the
path → .dwp/drafts/PLAN_{name}_draft_refined.md, then offer:
- Looks good, create the final plan → Step 4.4.
- Make adjustments → ask what to change, edit the refined draft in place,
show the menu again.
- Show the full refined draft → display it, then re-show the menu.
- Stop here → completion message for the draft phase.
4.2 Trust Mode — Automatic Continue
Skip review; go directly to Step 4.4. Progress: [2/2] Creating final plan....
4.3 From-Refined-Draft Mode
- Validate the file exists in
.dwp/drafts/. If not found, list available
refined drafts and ask the user to select.
- Read it; extract plan name, objective, context, tasks, guidelines.
- Skip to Step 4.4.
4.4 Create Final Plan
Follow ../guide/GUIDE.md. Create:
Folder: .dwp/plans/PLAN_{name}/
README.md — Goal; Context; Plan Variables (optional); Global Guidelines;
Task List with [ ] checkboxes + links (including the three mandatory final
tasks); Execution Rules; Skills & Agents Used; Plan Status / Notes; Analysis
Outputs (referencing EXECUTIVE_REPORT.md); Quick Reference to PROMPTS.md.
PROMPTS.md — from ../examples/PROMPTS_TEMPLATE.md, replacing
{PLAN_NAME}.
PROGRESS.md — initial template (Task Summaries / Key Decisions / Important
Values & Paths).
analysis_results/ — empty folder inside the plan directory.
User-defined task files — N.task_{title}.md, each with Context, Read
Before Starting (optional), Goal, Instructions (with re-anchoring),
Acceptance Criteria, Outputs (optional), Validation, Rollback (optional),
Execution Checklist, Completion & Log. For any task that adds new core
functionality or changes product behavior, bake the test discipline into
it (../guide/GUIDE.md §5.3): its Acceptance Criteria must require
automated test coverage for the new/changed behavior, and its Validation
must run the repo's tests plus lint/type-check/format checks (not the
build alone). Where related work is substantial, prefer a dedicated
N.task_add_tests_for_{feature}.md task right after the implementation task.
Likewise, for any task that touches auth, input handling, secrets/config,
network surface, or dependencies, bake the security discipline into it
(../guide/GUIDE.md §5.4); where the security-sensitive work is substantial,
prefer a dedicated N.task_security_hardening_{feature}.md task placed after
the implementation tasks and before the comprehensive-tests task, so
findings are fixed before tests encode the behavior and become regression
test cases rather than rework.
State layer (RECOMMENDED, ../spec/PLAN_STATE.md) — write
manifest.json (plan identity: name, archetype, rigor tier, spec version,
task count, creating agent — once, never edited after) and the initial
state.json (every task pending, empty gates). Both atomically
(write-temp-then-rename). REQUIRED when the plan will run unattended
(../spec/AGENT_PROTOCOL.md §7.2) or the workspace has no git.
Proportional rigor check first (../spec/DWP_SPECIFICATION.md §11): before
materializing anything, confirm the work actually warrants a plan. A trivial
single-concern change is micro tier — say that a plan is disproportionate,
offer to state goal + acceptance criteria + validation gate inline and just do
it. Declare the chosen tier (standard or deep) and why in the refined draft.
Three mandatory final tasks (always):
Security Review (MANDATORY, third-to-last, task N-2,
{N-2}.task_security_review.md): reviews the plan's full accumulated diff for
hardcoded secrets, injection risks, unsafe input handling, new attack surface,
and auth/permission changes; audits dependencies the plan introduced
(best-effort, with the ecosystem's audit tooling where available); verifies
docs/SECURITY.md still reflects reality and updates it when the plan changed
secrets handling, the auth model, or data boundaries; writes
analysis_results/SECURITY_REVIEW.md even when clean. A critical finding
blocks completion until fixed or explicitly accepted by the user
(../spec/DWP_SPECIFICATION.md §6.1).
Addon augmentation — ai-diff-reviewer (opt-in, only when installed).
When the target repo has installed the ai-diff-reviewer addon — detected via
.agents/skills/ai-diff-reviewer/ present + an extension file at one of the
three recognized paths (in precedence order): .review/extension.md,
.github/ai-diff-reviewer/extension.md, or the back-compat
.github/ai-pr-reviewer/extension.md — the Security Review task template gains
an ADDITIONAL post-existing-checks step: invoke the upstream skill's parent
default flow ("Review my current branch" / /ai-diff-reviewer), capture the
verdict, findings table, per-finding bodies, notes, and recommendation, and
append them to analysis_results/SECURITY_REVIEW.md under a dedicated
## AI Diff Reviewer local review heading. The upstream skill's prompt.md
is byte-identical to the CI Action's prompts/default.md at the same tag, so
when the same repo also runs the CI Action (Flow B), the local review shares
the same methodology and severity model via that prompt plus the extension
file; CI round 2+ may surface a shorter finding set under Iteration-Aware
Review (local stays a full pass — see addon SPEC §4.3). A critical finding
follows the existing SR contract
(blocks completion until fixed or explicitly accepted); warning / info
findings are appended and reported but do not block. The augmentation is
best-effort and conditional per the addon SPEC §7 (never-block rule): skip
the local review pass (warn once, NEVER fail the task) only when the
vendored skill is absent, detection fails (no extension file), or the local
review invocation errors. Flow A needs no CI provider secret — do NOT
treat an unset CURSOR_API_KEY (or other provider secret) as a reason to
skip the local Security Review pass; that secret is Flow B CI / gate
messaging only. Flow B optional companion (not a plan task):
when the plan's PR has been pushed and CI has posted its review, the developer
MAY invoke the upstream apply-review sub-skill from within the same
execute session to walk through CI findings per-finding (apply / defer /
skip) with explicit consent — read-only by default, edits require per-finding
yes, never commits or pushes. This is surfaced as an available option during
execute; the addon MUST NOT insert an apply-review task file into any
plan (would violate the mandatory-final-task-order rule).
Skills & Agents Discovery (MANDATORY, second-to-last, task N-1,
{N-1}.task_skills_agents_discovery.md): reviews completed tasks for new
patterns, checks the catalog, creates/updates skills/agents if warranted,
evaluates the skills-generator system. If no skills-generator exists in the
target repo, write a simplified evaluate-and-document-only version.
Executive Report (MANDATORY, last, task N,
{N}.task_executive_report.md): generates
analysis_results/EXECUTIVE_REPORT.md with Executive Summary, Product Impact,
Technical Details, QA Verification Guide, FAQs, Next Steps.
Add to the README a note: "Every plan includes Security Review
(third-to-last), Skills & Agents Discovery (second-to-last), and Executive
Report (last). These are auto-generated by /dwp-create."
Quality gates: atomic, ordered tasks; both mandatory files present;
analysis_results/ exists; PROGRESS.md exists; numbering correct (user tasks →
security review → skills discovery → executive report); behavior-changing tasks carry test coverage
in their Acceptance Criteria and tests + lint/type-check in their Validation
(../guide/GUIDE.md §5.3).
Accelerate generation with team agents (Claude Code only, automatic): for
5+ user-defined task files, the lead creates README/PROMPTS/PROGRESS/
analysis_results + the mandatory final task files, then spawns teammates (1 per
2–3 task files) to write user task files in parallel (no file overlap), verifies
all files, and cleans up. Fallback: generate sequentially.
Orchestrator additions (orchestrator plans):
- README Child DWP Plans table (
# | Repository | Child Plan | Status | Depends On), an Execution Mode subsection, and Dependency Rules.
- ORCHESTRATOR_MANIFEST.md at
.dwp/plans/PLAN_{name}/ORCHESTRATOR_MANIFEST.md
(template in ../guide/GUIDE.md §13.8): Shared Context, Child DWP Registry,
Dependency Graph, Output Contracts, Execution State.
- Task files: direct design tasks first (if hybrid); then
create_child_dwp
tasks in dependency order (template
../examples/ORCHESTRATOR_TASK_TEMPLATE_create_child_dwp.md); optional
integration_checkpoint tasks
(../examples/ORCHESTRATOR_TASK_TEMPLATE_integration_checkpoint.md);
execute_child_dwp tasks for Sequential-with-Output-Handoff mode
(../examples/ORCHESTRATOR_TASK_TEMPLATE_execute_child_dwp.md); then the two
mandatory final tasks last. Each create_child_dwp task instructs the agent to
navigate to the target repo, read its AGENTS.md, and create a child DWP at
repositories/{repo}/.dwp/plans/PLAN_{child}/ using that repo's conventions.
Team-agents metadata (when Step 2.10 detected parallelizable tasks): add a
"Team Agents Configuration (Claude Code Only)" section to the README (Parallel
Task Groups + Teammate Roles tables) and a "Team Agents Metadata (Claude Code
Only)" section to each parallel task file (Parallel Group / Teammate Role / Can
Run With / Blocks / Files Owned). Use ../examples/TEAM_AGENTS_TASK_TEMPLATE.md.
Rules: never put required info inside team-agents sections; every task must work
sequentially; mandatory final tasks are always sequential; file ownership between
parallel tasks must not overlap.
Step 5 — Completion & Execute Option
For a full plan, report success and the location
.dwp/plans/PLAN_{name}/, then offer: (1) execute now → run the Execute
sub-skill (../execute/SKILL.md); (2) review the README first, then ask again;
(3) done for now → tell them to run /dwp-execute {name} later.
Dailybot kickoff (only when the Dailybot addon is wired — best-effort,
non-blocking): after the plan is materialized and approved, send a regular
(non-milestone) kickoff report via the dailybot report sub-skill — "Starting:
<what is being built and why it matters>" — per the addon's lifecycle event
model (../addons/dailybot/SPEC.md §5.1). One kickoff per plan; skip silently
if Dailybot is absent, unauthenticated, or .dailybot/disabled exists. Never
block on this.
For refined-draft-only mode, report the single refined draft saved at
.dwp/drafts/PLAN_{name}_draft_refined.md and the next step: run
/dwp-create from PLAN_{name}_draft_refined.md to build the final plan.
Step 6 — Execute Plan (Optional)
If the user chose to execute, hand off to the Execute sub-skill
(../execute/SKILL.md): read the plan README, check git status, start from the
first [ ] task, execute sequentially, validate, commit per task, report.
Error Handling
- Plan name already exists: offer different name / overwrite / cancel.
- Name auto-converted: show an informational notice (not an error).
- Refined draft not found (from-refined-draft): list available refined drafts
in
.dwp/drafts/ and ask the user to choose.
- Insufficient tasks (<2): ask the user to break the work down.
Important Notes
- Git ignore: everything under
.dwp/ is git-ignored.
- Single artifact: the only draft file is
PLAN_{name}_draft_refined.md in
.dwp/drafts/ — there is no separate raw draft.
- Reference: follow
../guide/GUIDE.md; orchestrator → §13; team agents → §14.
- Archetypes: orchestrator support assumes the orchestrator-hub archetype
(sub-repos under
repositories/); an individual repo creates standard plans.
See ../shared/adaptation.md.
1---2name: deepworkplan-create-43description: Create a Deep Work Plan. Gather context, draft, and refine into a single final plan under .dwp/plans/, with a refined draft staged in .dwp/drafts/. Use when the developer wants a new structured multi-task plan.4version: "2.17.0"5documentation_url: https://deepworkplan.com6user-invocable: true7allowed-tools: Bash, Read, Grep, Glob, Edit, Write8metadata:9 source: https://skillmd.com/skills/dailybothq/deepworkplan-create-410---1112# DeepWorkPlan — Create1314Create a new Deep Work Plan through a smooth, unified flow: the developer15provides information once, you generate a **single refined draft**, the developer16reviews it, and you materialize the final plan under `.dwp/plans/PLAN_{name}/`.1718> **Single-step change (vs legacy):** DeepWorkPlan generates the **refined draft19> directly**. There is **no separate raw-draft file**. This replaces the legacy20> draft → refined-draft two-step (which wrote `PLAN_{name}_draft.md` and then21> `PLAN_{name}_draft_refined.md`). The only reviewable draft artifact is now22> `.dwp/drafts/PLAN_{name}_draft_refined.md`.2324## Philosophy2526The goal is a delightful, smooth experience. The user provides information once;27the system handles all intermediate steps (refined-draft creation, review, final28plan generation) automatically.2930## Shared resources (read these)3132- [`../shared/context.sh`](../shared/context.sh) — resolve repo root, branch,33 agent tool, and the `.dwp/` output location (`dwp_dir`).34- [`../shared/dwp-paths.md`](../shared/dwp-paths.md) — the `.dwp/plans/` +35 `.dwp/drafts/` output convention.36- [`../shared/adaptation.md`](../shared/adaptation.md) — reasoning-over-copy-paste37 and the two repository archetypes (individual repo vs orchestrator hub).38- [`../guide/GUIDE.md`](../guide/GUIDE.md) — the full methodology: plan README39 structure, task-file anatomy, mandatory final tasks, orchestrator (§13),40 team agents (§14).41- [`../examples/CREATE_PLAN.md`](../examples/CREATE_PLAN.md) — prompt patterns.42- [`../examples/PROMPTS_TEMPLATE.md`](../examples/PROMPTS_TEMPLATE.md) — the43 `PROMPTS.md` template for each plan.4445## Parameter Reference4647| Input | Classification | Mode | Behavior | Example |48|-------|---------------|------|----------|---------|49| (none) | — | guided | Ask for name, then ask questions | `/dwp-create` |50| `{short text}` | **name-only** | guided | Extract name, ask questions immediately | `/dwp-create improve error handling` |51| `{long text}` | **full-context** | guided | Infer name, proceed to refined draft directly | `/dwp-create Refactor auth to use JWT across all services. Currently using sessions...` |52| `trust` or `auto` | — | trust | Ask for name, then ask questions (no confirmations) | `/dwp-create trust` |53| `{short text} trust` | **name-only** | trust | Extract name, ask questions (no confirmations) | `/dwp-create improve-error-handling trust` |54| `{long text} trust` | **full-context** | trust | Infer name, proceed directly (no confirmations) | `/dwp-create Refactor auth... trust` |55| `refined-draft {name}` | — | refined-draft-only | Produce ONLY the refined draft (no final plan) | `/dwp-create refined-draft my_plan` |56| `from-refined-draft {file}` | — | from-refined-draft | Build final plan from an existing refined draft | `/dwp-create from-refined-draft PLAN_x_draft_refined.md` |57| `from {file}` | — | from-refined-draft | Alias for `from-refined-draft` | `/dwp-create from PLAN_x_draft_refined.md` |5859> **Name format:** users type names in any format; you auto-convert to60> `snake_case` internally.6162## Modes6364### Guided Mode (default)65- Collects information from the user.66- Creates the **refined draft** → shows it for review.67- Asks for confirmation before creating the final plan.68- User can request adjustments before final generation.6970### Trust Mode (`trust` or `auto`)71- Collects information from the user.72- Creates the **refined draft** → final plan automatically (no intermediate73 confirmations).7475## Trust boundary (write scope)7677`allowed-tools` includes write-capable `Edit`, `Write`, and `Bash`.7879**Writes:** plan artifacts under the gitignored `.dwp/` directory only —80`.dwp/drafts/` during drafting, `.dwp/plans/PLAN_{name}/` for the materialized81plan (README, task files, analysis outputs). "Trust mode" skips intermediate82confirmations of **plan content**, not of the write boundary.8384**It MUST NOT:** modify source files (that is `execute`'s job), write outside85`.dwp/`, read or include secrets in plan content, or materialize a plan whose86tasks lack acceptance criteria and validation gates.8788## Unified Workflow8990### Step 0 — Parse Parameters & Determine Mode9192**0.1 Detect trust mode:** if the LAST word is `trust` or `auto`, remove it and93set `trust_mode = true`; otherwise `false`.9495**0.2 Detect special modes (check FIRST word):**96- `refined-draft` → `mode = "refined-draft-only"`, remaining text = plan name.97- `from-refined-draft` or `from` → `mode = "from-refined-draft"`, remaining text98 = refined-draft file path.99- Otherwise → continue to input classification (0.3).100101**0.3 Classify remaining input:**102103| Condition | Classification | What to do |104|-----------|---------------|------------|105| No remaining text | **no input** | Go to Step 1, then Step 2 (ask for name + all info) |106| ≤10 words AND no complete sentences AND no line breaks | **name-only** | Convert to snake_case → plan name. Go to Step 1, then Step 2 (skip name question) |107| >10 words OR detailed sentences OR line breaks | **full-context** | Infer plan name → snake_case. Go to Step 1, then Step 3 (use provided context) |108109**Name auto-conversion to snake_case:** lowercase; replace hyphens/spaces with110`_`; strip everything but `a-z0-9_`. Examples: `improve Feature X` →111`improve_feature_x`, `add-stripe-payments` → `add_stripe_payments`.112113> **CRITICAL:** when input is **name-only**, NEVER explore the codebase or114> research the topic before asking questions. The name only says what to CALL the115> plan, not what to DO. Go directly to Step 2.116117**Routing by mode:**118- `from-refined-draft` → skip to Step 4.3.119- `refined-draft-only` → gather info, create only the refined draft, skip final120 plan creation.121- `no input` / `name-only` → Step 1, then Step 2.122- `full-context` → Step 1, then Step 3.123124### Step 1 — Quick Introduction125126Show a brief intro matching the mode (guided vs trust): what will happen and that127you'll create a refined plan, review it (guided) or proceed (trust), then128generate the final executable plan.129130### Step 2 — Gather Information (Conversational)131132> Skip this entire step for `full-context` input — go straight to Step 3.133134Collect, conversationally:135- **2.1 Plan name** (skip if already extracted) — auto-convert to snake_case, add136 `PLAN_` prefix internally.137- **2.2 Objective** — one or two sentences.138- **2.3 Context** — where the changes live, constraints/rules, tech notes.139- **2.4 Tasks** — at least 2; if only 1, suggest breaking it down.140- **2.5 Guidelines (optional)** — branch/commit format, coverage target, etc.141142**2.6 Orchestrator detection (automatic).** After 2.3–2.4, auto-detect an143**orchestrator plan** when: the work spans 2+ sub-repositories with independent144feature work, or the user explicitly mentions child DWPs / orchestrator /145"create plans in each repo". If detected, offer the choice between an146**orchestrator plan** (creates child DWPs per repo, each following its own147`AGENTS.md`) and a **direct multi-project plan**. See `../guide/GUIDE.md` §13 and148`../shared/adaptation.md` (orchestrator-hub archetype).149150**2.7–2.9 (orchestrator only):** ask for target repositories (note each repo151root — for an orchestrator hub this is `repositories/{repo}/`), dependency order,152and execution mode (Distributed / Sequential with Output Handoff / Sequential153basic). Default to Distributed.154155**2.10 Team-agents detection (automatic — always runs, non-orchestrator plans).**156Always analyze whether 2+ tasks touch different files/modules with no data157dependencies and would benefit from parallel execution. This is NOT opt-in.158- If parallelizable: in **guided** mode, inform the user (do not ask) and add the159 team-agents configuration; in **trust** mode, do it silently. Team-agents160 metadata is always additive and backward compatible (other agents ignore it).161- Auto-assign parallel groups (tasks with no cross-dependencies), teammate roles162 (derived from task content), and default model `sonnet`. Setup/integration and163 the three mandatory final tasks are always sequential.164- If not parallelizable: add nothing, mention nothing.165166**Step 2.11 — Parallel Research Phase (Claude Code only, automatic).** Before167drafting, if the plan spans 2+ repos or several independent modules and context168isn't already provided, spawn **research teammates** (`subagent_type: "Explore"`,169one per repo/area) to read each `AGENTS.md`, identify relevant files, contracts,170and validation commands, then synthesize their findings into enriched context for171the refined draft. Skip for simple/single-module plans or full-context input.172Fallback: research sequentially if team agents are unavailable. In trust mode,173run silently.174175### Step 3 — Create the Refined Draft (Automatic, SINGLE STEP)176177> **This is the single-step change.** Produce the **refined draft directly** —178> one file, written straight to `.dwp/drafts/`. Do NOT create a separate raw179> `PLAN_{name}_draft.md` first.180181Show a **2-step** progress UI:182183```184━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━185Creating your plan...186━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━187188[1/2] Drafting refined plan...189```190191**3.1 Write the refined draft:**192- Resolve `dwp_dir` via `../shared/context.sh`; ensure `<dwp_dir>/drafts/` exists.193- Compose a professional, complete plan prompt following194 `../examples/CREATE_PLAN.md`: objective, context (enriched with Step 2.11195 research if applicable), well-formed tasks, guidelines. Expand every section196 with full detail and clarity in one pass.197- Write **only**: `.dwp/drafts/PLAN_{name}_draft_refined.md`.198199```200[1/2] Drafting refined plan... ✓201[2/2] Preparing for review...202```203204### Step 4 — Review & Create Final Plan205206#### 4.1 Guided Mode — Show for Review207208Present a summary (objective, task count + list, location, constraints) and the209path `→ .dwp/drafts/PLAN_{name}_draft_refined.md`, then offer:2101. Looks good, create the final plan → Step 4.4.2112. Make adjustments → ask what to change, **edit the refined draft in place**,212 show the menu again.2133. Show the full refined draft → display it, then re-show the menu.2144. Stop here → completion message for the draft phase.215216#### 4.2 Trust Mode — Automatic Continue217218Skip review; go directly to Step 4.4. Progress: `[2/2] Creating final plan...`.219220#### 4.3 From-Refined-Draft Mode221222- Validate the file exists in `.dwp/drafts/`. If not found, list available223 refined drafts and ask the user to select.224- Read it; extract plan name, objective, context, tasks, guidelines.225- Skip to Step 4.4.226227#### 4.4 Create Final Plan228229Follow `../guide/GUIDE.md`. Create:2302311. **Folder:** `.dwp/plans/PLAN_{name}/`2322. **README.md** — Goal; Context; Plan Variables (optional); Global Guidelines;233 Task List with `[ ]` checkboxes + links (including the three mandatory final234 tasks); Execution Rules; Skills & Agents Used; Plan Status / Notes; Analysis235 Outputs (referencing `EXECUTIVE_REPORT.md`); Quick Reference to `PROMPTS.md`.2363. **PROMPTS.md** — from `../examples/PROMPTS_TEMPLATE.md`, replacing237 `{PLAN_NAME}`.2384. **PROGRESS.md** — initial template (Task Summaries / Key Decisions / Important239 Values & Paths).2405. **analysis_results/** — empty folder inside the plan directory.2416. **User-defined task files** — `N.task_{title}.md`, each with Context, Read242 Before Starting (optional), Goal, Instructions (with re-anchoring),243 Acceptance Criteria, Outputs (optional), Validation, Rollback (optional),244 Execution Checklist, Completion & Log. For any task that adds new core245 functionality or changes product behavior, bake the **test discipline** into246 it (`../guide/GUIDE.md` §5.3): its Acceptance Criteria **must** require247 automated test coverage for the new/changed behavior, and its Validation248 **must** run the repo's tests plus lint/type-check/format checks (not the249 build alone). Where related work is substantial, prefer a dedicated250 `N.task_add_tests_for_{feature}.md` task right after the implementation task.251 Likewise, for any task that touches auth, input handling, secrets/config,252 network surface, or dependencies, bake the **security discipline** into it253 (`../guide/GUIDE.md` §5.4); where the security-sensitive work is substantial,254 prefer a dedicated `N.task_security_hardening_{feature}.md` task placed after255 the implementation tasks and **before** the comprehensive-tests task, so256 findings are fixed before tests encode the behavior and become regression257 test cases rather than rework.2582597. **State layer (RECOMMENDED, `../spec/PLAN_STATE.md`)** — write260 `manifest.json` (plan identity: name, archetype, rigor tier, spec version,261 task count, creating agent — once, never edited after) and the initial262 `state.json` (every task `pending`, empty gates). Both atomically263 (write-temp-then-rename). REQUIRED when the plan will run unattended264 (`../spec/AGENT_PROTOCOL.md` §7.2) or the workspace has no git.265266**Proportional rigor check first (`../spec/DWP_SPECIFICATION.md` §11):** before267materializing anything, confirm the work actually warrants a plan. A trivial268single-concern change is **micro** tier — say that a plan is disproportionate,269offer to state goal + acceptance criteria + validation gate inline and just do270it. Declare the chosen tier (`standard` or `deep`) and why in the refined draft.271272**Three mandatory final tasks (always):**273- **Security Review** (MANDATORY, **third-to-last**, task `N-2`,274 `{N-2}.task_security_review.md`): reviews the plan's full accumulated diff for275 hardcoded secrets, injection risks, unsafe input handling, new attack surface,276 and auth/permission changes; audits dependencies the plan introduced277 (best-effort, with the ecosystem's audit tooling where available); verifies278 `docs/SECURITY.md` still reflects reality and updates it when the plan changed279 secrets handling, the auth model, or data boundaries; writes280 `analysis_results/SECURITY_REVIEW.md` even when clean. A critical finding281 blocks completion until fixed or explicitly accepted by the user282 (`../spec/DWP_SPECIFICATION.md` §6.1).283284 **Addon augmentation — `ai-diff-reviewer` (opt-in, only when installed).**285 When the target repo has installed the [`ai-diff-reviewer` addon](../addons/ai-diff-reviewer/SKILL.md) — detected via286 `.agents/skills/ai-diff-reviewer/` present + an extension file at one of the287 three recognized paths (in precedence order): `.review/extension.md`,288 `.github/ai-diff-reviewer/extension.md`, or the back-compat289 `.github/ai-pr-reviewer/extension.md` — the Security Review task template gains290 an ADDITIONAL post-existing-checks step: invoke the upstream skill's parent291 default flow ("Review my current branch" / `/ai-diff-reviewer`), capture the292 verdict, findings table, per-finding bodies, notes, and recommendation, and293 append them to `analysis_results/SECURITY_REVIEW.md` under a dedicated294 `## AI Diff Reviewer local review` heading. The upstream skill's `prompt.md`295 is byte-identical to the CI Action's `prompts/default.md` at the same tag, so296 when the same repo also runs the CI Action (Flow B), the local review shares297 the same methodology and severity model via that prompt plus the extension298 file; CI round 2+ may surface a shorter finding set under Iteration-Aware299 Review (local stays a full pass — see addon SPEC §4.3). A `critical` finding300 follows the existing SR contract301 (blocks completion until fixed or explicitly accepted); `warning` / `info`302 findings are appended and reported but do not block. The augmentation is303 best-effort and conditional per the addon SPEC §7 (never-block rule): skip304 the **local** review pass (warn once, NEVER fail the task) only when the305 vendored skill is absent, detection fails (no extension file), or the local306 review invocation errors. Flow A needs **no** CI provider secret — do NOT307 treat an unset `CURSOR_API_KEY` (or other provider secret) as a reason to308 skip the local Security Review pass; that secret is Flow B CI / gate309 messaging only. **Flow B optional companion (not a plan task):**310 when the plan's PR has been pushed and CI has posted its review, the developer311 MAY invoke the upstream `apply-review` sub-skill from within the same312 `execute` session to walk through CI findings per-finding (apply / defer /313 skip) with explicit consent — read-only by default, edits require per-finding314 yes, never commits or pushes. This is surfaced as an available option during315 `execute`; the addon MUST NOT insert an `apply-review` task file into any316 plan (would violate the mandatory-final-task-order rule).317- **Skills & Agents Discovery** (MANDATORY, **second-to-last**, task `N-1`,318 `{N-1}.task_skills_agents_discovery.md`): reviews completed tasks for new319 patterns, checks the catalog, creates/updates skills/agents if warranted,320 evaluates the skills-generator system. If no skills-generator exists in the321 target repo, write a simplified evaluate-and-document-only version.322- **Executive Report** (MANDATORY, **last**, task `N`,323 `{N}.task_executive_report.md`): generates324 `analysis_results/EXECUTIVE_REPORT.md` with Executive Summary, Product Impact,325 Technical Details, QA Verification Guide, FAQs, Next Steps.326327Add to the README a note: "Every plan includes Security Review328(third-to-last), Skills & Agents Discovery (second-to-last), and Executive329Report (last). These are auto-generated by `/dwp-create`."330331**Quality gates:** atomic, ordered tasks; both mandatory files present;332`analysis_results/` exists; `PROGRESS.md` exists; numbering correct (user tasks →333security review → skills discovery → executive report); behavior-changing tasks carry test coverage334in their Acceptance Criteria and tests + lint/type-check in their Validation335(`../guide/GUIDE.md` §5.3).336337**Accelerate generation with team agents (Claude Code only, automatic):** for3385+ user-defined task files, the lead creates README/PROMPTS/PROGRESS/339analysis_results + the mandatory final task files, then spawns teammates (1 per3402–3 task files) to write user task files in parallel (no file overlap), verifies341all files, and cleans up. Fallback: generate sequentially.342343**Orchestrator additions (orchestrator plans):**344- README **Child DWP Plans** table (`# | Repository | Child Plan | Status |345 Depends On`), an **Execution Mode** subsection, and **Dependency Rules**.346- **ORCHESTRATOR_MANIFEST.md** at `.dwp/plans/PLAN_{name}/ORCHESTRATOR_MANIFEST.md`347 (template in `../guide/GUIDE.md` §13.8): Shared Context, Child DWP Registry,348 Dependency Graph, Output Contracts, Execution State.349- Task files: direct design tasks first (if hybrid); then `create_child_dwp`350 tasks in dependency order (template351 `../examples/ORCHESTRATOR_TASK_TEMPLATE_create_child_dwp.md`); optional352 `integration_checkpoint` tasks353 (`../examples/ORCHESTRATOR_TASK_TEMPLATE_integration_checkpoint.md`);354 `execute_child_dwp` tasks for Sequential-with-Output-Handoff mode355 (`../examples/ORCHESTRATOR_TASK_TEMPLATE_execute_child_dwp.md`); then the two356 mandatory final tasks last. Each `create_child_dwp` task instructs the agent to357 navigate to the target repo, read its `AGENTS.md`, and create a child DWP at358 `repositories/{repo}/.dwp/plans/PLAN_{child}/` using that repo's conventions.359360**Team-agents metadata (when Step 2.10 detected parallelizable tasks):** add a361"Team Agents Configuration (Claude Code Only)" section to the README (Parallel362Task Groups + Teammate Roles tables) and a "Team Agents Metadata (Claude Code363Only)" section to each parallel task file (Parallel Group / Teammate Role / Can364Run With / Blocks / Files Owned). Use `../examples/TEAM_AGENTS_TASK_TEMPLATE.md`.365Rules: never put required info inside team-agents sections; every task must work366sequentially; mandatory final tasks are always sequential; file ownership between367parallel tasks must not overlap.368369### Step 5 — Completion & Execute Option370371For a full plan, report success and the location372`.dwp/plans/PLAN_{name}/`, then offer: (1) execute now → run the **Execute**373sub-skill (`../execute/SKILL.md`); (2) review the README first, then ask again;374(3) done for now → tell them to run `/dwp-execute {name}` later.375376**Dailybot kickoff (only when the Dailybot addon is wired — best-effort,377non-blocking):** after the plan is materialized and approved, send a **regular**378(non-milestone) kickoff report via the dailybot `report` sub-skill — "Starting:379\<what is being built and why it matters\>" — per the addon's lifecycle event380model (`../addons/dailybot/SPEC.md` §5.1). One kickoff per plan; skip silently381if Dailybot is absent, unauthenticated, or `.dailybot/disabled` exists. Never382block on this.383384For `refined-draft-only` mode, report the single refined draft saved at385`.dwp/drafts/PLAN_{name}_draft_refined.md` and the next step: run386`/dwp-create from PLAN_{name}_draft_refined.md` to build the final plan.387388### Step 6 — Execute Plan (Optional)389390If the user chose to execute, hand off to the **Execute** sub-skill391(`../execute/SKILL.md`): read the plan README, check git status, start from the392first `[ ]` task, execute sequentially, validate, commit per task, report.393394## Error Handling395396- **Plan name already exists:** offer different name / overwrite / cancel.397- **Name auto-converted:** show an informational notice (not an error).398- **Refined draft not found (from-refined-draft):** list available refined drafts399 in `.dwp/drafts/` and ask the user to choose.400- **Insufficient tasks (<2):** ask the user to break the work down.401402## Important Notes403404- **Git ignore:** everything under `.dwp/` is git-ignored.405- **Single artifact:** the only draft file is `PLAN_{name}_draft_refined.md` in406 `.dwp/drafts/` — there is no separate raw draft.407- **Reference:** follow `../guide/GUIDE.md`; orchestrator → §13; team agents → §14.408- **Archetypes:** orchestrator support assumes the orchestrator-hub archetype409 (sub-repos under `repositories/`); an individual repo creates standard plans.410 See `../shared/adaptation.md`.