DeepWorkPlan — Onboard
Turn the target repository into an AI-first autopilot repo: a codebase
whose AGENTS.md, docs/, per-module docs, .agents/, .claude → .agents and
.cursor → .agents symlinks, and gitignored .dwp/ give any AI agent (Claude Code, Cursor, OpenAI
Codex, Gemini, Copilot, Cline, Windsurf, OpenClaw) enough structured context to
work reliably without per-session human hand-holding.
The one rule that overrides everything: REASON, do not copy-paste
This flow is not a template copier and not a scaffolder. Its entire
value is that you inspect the actual target repo — its real languages,
frameworks, package manager, build/test/lint commands, folder layout, test
convention, deployment shape — and then generate artifacts adapted to that
repo. The shape of the output is fixed (the ~90%: AGENTS.md, the docs/
categories, per-module docs, .agents/, the symlinks, .dwp/); the content
is reasoned per repo (the ~10%: validation commands, paths, stack-specific
skills, example plans).
An empty doc, a generic stub, a placeholder command, or a doc copied
verbatim from this skill or another repo is a FAILURE. Never write
<your test command here>. Never write npm test unless you confirmed the
repo uses npm and has a test script. Find the real command and write it.
If you cannot determine a real value, ask the developer — do not guess and do
not leave a placeholder.
Shared resources — READ THESE FIRST
../shared/context.sh — resolve the target repo root,
branch, agent tool, and the .dwp/ output location (dwp_dir). Run it; do
not reinvent detection.
../shared/adaptation.md — the
reasoning-over-copy-paste principle and the two archetypes. This sub-skill is
its deep elaboration.
../shared/dwp-paths.md — the .dwp/ output
convention you scaffold in Phase 7.
presets/README.md — the per-stack reasoning guides
spanning backend/API (Django, FastAPI, Rails, Spring Boot, Laravel, NestJS),
frontend (Vue/Vite, Next.js, SvelteKit, Nuxt, Angular, Astro/Svelte), mobile
(React Native, Flutter, Swift/iOS), and systems/infra (Go, Rust, Terraform,
TypeScript Lambda, Node/TS service, Python package/CLI), plus a generic
fallback and the orchestrator-hub note. See presets/README.md for the full
index. Read the matching preset in Phase 1 and use it in Phases 3–6.
Presets are reasoning aids, not templates.
../guide/GUIDE.md — the DWP methodology you reference
when wiring the skill and (for hubs) the orchestrator/child-DWP capability.
templates/onboarding-plan.md — the
reasoning aid for the plan-driven path (Phase 2b): the shape of a "finish
onboarding myself" Deep Work Plan a large repo emits instead of generating
everything inline. A template to reason from, never to copy verbatim.
Ship purity: every path this flow references is relative inside
skills/deepworkplan/ (../shared/*, presets/*, ../guide/GUIDE.md,
../addons/*). Never reference any absolute host path or any
.agent_commands/... path. The output you write lives in the target repo,
at paths relative to its root.
The generated outcome (what success looks like in the target repo)
When this flow finishes, the target repo contains:
AGENTS.md — index + mandatory rules + a Quick Commands block with the
repo's real, runnable commands; plus CLAUDE.md → AGENTS.md.
docs/ — the standard categories, each filled with real
repo-specific content (real commands, real module names, real test pattern):
PRODUCT_SPEC.md (the non-technical product/why doc — required for every
repo, libraries included), ARCHITECTURE.md, STANDARDS.md,
TESTING_GUIDE.md, DEVELOPMENT_COMMANDS.md, SECURITY.md, PERFORMANCE.md,
AI_AGENT_ONBOARDING.md, AI_AGENT_COLLAB.md, optional
PR_REVIEW_WORKFLOW.md / ECOSYSTEM_CONTEXT.md, and a docs/README.md
index.
- Per-module nested docs — a
README.md (and a docs/ subfolder for
complex modules) inside each major source module discovered in recon.
.agents/ — reasoned agents/, commands/, skills/, docs/
(skills_agents_catalog.md + COMMANDS_REFERENCE.md), settings.json, and
the .claude → .agents and .cursor → .agents symlinks. Skills/agents/commands are
stack-appropriate, not generic boilerplate.
- DeepWorkPlan skill installed + a gitignored
.dwp/ scaffold
(.dwp/plans/, .dwp/drafts/, with READMEs and a .gitignore rule).
Plus, opt-in (Phase 7b): any accepted addons (the first is devcontainer).
The flow — Phases 0–8
Run the phases in order. Write your working notes to .dwp/onboard/RECON.md as
you go so generation is auditable and resumable. Treat every "detect" step as
reason about the real repo, never assume.
After recon and the archetype decision, Phase 2b picks the onboarding
strategy: generate everything inline in this session (small/medium repos —
the default), or, for a large repo, emit a Deep Work Plan that completes
the onboarding task-by-task with per-artifact gates and full resumability (the
recommended path at scale). The phase descriptions below are written for the
inline path; on the plan-driven path the same work runs as plan tasks.
Trust boundary (write scope)
allowed-tools includes write-capable Edit, Write, and Bash. Onboarding
mutates the target repository — non-destructively and by explicit design:
Writes (Phase 0 consent covers the onboarding offer; per-file rules below):
AGENTS.md (+ the CLAUDE.md symlink), the reasoned docs/ tree, per-module
docs, and .agents/ (skills/commands/agents/catalog) — reconciled with
anything that already exists; replacing or deleting existing content requires
asking the developer first.
- A
.dwp/ directory and a one-time append to .gitignore (never a
rewrite).
- On the plan-driven path, plan artifacts under
.dwp/ as create defines.
It MUST NOT: overwrite or delete existing files without explicit approval,
commit or push (commits happen only when the developer asks or a plan task's
gate defines them), touch files outside the repo, read or commit secrets, or
enable any addon without the developer's explicit acceptance of that addon's
offer.
Phase 0 — Preconditions & consent
- Resolve context. Run
bash ../shared/context.sh to get repo_root,
branch, agent_tool, and dwp_dir. All target-repo paths below are
relative to repo_root.
- Detect fresh-empty vs existing. Decide which case you are in:
- Fresh-empty — little/no source, no VCS history, no
AGENTS.md /
CLAUDE.md / docs/ / .agents/. You generate from a clean slate (still
reasoning from whatever signals exist — e.g. a single package.json).
- Existing — real source code and/or any of the above already present.
You must be idempotent and non-destructive (see below).
- Non-destructive rule (existing repos). You MUST NOT clobber a
hand-written
AGENTS.md, CLAUDE.md, docs/, .agents/, or .gitignore.
For each artifact that already exists: prefer to merge/augment; if a
destructive change is unavoidable, back it up (e.g. AGENTS.md.bak) and
ask the developer first. Re-running the flow on an
already-onboarded repo MUST be safe — detect what already conforms and only
fill gaps.
- Consent before writing. This flow mutates the developer's repo. Present
the planned change set at a high level (archetype guess, detected stack,
the list of files/folders you intend to create or modify) and get explicit
confirmation before writing anything.
- Honor dry-run / plan-only. If the developer passes
--dry-run, says
"just show me the plan", or declines to write, produce the full plan (recon +
intended change set) without writing any repo files. You MAY still write
.dwp/onboard/RECON.md as the plan artifact, after telling them.
Phase 1 — Repo reconnaissance (REASON, don't assume)
Inspect the real repo and record findings in .dwp/onboard/RECON.md. This is
the highest-value phase — everything downstream is reasoned from here.
Detect, by reading actual files (not by habit):
- Languages & frameworks. Manifests:
pyproject.toml / poetry.lock / requirements.txt / setup.cfg,
package.json / pnpm-lock.yaml / yarn.lock / package-lock.json,
go.mod, Cargo.toml, Gemfile, composer.json, pom.xml, *.csproj.
Framework signatures: manage.py+settings.py → Django; vite.config.* +
vue/react in deps → Vue/React + Vite; astro.config.* → Astro;
next.config.* → Next; Express/Fastify imports → Node service; Lambda
handlers / serverless.yml / template.yaml → serverless; a console_scripts
/ [project.scripts] entry + Click/Typer/argparse → Python CLI.
- Build / test / lint / typecheck commands — the crown jewels. Read the
manifest scripts (
package.json scripts, pyproject.toml tool config),
Makefile, Taskfile.yml, tox.ini, CI workflows (.github/workflows/*,
.gitlab-ci.yml), and any docker.sh / docker-compose.yml. Capture the
exact commands (e.g. pnpm run eslint:check, pnpm run type:check,
codecheck -f inside Docker, poetry run pytest, ruff check,
npm run biome:check, astro check). Note any command that runs only in
CI or only inside a container — flag it as such (this matters for the
Quick Commands block and the Phase 8 smoke test). If the repo has no test
and/or no lint/type-check command at all, do not just record the absence —
flag it as a gap to be closed in Phase 4 by proposing a stack-appropriate
toolchain (per ../spec/DOCUMENTATION_STANDARD.md §3.3). Validation gates are
the backbone of reliable Deep Work Plans; a repo with no way to validate its
behavior is not yet AI-first.
- Package manager. Infer from the lockfile that actually exists
(
pnpm-lock.yaml → pnpm, poetry.lock → poetry, etc.), never from habit.
- Folder layout & modules. Find the source roots (
src/, app/, lib/,
pkg/, cmd/, pages/, components/) and the major sub-modules within them.
These become the per-module docs in Phase 5.
- Test convention. File naming (
*_test.py, *.spec.ts, *.test.ts),
framework (pytest / jest / vitest / playwright / go test), and where tests
live (co-located vs tests/). If no tests exist, note that — Phase 4 will
propose a convention and framework reasoned from the stack rather than
leaving testing undefined.
- Deployment / runtime shape. Containerized? Serverless? Static site?
Long-running service? Library/package? This informs
ARCHITECTURE.md and
PERFORMANCE.md.
- Existing conventions to carry forward. Read any current
README,
CONTRIBUTING, .editorconfig, linter/formatter config, and the existing
commit-message style (git log). Carry these forward; do not override a
working convention with a generic one.
Then load the matching preset from presets/ (one per common stack across
backend, frontend, mobile, and systems/infra — see presets/README.md for the
full index — or generic if nothing matches). Use it as a reasoning
checklist, and explicitly verify each preset
assumption against what you actually found — detected reality wins over preset
assumptions.
Write .dwp/onboard/RECON.md with: detected stack, package manager, exact
validation commands (flagged CI/Docker-only where relevant), source roots +
major modules, test convention, deployment shape, carried-forward conventions,
and which preset you used.
Also record a scale count (the evidence the Phase 2b decision reads, so the
inline-vs-plan choice is mechanical, not guessed):
major_modules — the number of major source modules you'll write per-module
docs for (Phase 5).
planned_artifacts — a rough total of files to generate: AGENTS.md (1) +
the docs/ categories (~10) + one per-module README.md + the .agents/ kit.
Estimate it: ≈ 11 + major_modules for a typical repo.
Record both numbers explicitly in .dwp/onboard/RECON.md. Phase 2b thresholds
are stated against these counts.
Phase 2 — Archetype decision
Classify the repo using ../spec/ARCHETYPES.md signals (summarized in
presets/README.md):
| Signal |
Indicates orchestrator hub |
A repositories/ (or equivalent) folder of multiple independent repos |
strong |
| No single primary application stack at root; root is mostly markdown/coordination |
strong |
| Sub-repos git-ignored / tracked separately |
moderate |
| Cross-project standards, a repo navigation index, or orchestrator manifests |
moderate |
Root AGENTS.md indexes other repos' AGENTS.md |
moderate |
- Default to
individual repo (the 99% case) unless a clear majority of
signals say hub.
- A monorepo with one build/stack is an individual repo with modules
(handled by per-module docs), not a hub.
- If signals are ambiguous, present your assessment + evidence and ask the
developer before proceeding.
Record the decision and the evidence in .dwp/onboard/RECON.md. Every phase
below branches on this decision where noted.
Phase 2b — Onboarding strategy: inline vs plan-driven (scale decision)
Onboarding a repo means analyzing the whole codebase and documenting all
of it: every docs/ category, a per-module README.md for each major module,
and the full .agents/ kit (agents, skills, commands, catalogs). For a small or
medium repo, generating all of that inline in this session (Phases 3–8) is
the right, fast default.
For a large repo, doing it all inline is the wrong tool: it strains a single
context window, gives no per-artifact validation gate, can't be audited
task-by-task, and loses all progress if the session is interrupted. That is
exactly the problem Deep Work Plans solve. So for a large repo, onboarding
becomes its own Deep Work Plan — the repo's first plan is "finish onboarding
myself," executed task-by-task with gates and full resumability. This is the
methodology dogfooding itself: the onboarding uses the very loop it installs.
Decide the strategy from the recon counts (mechanical, not a guess). Read the
major_modules and planned_artifacts numbers you recorded in Phase 1. Choose
plan-driven when a clear majority of these hold (or the developer asks):
major_modules > 8 (each needs its own per-module doc, Phase 5).
planned_artifacts ≥ 15 (docs + per-module docs + .agents/).
- A monorepo / multi-package workspace, or an orchestrator hub.
- The work plainly won't fit one focused session, or must survive across
sessions/agents.
Otherwise stay inline (the typical case) — run Phases 3–8 directly. State the
counts and the resulting choice in .dwp/onboard/RECON.md so the decision is
auditable; if the counts sit right at the boundary, present them and let the
developer break the tie.
The plan-driven path:
Resume, don't regenerate (idempotency check). Before building a new plan,
look for an in-progress onboarding plan: ls .dwp/plans/PLAN_onboard_*. If one
exists, do not start over — read its PROGRESS.md, report status, and hand
off to /dwp-resume to continue from the first open task. Only generate a new
plan when none exists. (This honors the Phase 0 idempotency rule for the
plan-driven path and matches the verify sub-skill's in-progress note.)
Still complete Phase 1 recon and Phase 2 archetype here — the recon
(.dwp/onboard/RECON.md) is the analysis the plan is built from. Never skip
it.
Generate AGENTS.md + CLAUDE.md (Phase 3) up front (or as task 1) so
the plan's tasks have the index and mandatory rules to anchor to.
Instead of generating the rest inline, emit a Deep Work Plan draft under
.dwp/drafts/ whose atomic tasks are reasoned from recon — see
templates/onboarding-plan.md for the shape
(a reasoning aid, not a copy-paste). Typical decomposition:
- one task per
docs/ category (Phase 4), each gated on "no placeholders
- real commands + links resolve";
- one task per major module for its
README.md (Phase 5) — the part that
scales worst inline;
- one task for the
.agents/ kit (agents + skills + commands + catalogs,
Phase 6), gated on "catalog matches disk";
- one task to install the skill + scaffold
.dwp/ and tmp/ (Phase 7);
- the Phase 8 self-check as the mandatory final task, alongside the spec's
three mandatory final tasks (Security Review, Skills & Agents Discovery,
Executive Report).
Each task carries explicit Acceptance Criteria and a runnable
validation gate (the repo's real lint / md-check / test).
Hand off to the normal loop: refine the draft with /dwp-refine, finalize,
then /dwp-execute it task-by-task. It is resumable with /dwp-resume and
inspectable with /dwp-status.
The Phase 0 rules — non-destructive, idempotent, no placeholders, consent —
apply identically on the plan-driven path. They move into each task's
Acceptance Criteria and gate rather than disappearing. A plan-driven onboarding
that ships a placeholder doc is the same failure as an inline one.
Record the chosen strategy (inline vs plan-driven) and its evidence in
.dwp/onboard/RECON.md.
Phase 3 — Generate AGENTS.md + CLAUDE.md symlink
Reason the content from Phase 1; do not template it.
AGENTS.md (plain UTF-8 markdown, NO frontmatter, ~150–500 lines) MUST serve
three roles:
- Index — a documentation index table linking every
docs/ file you will
create (Phase 4), each with a one-line description; plus an annotated
repo-structure tree (≥2 levels) reflecting the real layout from recon.
Link only files that will exist.
- Mandatory rules — English-only; conventional commits
(
type(scope): description) with the repo's real scopes derived from its
domains; the repo's real test pattern + coverage expectation; its error/
logging conventions; repository-boundary rules (where the agent may/may not
commit); and a progress-reporting + "never block work on reporting" note.
- Quick Commands — a table of the detected install / test / lint /
type-check / build / validate commands, verbatim. Mark any command that
runs only in CI or only inside a container (e.g. "must run inside the
Docker container").
Orchestrator-hub additions (only if Phase 2 said hub): add the sub-project
navigation index link (e.g. repositories/README.md) and each sub-project's
AGENTS.md; the multi-project commit workflow (commit inside each sub-repo,
never from the hub root); and child-DWP language per ../guide/GUIDE.md
(orchestrator §).
CLAUDE.md. Create the symlink ln -s AGENTS.md CLAUDE.md. If the target
filesystem/host does not support symlinks, fall back to a one-line CLAUDE.md
containing exactly @AGENTS.md, and note the fallback in .dwp/onboard/REPORT.md.
Never duplicate AGENTS.md content into CLAUDE.md.
Existing-repo note: if AGENTS.md already exists and is hand-written,
merge your index/commands/rules into it rather than overwriting; back up +
ask before any destructive change (Phase 0).
Phase 4 — Generate docs/
Produce the standard categories, each adapted from recon — an empty or
generic doc is a failure. The conformance floor (all MUST):
PRODUCT_SPEC.md, ARCHITECTURE.md, STANDARDS.md, TESTING_GUIDE.md,
DEVELOPMENT_COMMANDS.md, SECURITY.md, AI_AGENT_ONBOARDING.md,
AI_AGENT_COLLAB.md. SHOULD: PERFORMANCE.md, plus optional
PR_REVIEW_WORKFLOW.md and ECOSYSTEM_CONTEXT.md. Always add a
docs/README.md master index.
Each doc must contain real content:
PRODUCT_SPEC.md — the non-technical product/why doc: the problem the repo
solves, who it is for, its key capabilities/features, success criteria, and
explicit non-goals. It MUST read plainly enough that anyone — a person or an
agent, technical or not — can understand what this repository is and why it
exists at a glance; that is the whole point of the document. Reason it from
the README, package description, public API, and any roadmap/issues — never a
generic stub. Required for every repo, including libraries, CLIs, and
internal tools: if there are no end users, frame the product as its
consumers (who calls this API, and why they choose it). This is the why; the
docs below are the how.
ARCHITECTURE.md — the real components, data flow, and deployment shape from
recon; an annotated diagram of the actual module layout.
STANDARDS.md — the repo's real coding conventions, naming, import order,
error/logging patterns, and forbidden anti-patterns (carry forward existing
linter config).
TESTING_GUIDE.md — the real test framework + file-naming pattern + how
to run/scope tests + coverage expectation. If the repo has no test/lint
setup, do NOT write "no tests" or leave it empty — propose a
stack-appropriate setup (recommended framework + runner, test file convention,
where tests live, a sensible initial coverage target, and the lint /
type-check / format tooling), document it as the target, and surface it to
the developer. When non-destructive and the developer consents, scaffold a
minimal runnable baseline (the test/lint scripts + at least one real smoke
test). See ../spec/DOCUMENTATION_STANDARD.md §3.3. This is essential, not
cosmetic: it is what gives every future Deep Work Plan a real validation gate.
DEVELOPMENT_COMMANDS.md — the authoritative, verbatim command reference
(install/test/lint/type-check/build/run), expanding the AGENTS.md Quick
Commands; flag CI/Docker-only commands.
SECURITY.md — the real secrets-handling location/convention, auth model,
sensitive-data boundaries, and what agents MUST NOT write into docs.
PERFORMANCE.md — performance-critical paths/budgets relevant to the runtime
shape (skip or keep brief for trivial repos).
AI_AGENT_ONBOARDING.md — a concrete first-session checklist for this repo
(clone → install with the real PM → run the real validation → where things
live).
AI_AGENT_COLLAB.md — handoff, ownership, and conflict-avoidance rules.
- (optional)
PR_REVIEW_WORKFLOW.md, ECOSYSTEM_CONTEXT.md — add when the repo
uses PRs / sits in a multi-repo ecosystem. ECOSYSTEM_CONTEXT.md is MUST
for an orchestrator hub.
docs/README.md — a one-paragraph scope statement + a table linking every
guide you created. MUST exist for a hub.
The preset for the detected stack lists the doc emphases that matter for
that stack — apply them.
Phase 5 — Generate per-module nested docs
For each major source module found in Phase 1 (a folder representing a
distinct feature/bounded concern), create a README.md inside that folder
describing: the module's responsibility, key files / public surface, and how
it's tested. For a complex or high-velocity module (3+ interconnected
concerns), add a docs/ subfolder with deeper guides, entered via a README.md.
A trivial/stable module needs only its README.md. Link each module's docs from
its own README.md; surface the most significant ones in the root AGENTS.md
index. (Reference ../spec/DOCUMENTATION_STANDARD.md §4 for the per-module rule; which
modules count as "major"/"complex" is reasoned per repo.)
Phase 6 — Generate .agents/ + agent directory symlinks
Create the canonical cross-agent config directory. All content must be
cross-agent (readable by Cursor/Codex/Gemini/Copilot as personas/procedures),
and stack-appropriate, not generic boilerplate.
.agents/agents/ — reasoned worker personas. Baseline roles: reviewer,
architect, executor, debugger, qa, perf-optimizer,
security-auditor, plus any stack-specific role the preset suggests
(e.g. a Django migration-author, a Vue component-author). Each persona
must be described well enough that a non-Claude agent can read it.
.agents/commands/ — the six short DWP commands (dwp-create,
dwp-execute, dwp-refine, dwp-resume, dwp-status, dwp-verify) plus stack-relevant
ones (code-review, pr, commit, branch). The dwp-* commands MUST be
thin delegators, NOT copies of the flow. Each is a short file (frontmatter
description: + a body) that routes the invocation to the matching sub-skill
of the installed deepworkplan skill — e.g. /dwp-create → the skill's
create sub-skill, /dwp-resume → resume, etc. Do NOT re-author the
command flow content (the skill owns it; duplicating it causes drift). This
gives users the familiar short /dwp-create / /dwp-resume aliases while the
single source of truth stays in the skill. (The skill's own sub-skills are
already user-invocable, so /deepworkplan-create etc. also work; the
dwp-* files are the shorter, conventional aliases.) Copy and adapt the
ready delegator templates at command-templates/ —
one per dwp-* command — fixing the <skill-path> to where the skill is
installed in the target repo. The same directory also ships skill-create.md
and agent-create.md — thin delegators that route /skill-create and
/agent-create to the author sub-skill so the onboarded repo can evolve
its own kit (create/update skills, agents, commands). Copy and adapt these two
alongside the dwp-* templates, fixing the same <skill-path>.
.agents/skills/ — stack-appropriate skills chosen by reasoning (use
the preset's "skills to generate" list as a starting point, then verify
against the repo's real needs), plus the DeepWorkPlan skill installed here
(Phase 7).
.agents/docs/ — skills_agents_catalog.md and COMMANDS_REFERENCE.md,
generated to match what you actually created (no phantom entries).
.agents/settings.json — a sane harness-config baseline (sensible
permissions; no secrets). .agents/README.md — a short entry point.
.claude → .agents and .cursor → .agents symlinks — ln -s .agents .claude and
ln -s .agents .cursor. Same symlink fallback as Phase 3 if unsupported (a tool-native pointer; document it).
Existing-repo note: if .agents/ (or per-tool .claude/ / .cursor/)
config already exists, reconcile into .agents/ and add the .claude and
.cursor symlinks only if absent; never delete existing personas/commands without asking.
Phase 7 — Install the DeepWorkPlan skill + scaffold .dwp/
Make the DeepWorkPlan skill available to the target repo via one of (offer
the developer the choice; recommend the first):
npx --yes skills add DailybotHQ/deepworkplan-skill@<tag> --skill deepworkplan -y
— pin the latest published tag from the repo's Releases (at the time
of writing, @v2.17.0; both --yes and -y are required in non-TTY)
- OpenClaw:
openclaw skills install deepworkplan (registry-managed pin)
- or symlink the local skill pack into
.agents/skills/deepworkplan/.
Do not offer unpinned clone-and-run variants or moving refs (@main,
@latest) — executing whatever a remote ref currently holds is an
unverifiable dependency (no version, no checksum, no rollback; the shape
Snyk W012 flags).
Scaffold the gitignored output area (per ../shared/dwp-paths.md):
create .dwp/plans/ and .dwp/drafts/, each with a README.md placeholder,
and add .dwp/ to the repo's .gitignore (append the rule
non-destructively — do not rewrite the file). .dwp/ is the only DWP output
location; it replaces any pre-v2 DWP output tree (see
../shared/dwp-paths.md for the contrast). If an older DWP output tree
exists, note it for migration (do not delete without asking).
Scaffold the tmp/ scratch area (per DOCUMENTATION_STANDARD.md §2.6):
create a root-level tmp/ with a .gitkeep, add tmp/ to the repo's
.gitignore (append non-destructively), and note the convention in
AGENTS.md — a gitignored freeform scratch space for ephemeral/throwaway
work (exploratory output, data exports, inter-agent prompt handoffs), kept
distinct from the structured .dwp/ plan output. If tmp/ already
exists, leave it as-is.
Phase 7b — Offer optional addons (opt-in)
After the core AI-first scaffolding, enumerate the available addons under
../addons/ and offer each as an explicit opt-in step. Addons are never
required — a repo is fully conformant with zero addons. In trust mode, you
MAY recommend the obviously-applicable ones, but still surface them.
Five addons ship today; enumerate all and offer each independently:
| Addon |
Folder |
Recommend in trust mode when… |
| Devcontainer support |
../addons/devcontainer/ |
the repo benefits from a reproducible isolated dev container (most repos with Docker/services). |
| Dailybot integration |
../addons/dailybot/ |
the developer/team already uses Dailybot or asks for team progress reporting — do NOT auto-install for everyone. |
| Dependency upgrade |
../addons/dependency-upgrade/ |
the repo has a lockfile + a dependency-heavy stack and wants safe, batched, validated upgrades — recommend only when a lockfile is present; never auto-install for everyone. |
| Design system |
../addons/design-system/ |
the repo has a user-facing interface surface, detected per profile: visual-ui (stylesheet with CSS custom properties, Tailwind config or @theme block, UI components, brand/style guide) is default-on when detected — in trust mode apply it (generate DESIGN.md), in guided mode strongly recommend and ask; cli-output (a CLI rendering library + a deliberate display layer) and conversational (a chat SDK or message-composition layer) are recommended when detected, always asked, never auto-applied. Never offer for a repo with no interface surface (pure library, headless service, infra-only). |
| AI Diff Reviewer |
../addons/ai-diff-reviewer/ |
the developer/team wants structured local code review on DWP Security Review and/or a CI PR merge gate — do NOT auto-install for everyone; always ask Flow A (local-only) vs Flow B (dual-surface), never default. |
The first addon is devcontainer support
(../addons/devcontainer/SKILL.md +
SPEC.md). If the developer accepts: read that
addon's SKILL.md and run its flow — match a preset in
../addons/devcontainer/templates/presets.md to the stack you detected in
Phase 1, then reason out a devcontainer adapted to that stack (base image,
user, workspaceFolder, supporting services from the app's real dependencies,
ports, public-vs-private secrets handling) while preserving the common skeleton
(AI-CLI persistence volumes for claude/codex/cursor/gh/dailybot + read-only
ssh/gitconfig mounts, dailybot-project-network, DOCKER_DEV_ENV=vscode →
sleep infinity, the codecheck/check/fix/test validation aliases, and
project-identity precedence per the addon SPEC §4). An existing devcontainer
MUST be reconciled, not clobbered — preserve working ports/network/identity and
only add missing skeleton pieces; back up and ask before any destructive change.
For a public repo, the addon also adds a secret-excluding .dockerignore and
keeps .env.example secret-free. After applying, run the addon's validation step
(SPEC §6). If declined, skip it and continue — the repo stays
baseline-conformant.
The second addon is Dailybot integration
(../addons/dailybot/SKILL.md +
SPEC.md). Offer it only when relevant — the
developer or team already uses Dailybot, or explicitly wants team progress
reporting; in trust mode, recommend it only on that signal and never
auto-install it for everyone. If accepted: read that addon's SKILL.md and run
its flow — detect whether the Dailybot skill/CLI is already present
(reconcile-don't-clobber), offer the opt-in install paths (Dailybot agent
skill via npx --yes skills add DailybotHQ/agent-skill@v3.10.3 --skill dailybot -y
/ npx --yes skills update dailybot -y / OpenClaw openclaw skills install dailybot,
or the Dailybot CLI >= 3.7.0 via pip / Homebrew / the skill's verified
installer flow), defer
all authentication to the Dailybot skill's own consent flow (shared/auth.md
— dailybot login or DAILYBOT_API_KEY; never reinvent or store credentials),
wire the four lifecycle events (kickoff, significant task, blocked,
completion) as optional progress reports via the dailybot report sub-skill,
and MAY offer deterministic hook enforcement (dailybot hook, CLI >=
3.7.0). The paired Dailybot skill (3.10.3) exposes 14 capabilities (chat,
check-ins, forms authoring, ask AI, per-repo API keys, and more); this addon wires only report
into DWP execution. Every report is strictly best-effort and never blocks
the work if Dailybot is absent, unauthenticated, or unreachable. The core
DeepWorkPlan methodology has zero Dailybot dependency — this addon is purely
optional team visibility.
After applying, run the addon's validation step (SPEC §8). If declined, skip it
and continue — the repo stays baseline-conformant.
The third addon is dependency upgrade
(../addons/dependency-upgrade/SKILL.md +
SPEC.md). It is package-manager
agnostic — offer it when the repo has a lockfile and a dependency-heavy stack;
in trust mode recommend it only when a lockfile is present, and never
auto-install it for everyone. If accepted: read that addon's SKILL.md and run
its flow — detect the repo's real package manager (npm/pnpm/yarn + ncu,
pip/poetry/uv, cargo, go mod, bundler, composer…), classify upgrades by semver,
upgrade in safe batches, run the repo's real validation gate after each
batch, revert a failing batch, and summarize. Only when accepted, the addon
installs a /lib-upgrade delegator into the repo's .agents/commands/. After
applying, run the addon's validation step (SPEC §9). If declined, skip it — the
repo stays baseline-conformant and no command is installed.
The fourth addon is design system
(../addons/design-system/SKILL.md +
SPEC.md). It is interface-surface-scoped
with per-profile strength (addon SPEC §3, §3.5) — during Phase 1 detection, check
each profile independently from real files: visual-ui (a stylesheet with
CSS custom properties, a Tailwind config or a Tailwind v4 @theme {} block, UI
components (.tsx/.vue/.svelte/.astro), a design-token file, or a
brand/style guide); cli-output (a CLI/TUI rendering library — rich, chalk,
ink, lipgloss, ratatui — plus a deliberate rendering layer such as a
display.*/ui.* helper module with semantic print helpers; a bare argument
parser with raw prints does NOT qualify); and conversational (a chat-platform
SDK — Slack, Discord, Teams, … — a message-composition layer, or documented
outbound-message voice rules). When visual-ui is detected, do not merely list
the addon: in trust mode apply it automatically (generate DESIGN.md,
developer may still decline), and in guided mode present it as a strong
recommendation and ask. When cli-output or conversational is detected,
recommend it and ask in both modes — never auto-apply those profiles. When
no profile is detected, do not offer the addon (a repo with no interface
surface must never get a DESIGN.md). Declining always leaves a
baseline-conformant repo. If accepted (or auto-applied): read that addon's
SKILL.md and run its flow — locate the repo's real design source per
accepted profile, reason out that profile's canonical sections of DESIGN.md
(visual-ui: colors & roles incl. dark mode, typography, layout & spacing,
elevation, shapes, components, responsive behavior; cli-output: output voice,
semantic colors & styles, output components, layout conventions, degradation &
environment; conversational: voice & register, message anatomy, platform
rendering — each plus do's & don'ts, with one shared Overview and one agent
prompt guide), and write it at docs/DESIGN.md (alongside the other specs
you generated in Phase 4 — root only if the repo has no docs/ tree; multiple
accepted profiles stack as sections in the same single file, never sibling
files) — never copying a third-party brand file. Then add a DESIGN.md
reference to the AGENTS.md documentation index (and CLAUDE.md) so agents
discover it like the rest of docs/. An existing DESIGN.md/token source MUST
be reconciled, not clobbered — adding a new profile to an existing file is
additive. After applying, run the addon's validation step (SPEC §11: file at
docs/DESIGN.md or root with all sections per accepted profile, AGENTS.md
references it, values traceable to the real source, per-profile integrity —
WCAG AA contrast / degradation rules / plain-text fallbacks — token references
resolve, new profiles were asked about). If declined, skip it — the repo stays
baseline-conformant.
The fifth addon is AI Diff Reviewer
(../addons/ai-diff-reviewer/SKILL.md +
SPEC.md). Offer it only when relevant —
the developer or team wants structured code-review quality on DWP work, a local
pre-push review, and/or a CI PR merge gate; in trust mode recommend it only
on that signal and never auto-install it for everyone. If accepted: read
that addon's SKILL.md and run its flow — ask Flow A (local-only) vs Flow B
(dual-surface) explicitly and NEVER default (matches the upstream skill's
ambiguity tie-break); detect whether the vendored skill / extension file /
pr-review.yml already exist (reconcile-don't-clobber); offer the opt-in
vendored-skill install via
npx --yes skills add DailybotHQ/ai-diff-reviewer@v2.0.0 --skill ai-diff-reviewer -y
(tag-pinned; both --yes and -y required); in Flow B hand off CI-workflow authoring to
the upstream setup sub-skill (never invent credentials — CURSOR_API_KEY /
provider secrets are the consumer's responsibility); wire the mandatory DWP
Security Review to run the upstream parent default flow as an additive
local-review pass; and (Flow B only) surface apply-review as an optional
developer-invoked companion during execute. Every local augmentation is
strictly best-effort and never blocks the work if the skill or extension is
absent or the local review invocation errors — an unset CI provider secret does
not skip the local Security Review pass (Flow B CI/gate only). The core
DeepWorkPlan methodology has zero AI Diff Reviewer dependency — this addon
is purely optional review quality. After applying,
run the addon's validation step (SPEC §9). If declined, skip it and continue —
the repo stays baseline-conformant.
Phase 8 — Self-check / validatio
…(truncated)
1---2name: deepworkplan-onboard-43description: Make a repository AI-first by reasoning about its stack and archetype, then generating adapted AGENTS.md, docs/, per-module docs, .agents/, and the .claude/.cursor to .agents symlinks. Offers opt-in addons. Use when the developer wants to onboard or AI-enable a repo.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-onboard-410---1112# DeepWorkPlan — Onboard1314Turn the **target repository** into an **AI-first autopilot repo**: a codebase15whose `AGENTS.md`, `docs/`, per-module docs, `.agents/`, `.claude → .agents` and16`.cursor → .agents` symlinks, and gitignored `.dwp/` give *any* AI agent (Claude Code, Cursor, OpenAI17Codex, Gemini, Copilot, Cline, Windsurf, OpenClaw) enough structured context to18work reliably without per-session human hand-holding.1920> ## The one rule that overrides everything: REASON, do not copy-paste21>22> This flow is **not** a template copier and **not** a scaffolder. Its entire23> value is that you **inspect the actual target repo** — its real languages,24> frameworks, package manager, build/test/lint commands, folder layout, test25> convention, deployment shape — and then **generate artifacts adapted to that26> repo**. The *shape* of the output is fixed (the ~90%: `AGENTS.md`, the `docs/`27> categories, per-module docs, `.agents/`, the symlinks, `.dwp/`); the *content*28> is reasoned per repo (the ~10%: validation commands, paths, stack-specific29> skills, example plans).30>31> **An empty doc, a generic stub, a placeholder command, or a doc copied32> verbatim from this skill or another repo is a FAILURE.** Never write33> `<your test command here>`. Never write `npm test` unless you confirmed the34> repo uses npm and has a `test` script. Find the *real* command and write it.35> If you cannot determine a real value, ask the developer — do not guess and do36> not leave a placeholder.3738## Shared resources — READ THESE FIRST3940- [`../shared/context.sh`](../shared/context.sh) — resolve the target repo root,41 branch, agent tool, and the `.dwp/` output location (`dwp_dir`). Run it; do42 not reinvent detection.43- [`../shared/adaptation.md`](../shared/adaptation.md) — the44 reasoning-over-copy-paste principle and the two archetypes. This sub-skill is45 its deep elaboration.46- [`../shared/dwp-paths.md`](../shared/dwp-paths.md) — the `.dwp/` output47 convention you scaffold in Phase 7.48- [`presets/README.md`](presets/README.md) — the per-stack **reasoning guides**49 spanning backend/API (Django, FastAPI, Rails, Spring Boot, Laravel, NestJS),50 frontend (Vue/Vite, Next.js, SvelteKit, Nuxt, Angular, Astro/Svelte), mobile51 (React Native, Flutter, Swift/iOS), and systems/infra (Go, Rust, Terraform,52 TypeScript Lambda, Node/TS service, Python package/CLI), plus a `generic`53 fallback and the orchestrator-hub note. See `presets/README.md` for the full54 index. Read the matching preset in Phase 1 and use it in Phases 3–6.55 **Presets are reasoning aids, not templates.**56- [`../guide/GUIDE.md`](../guide/GUIDE.md) — the DWP methodology you reference57 when wiring the skill and (for hubs) the orchestrator/child-DWP capability.58- [`templates/onboarding-plan.md`](templates/onboarding-plan.md) — the59 **reasoning aid** for the plan-driven path (Phase 2b): the shape of a "finish60 onboarding myself" Deep Work Plan a **large** repo emits instead of generating61 everything inline. A template to reason from, **never** to copy verbatim.6263> **Ship purity:** every path this flow references is relative inside64> `skills/deepworkplan/` (`../shared/*`, `presets/*`, `../guide/GUIDE.md`,65> `../addons/*`). Never reference any absolute host path or any66> `.agent_commands/...` path. The output you write lives in the **target repo**,67> at paths relative to its root.6869---7071## The generated outcome (what success looks like in the target repo)7273When this flow finishes, the target repo contains:74751. **`AGENTS.md`** — index + mandatory rules + a Quick Commands block with the76 repo's **real, runnable** commands; plus `CLAUDE.md → AGENTS.md`.772. **`docs/`** — the standard categories, each filled with **real**78 repo-specific content (real commands, real module names, real test pattern):79 `PRODUCT_SPEC.md` (the non-technical product/why doc — **required for every80 repo, libraries included**), `ARCHITECTURE.md`, `STANDARDS.md`,81 `TESTING_GUIDE.md`, `DEVELOPMENT_COMMANDS.md`, `SECURITY.md`, `PERFORMANCE.md`,82 `AI_AGENT_ONBOARDING.md`, `AI_AGENT_COLLAB.md`, optional83 `PR_REVIEW_WORKFLOW.md` / `ECOSYSTEM_CONTEXT.md`, and a `docs/README.md`84 index.853. **Per-module nested docs** — a `README.md` (and a `docs/` subfolder for86 complex modules) inside each major source module discovered in recon.874. **`.agents/`** — reasoned `agents/`, `commands/`, `skills/`, `docs/`88 (`skills_agents_catalog.md` + `COMMANDS_REFERENCE.md`), `settings.json`, and89 the `.claude → .agents` and `.cursor → .agents` symlinks. Skills/agents/commands are90 **stack-appropriate**, not generic boilerplate.915. **DeepWorkPlan skill installed** + a gitignored **`.dwp/`** scaffold92 (`.dwp/plans/`, `.dwp/drafts/`, with READMEs and a `.gitignore` rule).9394Plus, opt-in (Phase 7b): any accepted **addons** (the first is devcontainer).9596---9798# The flow — Phases 0–899100Run the phases in order. Write your working notes to `.dwp/onboard/RECON.md` as101you go so generation is auditable and resumable. Treat every "detect" step as102**reason about the real repo**, never assume.103104After recon and the archetype decision, **Phase 2b** picks the onboarding105*strategy*: generate everything **inline** in this session (small/medium repos —106the default), or, for a **large** repo, **emit a Deep Work Plan that completes107the onboarding task-by-task** with per-artifact gates and full resumability (the108recommended path at scale). The phase descriptions below are written for the109inline path; on the plan-driven path the **same work** runs as plan tasks.110111## Trust boundary (write scope)112113`allowed-tools` includes write-capable `Edit`, `Write`, and `Bash`. Onboarding114mutates the target repository — non-destructively and by explicit design:115116**Writes (Phase 0 consent covers the onboarding offer; per-file rules below):**117118- `AGENTS.md` (+ the `CLAUDE.md` symlink), the reasoned `docs/` tree, per-module119 docs, and `.agents/` (skills/commands/agents/catalog) — **reconciled** with120 anything that already exists; replacing or deleting existing content requires121 asking the developer first.122- A `.dwp/` directory and a one-time **append** to `.gitignore` (never a123 rewrite).124- On the plan-driven path, plan artifacts under `.dwp/` as `create` defines.125126**It MUST NOT:** overwrite or delete existing files without explicit approval,127commit or push (commits happen only when the developer asks or a plan task's128gate defines them), touch files outside the repo, read or commit secrets, or129enable any addon without the developer's explicit acceptance of that addon's130offer.131132## Phase 0 — Preconditions & consent1331341. **Resolve context.** Run `bash ../shared/context.sh` to get `repo_root`,135 `branch`, `agent_tool`, and `dwp_dir`. All target-repo paths below are136 relative to `repo_root`.1372. **Detect fresh-empty vs existing.** Decide which case you are in:138 - **Fresh-empty** — little/no source, no VCS history, no `AGENTS.md` /139 `CLAUDE.md` / `docs/` / `.agents/`. You generate from a clean slate (still140 reasoning from whatever signals exist — e.g. a single `package.json`).141 - **Existing** — real source code and/or any of the above already present.142 You must be **idempotent and non-destructive** (see below).1433. **Non-destructive rule (existing repos).** You **MUST NOT** clobber a144 hand-written `AGENTS.md`, `CLAUDE.md`, `docs/`, `.agents/`, or `.gitignore`.145 For each artifact that already exists: prefer to **merge/augment**; if a146 destructive change is unavoidable, **back it up** (e.g. `AGENTS.md.bak`) and147 **ask the developer first**. Re-running the flow on an148 already-onboarded repo MUST be safe — detect what already conforms and only149 fill gaps.1504. **Consent before writing.** This flow mutates the developer's repo. Present151 the **planned change set at a high level** (archetype guess, detected stack,152 the list of files/folders you intend to create or modify) and get explicit153 confirmation before writing anything.1545. **Honor dry-run / plan-only.** If the developer passes `--dry-run`, says155 "just show me the plan", or declines to write, produce the full plan (recon +156 intended change set) **without writing** any repo files. You MAY still write157 `.dwp/onboard/RECON.md` as the plan artifact, after telling them.158159## Phase 1 — Repo reconnaissance (REASON, don't assume)160161Inspect the real repo and record findings in `.dwp/onboard/RECON.md`. This is162the **highest-value** phase — everything downstream is reasoned from here.163164Detect, by reading actual files (not by habit):165166- **Languages & frameworks.** Manifests:167 `pyproject.toml` / `poetry.lock` / `requirements.txt` / `setup.cfg`,168 `package.json` / `pnpm-lock.yaml` / `yarn.lock` / `package-lock.json`,169 `go.mod`, `Cargo.toml`, `Gemfile`, `composer.json`, `pom.xml`, `*.csproj`.170 Framework signatures: `manage.py`+`settings.py` → Django; `vite.config.*` +171 `vue`/`react` in deps → Vue/React + Vite; `astro.config.*` → Astro;172 `next.config.*` → Next; Express/Fastify imports → Node service; Lambda173 handlers / `serverless.yml` / `template.yaml` → serverless; a `console_scripts`174 / `[project.scripts]` entry + Click/Typer/argparse → Python CLI.175- **Build / test / lint / typecheck commands — the crown jewels.** Read the176 manifest scripts (`package.json` `scripts`, `pyproject.toml` tool config),177 `Makefile`, `Taskfile.yml`, `tox.ini`, CI workflows (`.github/workflows/*`,178 `.gitlab-ci.yml`), and any `docker.sh` / `docker-compose.yml`. Capture the179 **exact** commands (e.g. `pnpm run eslint:check`, `pnpm run type:check`,180 `codecheck -f` *inside Docker*, `poetry run pytest`, `ruff check`,181 `npm run biome:check`, `astro check`). Note any command that runs **only in182 CI** or **only inside a container** — flag it as such (this matters for the183 Quick Commands block and the Phase 8 smoke test). **If the repo has no test184 and/or no lint/type-check command at all, do not just record the absence** —185 flag it as a gap to be closed in Phase 4 by *proposing* a stack-appropriate186 toolchain (per `../spec/DOCUMENTATION_STANDARD.md` §3.3). Validation gates are187 the backbone of reliable Deep Work Plans; a repo with no way to validate its188 behavior is not yet AI-first.189- **Package manager.** Infer from the **lockfile that actually exists**190 (`pnpm-lock.yaml` → pnpm, `poetry.lock` → poetry, etc.), never from habit.191- **Folder layout & modules.** Find the source roots (`src/`, `app/`, `lib/`,192 `pkg/`, `cmd/`, `pages/`, `components/`) and the major sub-modules within them.193 These become the per-module docs in Phase 5.194- **Test convention.** File naming (`*_test.py`, `*.spec.ts`, `*.test.ts`),195 framework (pytest / jest / vitest / playwright / go test), and where tests196 live (co-located vs `tests/`). If **no tests exist**, note that — Phase 4 will197 *propose* a convention and framework reasoned from the stack rather than198 leaving testing undefined.199- **Deployment / runtime shape.** Containerized? Serverless? Static site?200 Long-running service? Library/package? This informs `ARCHITECTURE.md` and201 `PERFORMANCE.md`.202- **Existing conventions to carry forward.** Read any current `README`,203 `CONTRIBUTING`, `.editorconfig`, linter/formatter config, and the existing204 commit-message style (`git log`). **Carry these forward**; do not override a205 working convention with a generic one.206207Then **load the matching preset** from `presets/` (one per common stack across208backend, frontend, mobile, and systems/infra — see `presets/README.md` for the209full index — or `generic` if nothing matches). Use it as a **reasoning210checklist**, and explicitly verify each preset211assumption against what you actually found — **detected reality wins over preset212assumptions**.213214Write `.dwp/onboard/RECON.md` with: detected stack, package manager, exact215validation commands (flagged CI/Docker-only where relevant), source roots +216major modules, test convention, deployment shape, carried-forward conventions,217and which preset you used.218219**Also record a scale count** (the evidence the Phase 2b decision reads, so the220inline-vs-plan choice is mechanical, not guessed):221222- `major_modules` — the number of major source modules you'll write per-module223 docs for (Phase 5).224- `planned_artifacts` — a rough total of files to generate: `AGENTS.md` (1) +225 the `docs/` categories (~10) + one per-module `README.md` + the `.agents/` kit.226 Estimate it: `≈ 11 + major_modules` for a typical repo.227228Record both numbers explicitly in `.dwp/onboard/RECON.md`. Phase 2b thresholds229are stated against these counts.230231## Phase 2 — Archetype decision232233Classify the repo using `../spec/ARCHETYPES.md` signals (summarized in234`presets/README.md`):235236| Signal | Indicates orchestrator hub |237|--------|---------------------------|238| A `repositories/` (or equivalent) folder of multiple independent repos | strong |239| No single primary application stack at root; root is mostly markdown/coordination | strong |240| Sub-repos git-ignored / tracked separately | moderate |241| Cross-project standards, a repo navigation index, or orchestrator manifests | moderate |242| Root `AGENTS.md` indexes *other repos'* `AGENTS.md` | moderate |243244- **Default to `individual repo`** (the 99% case) unless a clear majority of245 signals say hub.246- A monorepo with **one** build/stack is an **individual repo with modules**247 (handled by per-module docs), **not** a hub.248- If signals are **ambiguous**, present your assessment + evidence and **ask the249 developer** before proceeding.250251Record the decision and the evidence in `.dwp/onboard/RECON.md`. Every phase252below branches on this decision where noted.253254## Phase 2b — Onboarding strategy: inline vs plan-driven (scale decision)255256Onboarding a repo means analyzing the **whole** codebase and **documenting all257of it**: every `docs/` category, a per-module `README.md` for each major module,258and the full `.agents/` kit (agents, skills, commands, catalogs). For a small or259medium repo, generating all of that **inline** in this session (Phases 3–8) is260the right, fast default.261262For a **large** repo, doing it all inline is the wrong tool: it strains a single263context window, gives no per-artifact validation gate, can't be audited264task-by-task, and loses all progress if the session is interrupted. That is265**exactly** the problem Deep Work Plans solve. So for a large repo, **onboarding266becomes its own Deep Work Plan** — the repo's first plan is "finish onboarding267myself," executed task-by-task with gates and full resumability. This is the268methodology dogfooding itself: the onboarding uses the very loop it installs.269270**Decide the strategy from the recon counts (mechanical, not a guess).** Read the271`major_modules` and `planned_artifacts` numbers you recorded in Phase 1. Choose272**plan-driven** when a clear majority of these hold (or the developer asks):273274- `major_modules` **> 8** (each needs its own per-module doc, Phase 5).275- `planned_artifacts` **≥ 15** (docs + per-module docs + `.agents/`).276- A monorepo / multi-package workspace, or an orchestrator hub.277- The work plainly won't fit one focused session, or must survive across278 sessions/agents.279280Otherwise stay **inline** (the typical case) — run Phases 3–8 directly. State the281counts and the resulting choice in `.dwp/onboard/RECON.md` so the decision is282auditable; if the counts sit right at the boundary, present them and let the283developer break the tie.284285**The plan-driven path:**2862870. **Resume, don't regenerate (idempotency check).** Before building a new plan,288 look for an in-progress onboarding plan: `ls .dwp/plans/PLAN_onboard_*`. If one289 exists, **do not start over** — read its `PROGRESS.md`, report status, and hand290 off to `/dwp-resume` to continue from the first open task. Only generate a new291 plan when none exists. (This honors the Phase 0 idempotency rule for the292 plan-driven path and matches the `verify` sub-skill's in-progress note.)2931. Still complete **Phase 1 recon** and **Phase 2 archetype** here — the recon294 (`.dwp/onboard/RECON.md`) is the analysis the plan is built from. Never skip295 it.2962. Generate **`AGENTS.md` + `CLAUDE.md` (Phase 3) up front** (or as task 1) so297 the plan's tasks have the index and mandatory rules to anchor to.2983. Instead of generating the rest inline, **emit a Deep Work Plan draft** under299 `.dwp/drafts/` whose atomic tasks are reasoned from recon — see300 [`templates/onboarding-plan.md`](templates/onboarding-plan.md) for the shape301 (a **reasoning aid**, not a copy-paste). Typical decomposition:302 - one task **per `docs/` category** (Phase 4), each gated on "no placeholders303 + real commands + links resolve";304 - **one task per major module** for its `README.md` (Phase 5) — the part that305 scales worst inline;306 - one task for the **`.agents/` kit** (agents + skills + commands + catalogs,307 Phase 6), gated on "catalog matches disk";308 - one task to **install the skill + scaffold `.dwp/` and `tmp/`** (Phase 7);309 - the **Phase 8 self-check as the mandatory final task**, alongside the spec's310 three mandatory final tasks (Security Review, Skills & Agents Discovery,311 Executive Report).312313 Each task carries explicit **Acceptance Criteria** and a runnable314 **validation gate** (the repo's real lint / `md`-check / test).3154. Hand off to the normal loop: refine the draft with `/dwp-refine`, finalize,316 then `/dwp-execute` it task-by-task. It is resumable with `/dwp-resume` and317 inspectable with `/dwp-status`.318319> The Phase 0 rules — non-destructive, idempotent, **no placeholders**, consent —320> apply **identically** on the plan-driven path. They move into each task's321> Acceptance Criteria and gate rather than disappearing. A plan-driven onboarding322> that ships a placeholder doc is the same failure as an inline one.323324Record the chosen strategy (inline vs plan-driven) and its evidence in325`.dwp/onboard/RECON.md`.326327## Phase 3 — Generate `AGENTS.md` + `CLAUDE.md` symlink328329Reason the content from Phase 1; do not template it.330331**`AGENTS.md` (plain UTF-8 markdown, NO frontmatter, ~150–500 lines)** MUST serve332three roles:3333341. **Index** — a documentation index table linking every `docs/` file you will335 create (Phase 4), each with a one-line description; plus an annotated336 repo-structure tree (≥2 levels) reflecting the **real** layout from recon.337 Link only files that will exist.3382. **Mandatory rules** — English-only; conventional commits339 (`type(scope): description`) with the repo's **real** scopes derived from its340 domains; the repo's **real** test pattern + coverage expectation; its error/341 logging conventions; repository-boundary rules (where the agent may/may not342 commit); and a progress-reporting + "never block work on reporting" note.3433. **Quick Commands** — a table of the **detected** install / test / lint /344 type-check / build / validate commands, verbatim. **Mark** any command that345 runs only in CI or only inside a container (e.g. "must run **inside** the346 Docker container").347348**Orchestrator-hub additions** (only if Phase 2 said hub): add the sub-project349navigation index link (e.g. `repositories/README.md`) and each sub-project's350`AGENTS.md`; the **multi-project commit workflow** (commit inside each sub-repo,351never from the hub root); and **child-DWP** language per `../guide/GUIDE.md`352(orchestrator §).353354**`CLAUDE.md`.** Create the symlink `ln -s AGENTS.md CLAUDE.md`. If the target355filesystem/host does not support symlinks, fall back to a one-line `CLAUDE.md`356containing exactly `@AGENTS.md`, and note the fallback in `.dwp/onboard/REPORT.md`.357Never duplicate `AGENTS.md` content into `CLAUDE.md`.358359> **Existing-repo note:** if `AGENTS.md` already exists and is hand-written,360> merge your index/commands/rules into it rather than overwriting; back up +361> ask before any destructive change (Phase 0).362363## Phase 4 — Generate `docs/`364365Produce the standard categories, **each adapted** from recon — an empty or366generic doc is a failure. The conformance floor (all **MUST**):367`PRODUCT_SPEC.md`, `ARCHITECTURE.md`, `STANDARDS.md`, `TESTING_GUIDE.md`,368`DEVELOPMENT_COMMANDS.md`, `SECURITY.md`, `AI_AGENT_ONBOARDING.md`,369`AI_AGENT_COLLAB.md`. **SHOULD**: `PERFORMANCE.md`, plus optional370`PR_REVIEW_WORKFLOW.md` and `ECOSYSTEM_CONTEXT.md`. Always add a371`docs/README.md` master index.372373Each doc must contain **real** content:374375- `PRODUCT_SPEC.md` — the non-technical product/why doc: the problem the repo376 solves, who it is for, its key capabilities/features, success criteria, and377 explicit non-goals. It **MUST read plainly enough that anyone — a person or an378 agent, technical or not — can understand what this repository is and why it379 exists at a glance**; that is the whole point of the document. Reason it from380 the README, package description, public API, and any roadmap/issues — never a381 generic stub. **Required for every repo, including libraries, CLIs, and382 internal tools**: if there are no end users, frame the product as its383 consumers (who calls this API, and why they choose it). This is the *why*; the384 docs below are the *how*.385- `ARCHITECTURE.md` — the real components, data flow, and deployment shape from386 recon; an annotated diagram of the actual module layout.387- `STANDARDS.md` — the repo's real coding conventions, naming, import order,388 error/logging patterns, and forbidden anti-patterns (carry forward existing389 linter config).390- `TESTING_GUIDE.md` — the **real** test framework + file-naming pattern + how391 to run/scope tests + coverage expectation. **If the repo has no test/lint392 setup, do NOT write "no tests" or leave it empty** — *propose* a393 stack-appropriate setup (recommended framework + runner, test file convention,394 where tests live, a sensible initial coverage target, and the lint /395 type-check / format tooling), document it as the **target**, and surface it to396 the developer. When non-destructive and the developer consents, scaffold a397 minimal runnable baseline (the test/lint scripts + at least one real smoke398 test). See `../spec/DOCUMENTATION_STANDARD.md` §3.3. This is essential, not399 cosmetic: it is what gives every future Deep Work Plan a real validation gate.400- `DEVELOPMENT_COMMANDS.md` — the authoritative, **verbatim** command reference401 (install/test/lint/type-check/build/run), expanding the AGENTS.md Quick402 Commands; flag CI/Docker-only commands.403- `SECURITY.md` — the real secrets-handling location/convention, auth model,404 sensitive-data boundaries, and what agents MUST NOT write into docs.405- `PERFORMANCE.md` — performance-critical paths/budgets relevant to the runtime406 shape (skip or keep brief for trivial repos).407- `AI_AGENT_ONBOARDING.md` — a concrete first-session checklist for *this* repo408 (clone → install with the real PM → run the real validation → where things409 live).410- `AI_AGENT_COLLAB.md` — handoff, ownership, and conflict-avoidance rules.411- (optional) `PR_REVIEW_WORKFLOW.md`, `ECOSYSTEM_CONTEXT.md` — add when the repo412 uses PRs / sits in a multi-repo ecosystem. `ECOSYSTEM_CONTEXT.md` is **MUST**413 for an orchestrator hub.414- `docs/README.md` — a one-paragraph scope statement + a table linking every415 guide you created. **MUST** exist for a hub.416417The preset for the detected stack lists the **doc emphases** that matter for418that stack — apply them.419420## Phase 5 — Generate per-module nested docs421422For each **major** source module found in Phase 1 (a folder representing a423distinct feature/bounded concern), create a `README.md` inside that folder424describing: the module's responsibility, key files / public surface, and how425it's tested. For a **complex or high-velocity** module (3+ interconnected426concerns), add a `docs/` subfolder with deeper guides, entered via a `README.md`.427A trivial/stable module needs only its `README.md`. Link each module's docs from428its own `README.md`; surface the most significant ones in the root `AGENTS.md`429index. (Reference `../spec/DOCUMENTATION_STANDARD.md` §4 for the per-module rule; which430modules count as "major"/"complex" is reasoned per repo.)431432## Phase 6 — Generate `.agents/` + agent directory symlinks433434Create the canonical cross-agent config directory. **All content must be435cross-agent** (readable by Cursor/Codex/Gemini/Copilot as personas/procedures),436and **stack-appropriate**, not generic boilerplate.437438- **`.agents/agents/`** — reasoned worker personas. Baseline roles: `reviewer`,439 `architect`, `executor`, `debugger`, `qa`, `perf-optimizer`,440 `security-auditor`, plus any **stack-specific** role the preset suggests441 (e.g. a Django `migration-author`, a Vue `component-author`). Each persona442 must be described well enough that a non-Claude agent can read it.443- **`.agents/commands/`** — the six short DWP commands (`dwp-create`,444 `dwp-execute`, `dwp-refine`, `dwp-resume`, `dwp-status`, `dwp-verify`) plus stack-relevant445 ones (`code-review`, `pr`, `commit`, `branch`). **The `dwp-*` commands MUST be446 thin delegators, NOT copies of the flow.** Each is a short file (frontmatter447 `description:` + a body) that routes the invocation to the matching sub-skill448 of the installed `deepworkplan` skill — e.g. `/dwp-create` → the skill's449 `create` sub-skill, `/dwp-resume` → `resume`, etc. Do NOT re-author the450 command flow content (the skill owns it; duplicating it causes drift). This451 gives users the familiar short `/dwp-create` / `/dwp-resume` aliases while the452 single source of truth stays in the skill. (The skill's own sub-skills are453 already `user-invocable`, so `/deepworkplan-create` etc. also work; the454 `dwp-*` files are the shorter, conventional aliases.) Copy and adapt the455 ready delegator templates at [`command-templates/`](command-templates/) —456 one per `dwp-*` command — fixing the `<skill-path>` to where the skill is457 installed in the target repo. The same directory also ships `skill-create.md`458 and `agent-create.md` — thin delegators that route `/skill-create` and459 `/agent-create` to the **author** sub-skill so the onboarded repo can evolve460 its own kit (create/update skills, agents, commands). Copy and adapt these two461 alongside the `dwp-*` templates, fixing the same `<skill-path>`.462- **`.agents/skills/`** — **stack-appropriate** skills chosen by reasoning (use463 the preset's "skills to generate" list as a starting point, then verify464 against the repo's real needs), plus the DeepWorkPlan skill installed here465 (Phase 7).466- **`.agents/docs/`** — `skills_agents_catalog.md` and `COMMANDS_REFERENCE.md`,467 generated to **match what you actually created** (no phantom entries).468- **`.agents/settings.json`** — a sane harness-config baseline (sensible469 permissions; no secrets). `.agents/README.md` — a short entry point.470- **`.claude → .agents` and `.cursor → .agents` symlinks** — `ln -s .agents .claude` and471 `ln -s .agents .cursor`. Same symlink fallback as Phase 3 if unsupported (a tool-native pointer; document it).472473> **Existing-repo note:** if `.agents/` (or per-tool `.claude/` / `.cursor/`)474> config already exists, reconcile into `.agents/` and add the `.claude` and475> `.cursor` symlinks only if absent; never delete existing personas/commands without asking.476477## Phase 7 — Install the DeepWorkPlan skill + scaffold `.dwp/`4784791. **Make the DeepWorkPlan skill available** to the target repo via one of (offer480 the developer the choice; recommend the first):481 - `npx --yes skills add DailybotHQ/deepworkplan-skill@<tag> --skill deepworkplan -y`482 — **pin the latest published tag** from the repo's Releases (at the time483 of writing, `@v2.17.0`; both `--yes` and `-y` are required in non-TTY)484 - OpenClaw: `openclaw skills install deepworkplan` (registry-managed pin)485 - or symlink the local skill pack into `.agents/skills/deepworkplan/`.486487 Do not offer unpinned clone-and-run variants or moving refs (`@main`,488 `@latest`) — executing whatever a remote ref currently holds is an489 unverifiable dependency (no version, no checksum, no rollback; the shape490 Snyk W012 flags).4912. **Scaffold the gitignored output area** (per `../shared/dwp-paths.md`):492 create `.dwp/plans/` and `.dwp/drafts/`, each with a `README.md` placeholder,493 and add `.dwp/` to the repo's `.gitignore` (append the rule494 non-destructively — do not rewrite the file). `.dwp/` is the only DWP output495 location; it **replaces** any pre-v2 DWP output tree (see496 `../shared/dwp-paths.md` for the contrast). If an older DWP output tree497 exists, note it for migration (do not delete without asking).4983. **Scaffold the `tmp/` scratch area** (per `DOCUMENTATION_STANDARD.md` §2.6):499 create a root-level `tmp/` with a `.gitkeep`, add `tmp/` to the repo's500 `.gitignore` (append non-destructively), and note the convention in501 `AGENTS.md` — a gitignored freeform scratch space for ephemeral/throwaway502 work (exploratory output, data exports, inter-agent prompt handoffs), kept503 distinct from the **structured** `.dwp/` plan output. If `tmp/` already504 exists, leave it as-is.505506## Phase 7b — Offer optional addons (opt-in)507508After the core AI-first scaffolding, **enumerate** the available addons under509`../addons/` and offer each as an **explicit opt-in** step. Addons are **never510required** — a repo is fully conformant with zero addons. In **trust mode**, you511MAY recommend the obviously-applicable ones, but still surface them.512513Five addons ship today; enumerate **all** and offer each independently:514515| Addon | Folder | Recommend in trust mode when… |516|-------|--------|-------------------------------|517| **Devcontainer support** | [`../addons/devcontainer/`](../addons/devcontainer/SKILL.md) | the repo benefits from a reproducible isolated dev container (most repos with Docker/services). |518| **Dailybot integration** | [`../addons/dailybot/`](../addons/dailybot/SKILL.md) | the developer/team **already uses Dailybot** or asks for team progress reporting — **do NOT auto-install for everyone**. |519| **Dependency upgrade** | [`../addons/dependency-upgrade/`](../addons/dependency-upgrade/SKILL.md) | the repo has a lockfile + a dependency-heavy stack and wants safe, batched, validated upgrades — recommend only when a lockfile is present; **never auto-install for everyone**. |520| **Design system** | [`../addons/design-system/`](../addons/design-system/SKILL.md) | the repo has a **user-facing interface surface**, detected per profile: **visual-ui** (stylesheet with CSS custom properties, Tailwind config or `@theme` block, UI components, brand/style guide) is **default-on when detected** — in trust mode **apply** it (generate `DESIGN.md`), in guided mode **strongly recommend** and ask; **cli-output** (a CLI rendering library + a deliberate display layer) and **conversational** (a chat SDK or message-composition layer) are **recommended when detected, always asked, never auto-applied**. **Never offer for a repo with no interface surface** (pure library, headless service, infra-only). |521| **AI Diff Reviewer** | [`../addons/ai-diff-reviewer/`](../addons/ai-diff-reviewer/SKILL.md) | the developer/team wants structured local code review on DWP Security Review and/or a CI PR merge gate — **do NOT auto-install for everyone**; always ask Flow A (local-only) vs Flow B (dual-surface), never default. |522523The first addon is **devcontainer support**524([`../addons/devcontainer/SKILL.md`](../addons/devcontainer/SKILL.md) +525[`SPEC.md`](../addons/devcontainer/SPEC.md)). If the developer accepts: read that526addon's `SKILL.md` and run its flow — match a preset in527`../addons/devcontainer/templates/presets.md` to the stack you detected in528Phase 1, then **reason out** a devcontainer adapted to that stack (base image,529user, `workspaceFolder`, supporting services from the app's real dependencies,530ports, public-vs-private secrets handling) while preserving the common skeleton531(AI-CLI persistence volumes for claude/codex/cursor/gh/dailybot + read-only532ssh/gitconfig mounts, `dailybot-project-network`, `DOCKER_DEV_ENV=vscode` →533`sleep infinity`, the `codecheck`/`check`/`fix`/`test` validation aliases, and534project-identity precedence per the addon SPEC §4). An **existing devcontainer535MUST be reconciled, not clobbered** — preserve working ports/network/identity and536only add missing skeleton pieces; back up and ask before any destructive change.537For a **public** repo, the addon also adds a secret-excluding `.dockerignore` and538keeps `.env.example` secret-free. After applying, run the addon's validation step539(SPEC §6). If declined, skip it and continue — the repo stays540baseline-conformant.541542The second addon is **Dailybot integration**543([`../addons/dailybot/SKILL.md`](../addons/dailybot/SKILL.md) +544[`SPEC.md`](../addons/dailybot/SPEC.md)). Offer it **only when relevant** — the545developer or team already uses Dailybot, or explicitly wants team progress546reporting; in trust mode, recommend it **only** on that signal and **never547auto-install it for everyone**. If accepted: read that addon's `SKILL.md` and run548its flow — detect whether the Dailybot skill/CLI is already present549(reconcile-don't-clobber), offer the **opt-in** install paths (Dailybot agent550skill via `npx --yes skills add DailybotHQ/agent-skill@v3.10.3 --skill dailybot -y`551/ `npx --yes skills update dailybot -y` / OpenClaw `openclaw skills install dailybot`,552or the Dailybot CLI **>= 3.7.0** via pip / Homebrew / the skill's verified553installer flow), **defer554all authentication** to the Dailybot skill's own consent flow (`shared/auth.md`555— `dailybot login` or `DAILYBOT_API_KEY`; never reinvent or store credentials),556wire the **four lifecycle events** (kickoff, significant task, blocked,557completion) as optional progress reports via the dailybot `report` sub-skill,558and **MAY** offer deterministic hook enforcement (`dailybot hook`, CLI >=5593.7.0). The paired Dailybot skill (**3.10.3**) exposes 14 capabilities (chat,560check-ins, forms authoring, ask AI, per-repo API keys, and more); this addon wires only **report**561into DWP execution. Every report is strictly **best-effort and never blocks**562the work if Dailybot is absent, unauthenticated, or unreachable. The core563DeepWorkPlan methodology has **zero Dailybot dependency** — this addon is purely564optional team visibility.565After applying, run the addon's validation step (SPEC §8). If declined, skip it566and continue — the repo stays baseline-conformant.567568The third addon is **dependency upgrade**569([`../addons/dependency-upgrade/SKILL.md`](../addons/dependency-upgrade/SKILL.md) +570[`SPEC.md`](../addons/dependency-upgrade/SPEC.md)). It is **package-manager571agnostic** — offer it when the repo has a lockfile and a dependency-heavy stack;572in trust mode recommend it **only** when a lockfile is present, and **never**573auto-install it for everyone. If accepted: read that addon's `SKILL.md` and run574its flow — detect the repo's real package manager (npm/pnpm/yarn + ncu,575pip/poetry/uv, cargo, go mod, bundler, composer…), classify upgrades by semver,576upgrade in safe batches, run the repo's **real** validation gate after each577batch, revert a failing batch, and summarize. **Only when accepted**, the addon578installs a `/lib-upgrade` delegator into the repo's `.agents/commands/`. After579applying, run the addon's validation step (SPEC §9). If declined, skip it — the580repo stays baseline-conformant and no command is installed.581582The fourth addon is **design system**583([`../addons/design-system/SKILL.md`](../addons/design-system/SKILL.md) +584[`SPEC.md`](../addons/design-system/SPEC.md)). It is **interface-surface-scoped**585with per-profile strength (addon SPEC §3, §3.5) — during Phase 1 detection, check586each profile independently from **real files**: **visual-ui** (a stylesheet with587CSS custom properties, a Tailwind config or a Tailwind v4 `@theme {}` block, UI588components (`.tsx`/`.vue`/`.svelte`/`.astro`), a design-token file, or a589brand/style guide); **cli-output** (a CLI/TUI rendering library — rich, chalk,590ink, lipgloss, ratatui — **plus** a deliberate rendering layer such as a591`display.*`/`ui.*` helper module with semantic print helpers; a bare argument592parser with raw prints does NOT qualify); and **conversational** (a chat-platform593SDK — Slack, Discord, Teams, … — a message-composition layer, or documented594outbound-message voice rules). When **visual-ui** is detected, do not merely list595the addon: in **trust mode apply it automatically** (generate `DESIGN.md`,596developer may still decline), and in **guided mode present it as a strong597recommendation** and ask. When **cli-output** or **conversational** is detected,598**recommend it and ask in both modes — never auto-apply** those profiles. When599**no** profile is detected, **do not offer the addon** (a repo with no interface600surface must never get a `DESIGN.md`). Declining always leaves a601baseline-conformant repo. If accepted (or auto-applied): read that addon's602`SKILL.md` and run its flow — locate the repo's **real** design source per603accepted profile, **reason out** that profile's canonical sections of `DESIGN.md`604(visual-ui: colors & roles incl. dark mode, typography, layout & spacing,605elevation, shapes, components, responsive behavior; cli-output: output voice,606semantic colors & styles, output components, layout conventions, degradation &607environment; conversational: voice & register, message anatomy, platform608rendering — each plus do's & don'ts, with one shared Overview and one agent609prompt guide), and write it at **`docs/DESIGN.md`** (alongside the other specs610you generated in Phase 4 — root only if the repo has no `docs/` tree; multiple611accepted profiles stack as sections in the **same single file**, never sibling612files) — **never** copying a third-party brand file. Then **add a `DESIGN.md`613reference to the `AGENTS.md` documentation index** (and `CLAUDE.md`) so agents614discover it like the rest of `docs/`. An **existing `DESIGN.md`/token source MUST615be reconciled, not clobbered** — adding a new profile to an existing file is616additive. After applying, run the addon's validation step (SPEC §11: file at617`docs/DESIGN.md` or root with all sections per accepted profile, AGENTS.md618references it, values traceable to the real source, per-profile integrity —619WCAG AA contrast / degradation rules / plain-text fallbacks — token references620resolve, new profiles were asked about). If declined, skip it — the repo stays621baseline-conformant.622623The fifth addon is **AI Diff Reviewer**624([`../addons/ai-diff-reviewer/SKILL.md`](../addons/ai-diff-reviewer/SKILL.md) +625[`SPEC.md`](../addons/ai-diff-reviewer/SPEC.md)). Offer it **only when relevant** —626the developer or team wants structured code-review quality on DWP work, a local627pre-push review, and/or a CI PR merge gate; in trust mode recommend it **only**628on that signal and **never auto-install it for everyone**. If accepted: read629that addon's `SKILL.md` and run its flow — **ask Flow A (local-only) vs Flow B630(dual-surface) explicitly and NEVER default** (matches the upstream skill's631ambiguity tie-break); detect whether the vendored skill / extension file /632`pr-review.yml` already exist (reconcile-don't-clobber); offer the **opt-in**633vendored-skill install via634`npx --yes skills add DailybotHQ/ai-diff-reviewer@v2.0.0 --skill ai-diff-reviewer -y`635(**tag-pinned**; both `--yes` and `-y` required); in Flow B hand off CI-workflow authoring to636the upstream `setup` sub-skill (never invent credentials — `CURSOR_API_KEY` /637provider secrets are the consumer's responsibility); wire the mandatory DWP638**Security Review** to run the upstream parent default flow as an additive639local-review pass; and (Flow B only) surface `apply-review` as an optional640developer-invoked companion during `execute`. Every **local** augmentation is641strictly **best-effort and never blocks** the work if the skill or extension is642absent or the local review invocation errors — an unset CI provider secret does643**not** skip the local Security Review pass (Flow B CI/gate only). The core644DeepWorkPlan methodology has **zero AI Diff Reviewer dependency** — this addon645is purely optional review quality. After applying,646run the addon's validation step (SPEC §9). If declined, skip it and continue —647the repo stays baseline-conformant.648649## Phase 8 — Self-check / validatio650651…(truncated)