# Deepworkplan Onboard

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

- Skill: `dailybothq/deepworkplan-onboard` (Agent Skill, multi-file: 32 files)
- Install (CLI): `npx skillmds@latest add dailybothq/deepworkplan-onboard`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dailybothq/deepworkplan-onboard/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dailybothq (https://skillmd.com/u/dailybothq)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dailybothq/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`](../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`](../shared/adaptation.md) — the
  reasoning-over-copy-paste principle and the two archetypes. This sub-skill is
  its deep elaboration.
- [`../shared/dwp-paths.md`](../shared/dwp-paths.md) — the `.dwp/` output
  convention you scaffold in Phase 7.
- [`presets/README.md`](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`](../guide/GUIDE.md) — the DWP methodology you reference
  when wiring the skill and (for hubs) the orchestrator/child-DWP capability.
- [`templates/onboarding-plan.md`](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.

## 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`](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/`](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 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.

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

| Addon | Folder | Recommend in trust mode when… |
|-------|--------|-------------------------------|
| **Devcontainer support** | [`../addons/devcontainer/`](../addons/devcontainer/SKILL.md) | the repo benefits from a reproducible isolated dev container (most repos with Docker/services). |
| **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**. |
| **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**. |
| **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). |
| **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. |

The first addon is **devcontainer support**
([`../addons/devcontainer/SKILL.md`](../addons/devcontainer/SKILL.md) +
[`SPEC.md`](../addons/devcontainer/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`](../addons/dailybot/SKILL.md) +
[`SPEC.md`](../addons/dailybot/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` / `npx skills update dailybot`
/ OpenClaw / git clone + `setup.sh`, or the Dailybot CLI **>= 3.7.0**), **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`](../addons/dependency-upgrade/SKILL.md) +
[`SPEC.md`](../addons/dependency-upgrade/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`](../addons/design-system/SKILL.md) +
[`SPEC.md`](../addons/design-system/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`](../addons/ai-diff-reviewer/SKILL.md) +
[`SPEC.md`](../addons/ai-diff-reviewer/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 --skill ai-diff-reviewer -y`
(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 / 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 `.claude → .agents` + `.cursor → .agents` symlinks (or documented fallback);
   `skills_agents_catalog.md` and `COMMANDS_REFERENCE.md` **match** what was
   actually created (no phantom entries). **The six `

…(truncated)