Deepworkplan Onboard

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:

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 and .cursor → .agents symlinks. 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.

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

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):

• 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/ + 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/

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

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.

Five addons ship today; enumerate all and offer each independently:

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)