deepworkplan-onboard

name	deepworkplan-onboard
description	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 to .agents symlink. Offers opt-in addons. Use when the developer wants to onboard or AI-enable a repo.
version	2.15.0
documentation_url	https://deepworkplan.com
user-invocable	true
allowed-tools	Bash, Read, Grep, Glob, Edit, Write

DeepWorkPlan — Onboard

Turn the target repository into an AI-first autopilot repo: a codebase whose AGENTS.md, docs/, per-module docs, .agents/, .claude → .agents symlink, 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:

1. AGENTS.md — index + mandatory rules + a Quick Commands block with the repo's real, runnable commands; plus CLAUDE.md → AGENTS.md.
2. 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.
3. Per-module nested docs — a README.md (and a docs/ subfolder for complex modules) inside each major source module discovered in recon.
4. .agents/ — reasoned agents/, commands/, skills/, docs/ (skills_agents_catalog.md + COMMANDS_REFERENCE.md), settings.json, and the .claude → .agents symlink. Skills/agents/commands are stack-appropriate, not generic boilerplate.
5. 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.

Phase 0 — Preconditions & consent

1. 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.
2. 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).
3. 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.
4. 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.
5. 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:

0. 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.)

1. 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.

2. 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.

3. 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).

4. 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:

1. 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.
2. 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.
3. 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/ + .claude → .agents symlink

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 symlink — ln -s .agents .claude. 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 symlink only if absent; never delete existing personas/commands without asking.

Phase 7 — Install the DeepWorkPlan skill + scaffold .dwp/

1. Make the DeepWorkPlan skill available to the target repo via one of (offer the developer the choice; recommend the first):
   • npx skills add DailybotHQ/deepworkplan-skill
   • OpenClaw: openclaw skills install deepworkplan
   • git clone the skill repo + run its setup.sh
   • or symlink the local skill pack into .agents/skills/deepworkplan/.
2. 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).
3. 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.

Four 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).

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 skills add DailybotHQ/agent-skill / OpenClaw / git clone + setup.sh, or the Dailybot CLI), 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), and wire the optional progress-report step into DWP execution so a plan completion emits a Dailybot milestone report via the dailybot report sub-skill. That report step 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.

Phase 8 — Self-check / validation (mandatory)

See the dedicated section below.

---

Phase 8 — Self-check / validation (run in the TARGET repo)

After generating, run this checklist in the target repo. On any failure, fix-then-recheck before reporting done. On the plan-driven path (Phase 2b), this checklist is the plan's mandatory final task — run it after the plan's other tasks complete, gating the whole onboarding before reporting done.

1. AGENTS.md exists and contains a Quick Commands block whose commands are real and runnable (not placeholders). Spot-check that referenced commands exist in the manifest/Makefile/scripts.
2. CLAUDE.md resolves to AGENTS.md — the symlink points at AGENTS.md, or CLAUDE.md contains exactly @AGENTS.md.
3. docs/ has the standard categories, each non-empty and repo-specific (the eight MUST files at minimum — PRODUCT_SPEC included — plus docs/README.md). Grep for leftover placeholder markers (<...>, "TODO", "your command here") and fix any. TESTING_GUIDE.md MUST describe either a real test/lint setup or a concrete proposed one (§3.3) — never empty, never "no tests".
4. Every major source module has a README.md (and complex modules have a docs/).
5. .agents/ has agents/, commands/, skills/, docs/, settings.json and a .claude → .agents symlink (or documented fallback); skills_agents_catalog.md and COMMANDS_REFERENCE.md match what was actually created (no phantom entries). The six dwp-* commands exist in .agents/commands/ (dwp-create, dwp-execute, dwp-refine, dwp-resume, dwp-status, dwp-verify) and are thin delegators (no leftover <skill-path> placeholder, no copied flow body).
6. DeepWorkPlan skill is discoverable and .dwp/ exists, is gitignored (git check-ignore .dwp confirms), and has plans/ + drafts/. tmp/ exists and is gitignored (git check-ignore tmp confirms).
7. Smoke test — run the repo's OWN detected validation command once to confirm recon was accurate (e.g. the lint or test command). If it cannot run (e.g. Docker required and unavailable, network-gated CI command), note why in the report instead of silently skipping. If the repo had no validation toolchain and you proposed (and scaffolded) one, run the proposed test/lint command to confirm the baseline is real; if you only documented the proposal without scaffolding, note it as a recommended follow-up in the report.
8. Archetype-specific: if orchestrator hub, confirm the sub-repo navigation index + multi-project commit workflow are documented and ECOSYSTEM_CONTEXT.md exists.
9. Objective conformance gate — run /dwp-verify. This checklist mirrors the verify sub-skill; close the loop by actually running it (read ../verify/SKILL.md and execute its repository checks) for an independent CONFORMANT / NOT CONFORMANT verdict. This dogfoods verify and turns the manual checklist into a reproducible gate. Treat a NOT CONFORMANT verdict as a Phase 8 failure: fix-then-recheck before reporting done. (On the plan-driven path, /dwp-verify is exactly the final task's gate.)
10. Write the onboarding report to .dwp/onboard/REPORT.md summarizing: the archetype chosen + evidence, the detected stack + package manager, the exact validation commands captured, the full list of files/folders generated or modified, addons accepted/declined, the smoke-test result, any symlink fallback used, and any items deferred to the developer (e.g. ambiguous modules, a command that couldn't be smoke-tested).

Report a concise summary to the developer: archetype, stack, what was generated, the smoke-test result, and any deferred items — pointing them at .dwp/onboard/REPORT.md for the detail.

---

Modes & invocation

• /deepworkplan-onboard (or "make this repo AI-first", "onboard this repo", "set up AGENTS.md + docs + .agents") — full guided flow (consent before writing).
• --dry-run / "just show me the plan" — recon + planned change set, no writes (Phase 0.5).
• trust / auto — proceed without per-step confirmations, but still get the one consent gate in Phase 0 before the first write and still surface addons.
• plan / "onboard this as a deep work plan" — force the plan-driven path (Phase 2b) regardless of size: do recon + AGENTS.md, then emit an onboarding Deep Work Plan and hand off to /dwp-execute. The flow auto-selects this path for large repos even without the flag.

Failure-mode guardrails (do not violate)

• No placeholders ship. If a real value is unknowable, ask — never write <...> or a generic guess into AGENTS.md / docs/.
• No clobbering. Existing hand-written artifacts are merged/backed-up/asked about, never silently overwritten.
• No phantom catalog entries. .agents/docs/ must reflect exactly what exists.
• No stack mismatch. If the preset and the real repo disagree, the real repo wins — re-derive from recon.
• Idempotent. Re-running on an onboarded repo only fills gaps; it does not duplicate or churn working files.