v7.3.0 to v7.3.1

1 added, 1 removed. Audit A to A.

---

name: deepworkplan-onboard

description: Make any repository AI-first — reason (never template) an adapted AGENTS.md, docs/, per-module docs and .agents/ kit from the real repo, discover and verify its full and scoped validation commands and source-to-test mapping, install the DeepWorkPlan skill, and, for a repository onboarded under an earlier version, perform a targeted, non-destructive, idempotent harness upgrade. Use when the developer wants to onboard or upgrade a repository for AI agents.

- version: "7.3.0"

+ version: "7.3.1"

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` 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 (`AGENTS.md`, the `docs/`

> categories, per-module docs, `.agents/`, the symlinks, `.dwp/`); the *content*

> is reasoned per repo (validation commands, paths, stack-specific skills,

> example plans). Most of a generated artifact is the fixed shape and the

> remainder is reasoned — a direction, not a ratio to quote

> (`../shared/adaptation.md`).

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

- **Bounded autonomy (conditional — read only when the trigger fires):** [`v6.md`](v6.md) when the repository will run v6 plans — the pack line is 6+ or the developer explicitly requested v6. It adds the four v6 records (capability declaration, authority boundaries, outcome/test mapping, concise working context) and the upgrade scenarios. A v5-only repository never reads it.

- **Guide (conditional — read only when the trigger fires):** [`../guide/structure.md`](../guide/structure.md) §1–§2, §10 when Phase 7 scaffolds `.dwp/` beyond the paths `../shared/dwp-paths.md` names or Phase 3b authors the first plan; [`../guide/large-repo-onboarding.md`](../guide/large-repo-onboarding.md) §15 when the repo is large enough for the plan-driven path (Phase 2b); [`../guide/orchestrator.md`](../guide/orchestrator.md) §13 for an orchestrator hub (child-DWP capability); [`../guide/authoring.md`](../guide/authoring.md) §4–§5 when emitting an onboarding plan's task files. Do not read other guide files for this flow; [`../guide/GUIDE.md`](../guide/GUIDE.md) is the routing index, consulted only when a section is not named above.

- **Spec (conditional — read the named sections when the trigger fires):** [`../spec/DOCUMENTATION_STANDARD.md`](../spec/DOCUMENTATION_STANDARD.md) §3.4 (the required content of `TESTING_GUIDE.md`) when writing or reconciling the testing guide, and §3.5 (install / onboard / upgrade, provenance, legacy-vs-declared) when the repository was onboarded before. The Phase 4 and Phase 0 text below is self-sufficient for the common case.

- [`addons.md`](addons.md) (this directory) — **read in Phase 7a and Phase 7b**: Phase 7a installs the required AI Diff Reviewer local review; Phase 7b offers the seven optional addons (dependency upgrade is near-default for repos with declared dependencies; the rest are signal-gated opt-ins) and records each acceptance in the `.dwp/config.json` addon registry. No optional addon is required for a repository to use DWP.

- **Working principles (conditional):** read

[`../shared/working-principles.md`](../shared/working-principles.md) when

Phase 0 assesses an existing harness or Phase 3 writes its agent rules;

use it again in Phase 8 to check semantic coverage and reconciliation.

- [`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/*.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 + compact working principles for

autonomous, precise, verified work + 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/`, with a README and a `.gitignore` rule).

6. **A verified testing map** in `docs/TESTING_GUIDE.md` — the full and scoped

validation commands (one scoped selection actually run where the toolchain

is runnable), the source-to-test mapping, consumer policy, blind spots,

escalation paths and fallback, plus the unit-first posture — so every future

plan can select its gates instead of guessing (`../spec/DOCUMENTATION_STANDARD.md` §3.4).

7. **A recorded standard and a first usable outcome** — the provenance line

`DWP standard: 7.0.0 (onboarded YYYY-MM-DD; skill x.y.z)` in `AGENTS.md`, and

a `.dwp/onboard/REPORT.md` that names the verified command and mapping, the

installed skill identity and version, the active capability limits (what

could not be verified and why), and the exact post-onboarding next command

(see Phase 8 item 10).

Plus the required **AI Diff Reviewer local review** (Phase 7a: vendored skill +

`.review/extension.md`) and, from Phase 7b, the **optional addons** the

developer accepted or did not decline (the near-default dependency-upgrade

delegator installs under the onboarding consent unless explicitly declined;

the signal-gated opt-ins install only when accepted — 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.

**Writes include:** with Phase 0 consent, Phase 7a may run the tag-pinned

`npx --yes skills add https://github.com/DailybotHQ/ai-diff-reviewer/tree/v3.3.1 --skill ai-diff-reviewer -y`

install into `.agents/skills/ai-diff-reviewer/` and bootstrap the repo-tailored

`.review/extension.md`; decline or offline failure is recorded as a declared

exception.

**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 optional addon without the developer's explicit acceptance of that

addon's offer (the required local reviewer of Phase 7a is covered by the

Phase 0 consent; a decline is recorded as a declared exception).

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

- **Existing and previously onboarded → harness upgrade.** `AGENTS.md`

and/or `.agents/` already exist **and** the repository's guidance predates

the installed skill's requirements: no `DWP standard:` provenance line, a

provenance line from an earlier series (2.x, 4.x, or 5.x; see

`../spec/V6_LIFECYCLE.md`), or a

`docs/TESTING_GUIDE.md` without the scoped-invocation / mapping / posture

content of `../spec/DOCUMENTATION_STANDARD.md` §3.4, or missing working

principles (§2.3.1; assess equivalent rules by meaning, not headings).

In this case run the

**targeted upgrade** (§3.5) instead of a full re-onboarding: recon only what

the upgrade needs (testing discovery for testing gaps; existing agent

rules for a principles-only gap), then reconcile **only** the

missing or outdated pieces — the §3.4 sections of `TESTING_GUIDE.md`, the

testing rule and labeled scoped variants in `AGENTS.md` (Phase 3), the

DWP flow routing block in `AGENTS.md` (Phase 3, role 5 — added when

missing, reconciled when present), the working principles (Phase 3,

role 6 — preserve equivalent rules and add only missing behavior), the scoped variants in

`DEVELOPMENT_COMMANDS.md`, the `.agents/commands/dwp-*`

delegators and `skill-create`/`agent-create` (Phase 6, refreshed from

`command-templates/`), the required AI Diff Reviewer local review (Phase 7a —

vendored skill + extension file, when missing), the catalog pointers, and

the provenance line —

leaving every handwritten section, custom skill, existing command and

in-flight plan intact (in-flight plans keep their recorded shape; they are

never migrated here — that is `refine migrate`, on explicit request). Report

a **per-file summary** of what was added or changed, **and name what the

upgrade deliberately did not create**: a repository that was never fully

onboarded can still be missing baseline harness pieces (`.agents/agents/`,

`.agents/docs/`, `CLAUDE.md`, `docs/SECURITY.md`) that a targeted upgrade

is not entitled to invent. Say which ones remain and that a full onboarding

is the way to close them — never imply the upgrade made the repository

conformant when a conformance run would still report findings. Running the

upgrade a second time **MUST** change nothing. `upgrade` / "upgrade the harness"

forces this path; the flow selects it automatically when the signals above

are present.

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

**Testing discovery (the part every future gate depends on).** Establish, by

reading configuration and running `--version` where cheap: the package

manager(s) and workspace boundaries (monorepo packages, their own scripts);

the installed test/lint/type-check tools and their **versions** where flag

behavior depends on them; the **test layers** present (unit / integration /

e2e — where each lives and how each is run); the **source-to-test

relationship** (co-located, mirrored tree, naming convention, markers,

package boundary); whether the runner supports **scoped invocation** by

file, directory, package, marker or name filter; any **affected-tests

tooling** (`--changed`, `--findRelatedTests`, `testmon`, a task graph) and

its blind spots (dynamic loading, templates, fixtures, generated inputs,

configuration); the **working directory** each command runs from; and which

paths/packages are shared or core (a change there widens validation) and

which configuration/schema/dependency/toolchain files always trigger the full

run. Then **verify one genuine scoped selection where the toolchain is

runnable**: run the scoped command against a real path of this repo and

confirm it selects a **non-empty, relevant** set (record the selected /

executed count and the exit status). A command that exits 0 having selected

nothing is **not** verified — fix the selector or record the pattern as

unverified. Where the toolchain cannot run here (Docker-only, CI-only, missing

tool), record the pattern as **proposed / unverified** with the reason and a

real fallback — never as verified. **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.

- **Feature areas (the feature tier).** Detect candidate **major feature or

capability areas** — bigger than one module — using the triggers of

`../spec/DOCUMENTATION_STANDARD.md` §4.1: a capability spanning 2+ major

modules; a sub-app or self-contained subsystem directory (e.g.

`app/{domain}/`, or a top-level sub-app); an area carrying its own contracts

(an API surface, events, schemas, protocols) that multiple consumers depend

on. Heuristics, not bureaucracy — judge per repo and record the trigger with

each candidate. These become the per-feature `docs/` of 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) with their working

directory, the **testing map** (layers, mapping rule, scoped patterns and the

verified-run evidence or the unverified/proposed marking, affected-test tooling

and blind spots, shared/core paths and full-run triggers, fallback), source

roots + major modules + feature areas (each candidate with its trigger),

test convention, deployment shape, carried-forward conventions, and which

preset you used.

**Also record a machine-readable docs registry** at the end of RECON.md — one

line per documented area (`module: <path>`, `feature-area: <path> (trigger: …)`)

— so Phase 5 and the conformance checker (`../verify/conformance.sh`) read the

same recorded judgment instead of re-guessing it. A feature area deliberately

left without its `docs/` is recorded on the same line

(`(no docs — <reason>)`) — a decision, not an oversight.

**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 common 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,

list existing folders with `../shared/plan_paths.py --plans-dir

<dwp_dir>/plans list` and look for an in-progress onboarding plan, whether

numbered (`PLAN_<id>_onboard_*`) or legacy (`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, **materialize a Deep Work Plan** under

`.dwp/plans/` 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 folded into the plan's single mandatory Final

Review** (security pass, final-state validation, skills reconciliation,

documentation reconciliation — `../spec/DWP_SPECIFICATION.md` §6.1);

skills decisions are task-local and the Executive Report is optional.

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: adjust the plan with `/dwp-refine` if needed,

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 2c — Bounded-autonomy records (v6 repositories only)

**Only when** the repository will run v6 plans (pack line 6+ or an

explicit v6 request), read [`v6.md`](v6.md) and reconcile its four

records — capability declaration, authority boundaries, outcome/test

mapping, concise working context — into the Phase 3–4 outputs, applying

the Phase 0 rules verbatim. A v5-only repository skips this phase

entirely; nothing v6 is added, and no existing plan is touched.

## 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)** is a **compact entry

point** (`../spec/DOCUMENTATION_STANDARD.md` §2.4.1): the mandatory constraints

and quick commands inline, everything else one direct link away in the focused

`docs/` guide or module doc that owns it. Brevity comes from linking, never from

dropping an invariant an agent needs to act safely; no word cap hides required

context. It MUST cover these six responsibilities:

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 **and the

validation rule** (gates are selected from a change's touched surface using

`docs/TESTING_GUIDE.md`'s mapping, with the documented fallback to the full

suite); 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, with the **scoped variant

next to the full one where the toolchain supports it**, each labeled

(`full` / `scoped`). **Mark** any command that

runs only in CI or only inside a container (e.g. "must run **inside** the

Docker container"), and any scoped pattern that is proposed/unverified.

4. **Provenance** — one line, `DWP standard: 7.0.0 (onboarded YYYY-MM-DD;

skill x.y.z)` (on upgrade: `…; upgraded YYYY-MM-DD; skill x.y.z`), so a

checker and a future agent can tell which standard the repository declares

(`../spec/DOCUMENTATION_STANDARD.md` §3.5).

5. **DWP flow routing** — a concise intent-to-flow block so any agent that

reads `AGENTS.md` knows how structured work is invoked **in this repo**,

without a network or a prior session. Keep it small (it lives inside the

lean-index budget); reconcile it with any routing/preferences text the

repository already has — merge, never replace, and never widen it into an

interception policy. The block MUST state, in this structure:

```markdown

## Deep Work Plans — invocation

Structured work runs through the local DWP flows (`.agents/commands/dwp-*`

delegators; the flows live in `.agents/skills/deepworkplan/` — discovery is

local, no network service is consulted):

| Intent | Route |

|---|---|

| "plan this work", "create a plan" | `/dwp-create` |

| "execute / run the plan" | `/dwp-execute` |

| "continue / resume the interrupted plan" | `/dwp-resume` |

| "plan status", "what's left" | `/dwp-status` (read-only) |

| "verify the repo / the plan" | `/dwp-verify` (read-only) |

| ordinary direct edit ("fix this", "rename that") | done directly — never silently becomes a plan |

Hosts without slash commands invoke the same flows by name

(`#deepworkplan-create` or plain text). `trust`/`auto` authorizes

unattended continuation within the requested flow; it is not a flow

selector, and read-only routes stay read-only.

```

Reason the wording to the repo (an existing command kit with different

names keeps its names, with the DWP routes listed alongside), but every

property in the block must survive: explicit planning requests create;

execute/resume requests invoke those flows; status/verify remain

read-only; ordinary direct edits do not secretly become plans; trust is

not a flow selector; discovery is local.

6. **Working principles** — apply

[`../shared/working-principles.md`](../shared/working-principles.md) inline.

Reason from the existing rules: keep equivalent wording, add missing

behaviors, and preserve explicit preferences and approval boundaries.

Cover ownership, resourcefulness, routine decisions, informed escalation,

concrete approvals, recovery, scope, proportionate rigor, direct

communication, and evidence-backed completion. These defaults apply to

ordinary work as well as plans; they never authorize execution of an

analysis request or override plan gates. Keep the block compact and merge

equivalent sections instead of appending duplicates.

**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/orchestrator.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).

**Budget — the lean index is enforced, not hoped for (§2.1.1).** The

`AGENTS.md` you generate MUST stay within the 150–500-line budget. When the

reasoned content would exceed it, move the detail into the focused `docs/`

guide (or module/feature doc) that owns it and link it from the index — and

the index MUST link every doc that received displaced content, so nothing

silently disappears. Never drop an invariant an agent needs in order to act

safely just to fit the budget; detail moves, it is not deleted. An existing

handwritten `AGENTS.md` already over the budget is **never silently

rewritten**: report the overweight with a concrete migration proposal (what

moves where, which links get added) and apply it only with the developer's

consent (Phase 0's non-destructive rule).

## 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 +

coverage expectation, and the required content of

`../spec/DOCUMENTATION_STANDARD.md` §3.4, all from Phase 1's testing map:

**(commands)** the full-suite command(s) and the full lint/format/type-check

commands; the **scoped invocation pattern(s)** (by file, directory, package,

marker/name filter) each with **one concrete example from this repository**,

its working directory, the tool version where flags depend on it, and the

expected evidence of a correct run (the verified selected/executed count) —

a pattern copied from tool docs without a repository example is not enough;

scoped lint/format/type-check **only where genuinely supported** (say plainly

when a project-wide check is the real option or the cheaper one); when the

full suite is cheap, recommend it over elaborate selection. **(mapping)** the

source-to-test mapping rule; the dependent-consumer policy (the affected-tests

tool or documented consumer list, and what to do when none exists); the known

blind spots (dynamic loading, templates, fixtures, generated inputs,

configuration, migrations); the escalation paths (which paths/packages are

shared or core; which config/schema/dependency/toolchain changes always trigger

the full run); and an explicit **fallback statement** ("run `<full command>`")

for whatever scoping cannot cover. **(posture)** where each test layer lives

and how it runs; **unit-first behavioral coverage** as the base — fast,

deterministic tests of observable behavior and meaningful boundaries, covering

errors, edge cases and regressions, with mocks at useful boundaries and

**no** assertions on internal call sequences; **real-seam integration** (which

contracts, persistence, routing, serialization, auth or wiring seams carry

integration/contract tests, and that a change to such a seam adds them);

**useful end-to-end** coverage (few, high-value flows); deterministic

fixtures and meaningful assertions. Teach this as a default cost/risk

strategy — **no** ratio quotas, no test-count targets, no universal

millisecond promise, no fake isolation, and no blanket rewrite of the existing

suite. Keep **current capabilities** and any **proposed** setup in clearly

separate sections so nobody mistakes a proposal for a verified command.

**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 — **including the scoped invocation pattern the

proposed runner supports**, so the repo is efficient by construction), sized

proportionately to the repo's conventions and maturity, document it as the

**target** (marked proposed, never verified), and surface it to the

developer. Do not install tools silently and do not invent a runnable gate;

obey the repo's dependency policy and the Phase 0 consent. 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, with the **scoped variants** of test/lint/type-check listed next to

the full ones and each labeled full or scoped (and proposed/unverified where

applicable); 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.)

**Feature tier (§4.1).** For each feature area the RECON registry recorded as

major, create its own `docs/` folder next to the area's code — architecture

decisions, contracts, runbooks — entered via the area's `README.md`. Link the

most significant entries from the READMEs of the modules the area spans and

surface them in the root `AGENTS.md` index, exactly like per-module docs. An

area recorded as major but deliberately left undocumented carries the recorded

reason from RECON. The feature tier sits above, never instead of, the

per-module tier: a module inside a feature area still gets its own

`README.md`.

## 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 seven short DWP commands (`dwp-create`,

`dwp-execute`, `dwp-refine`, `dwp-resume`, `dwp-status`, `dwp-verify`,

`dwp-upgrade`) 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).

`COMMANDS_REFERENCE.md` opens by stating the three invocation forms — `/`

in Claude Code, `#<name>` in agents that intercept slash syntax, and plain

text ("run `<name>`") on hosts without slash commands — so flow discovery

stays local and host-portable from the index alone.

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

> A tool-created `.claude/` / `.cursor/` directory whose only content is symlinks

> into `.agents/` may be converted to the canonical root symlink outright — that

> is a zero-loss reconciliation, not a deletion.

> On a **harness upgrade** (Phase 0), refresh the `dwp-*`, `skill-create` and

> `agent-create` delegators from `command-templates/` (they are thin and owned

> by the skill), leave every other command, agent and skill as-is, and update

> only the catalog entries that point at refreshed files.

## 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 https://github.com/DailybotHQ/deepworkplan-skill/tree/<tag> --skill deepworkplan -y`

— **pin the latest published tag** from the repo's Releases (check it;

never write a tag you did not verify; 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).

**Verify every skills-CLI install — mandatory.** Two CLI defects are

known from round-1 benchmark evidence: an `@tag` pin can be display-only,

and a parallel-mkdir race can report success while placing no content.

**Pre-create the target** `.agents/skills/deepworkplan/` before the call

(documented race workaround), then follow the install-verification

contract around every `skills add` call

(`../shared/install-verification.md`): verify what landed, retry once,

fall back to the byte-exact `git archive` install — never proceed

silently on a mismatched or empty install.

2. **Scaffold the gitignored output area** (per `../shared/dwp-paths.md`):

create `.dwp/plans/` with a `README.md` placeholder, and append to the

repo's `.gitignore` (non-destructively — do not rewrite the file) the

two lines `.dwp/*` and `!.dwp/config.json`: plans stay ignored, the

addon registry is shared with teammates and CI (`../spec/CONFIG.md` §1).

An existing `.dwp/` rule stays conformant; propose the exception. `.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 7a — Install the AI Diff Reviewer local review (required)

The local review is part of the baseline since standard 2.3.0

(`../spec/ADDONS.md` §6.5). When the core flow is done (Phases 3–7), read

[`addons.md`](addons.md) (this directory) Phase 7a and run the

[`../addons/ai-diff-reviewer/SKILL.md`](../addons/ai-diff-reviewer/SKILL.md)

flow: pinned install of the vendored skill into `.agents/skills/ai-diff-reviewer/`,

extension bootstrap at `.review/extension.md` (upstream `generate-extension`),

Flow A as the baseline and Flow B offered as an explicit opt-in. Reconcile what

already exists. When the install cannot run here (sandbox, offline) or the

developer declines, record the gap in the report and, for a decline, as a

declared exception in `AGENTS.md` — never silently. A **harness upgrade**

(Phase 0) reconciles the same two pieces when missing.

The Phase 7 install-verification contract applies verbatim to the reviewer's

pinned `skills add` call (`.agents/skills/ai-diff-reviewer/`): pre-create,

verify the installed `version:` equals the pinned tag, retry once, byte-exact

fallback.

## Phase 7b — Offer optional addons (trigger only)

The remaining addons are optional; **no optional addon is required for a

repository to use DWP**. After Phase 7a, read [`addons.md`](addons.md) (this

directory) Phase 7b and make the offer it describes: six addons are

signal-gated opt-ins that install only on explicit acceptance; the seventh —

dependency upgrade — is **near-default** for every repo with declared

dependencies: its **inert** `/lib-upgrade` delegator installs under the

Phase 0 onboarding consent **unless explicitly declined**, and no upgrade ever

runs from an install. Each acceptance is recorded with `python3

../shared/config.py enable <key> --repo <repo>` (`../spec/CONFIG.md`); a

decline writes nothing. On a **harness

upgrade** (Phase 0) do not re-offer addons the repository already declined or

already has; mention only new ones, briefly.

## 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. It is a **lean index within the

150–500-line budget** (`../spec/DOCUMENTATION_STANDARD.md` §2.1.1) — if it

ran past the budget, move the detail into the owning doc and link it, never

drop an invariant — and **every relative `.md` link in its index resolves**

to a file that exists (§2.2 links no file that does not exist); fix any

that do not. It carries the **DWP flow routing block** (Phase 3, role 5)

with every property intact: explicit planning requests create;

execute/resume requests invoke those flows; status/verify stay read-only;

ordinary direct edits never silently become plans; trust is not a flow

selector; discovery is local. Review the **working principles** by meaning

(Phase 3, role 6; `../shared/working-principles.md`): all ten behaviors must

be present without weakening existing scope, approval rules, or gates.

Reassess the reconciled file and confirm a second pass needs no edits.

Report instruction coverage separately from observed agent behavior.

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" — **and MUST carry

the §3.4 content**: full and scoped commands with a repository example and

the verified-run evidence (or an honest proposed/unverified marking with a

fallback), the mapping rule, consumer policy, blind spots, escalation paths,

the fallback statement, and the unit-first posture with current and proposed

kept apart. `AGENTS.md` carries the `DWP standard:` provenance line and

labeled scoped variants in Quick Commands.

4. **Every major source module has a `README.md`** (and complex modules have a

`docs/`) — and **every feature area the RECON registry recorded as major has

its feature `docs/` entered via a `README.md`**, or its recorded no-docs

reason on the registry line (§4.1).

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 seven `dwp-*` commands exist** in

`.agents/commands/` (`dwp-create`, `dwp-execute`, `dwp-refine`, `dwp-resume`,

`dwp-status`, `dwp-verify`, `dwp-upgrade`) 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/`. **`tmp/`

exists and is gitignored** (`git check-ignore tmp` confirms). **The AI Diff

Reviewer local review is installed**: `.agents/skills/ai-diff-reviewer/SKILL.md`

exists and an extension file is present at a recognized path

(`.review/extension.md` preferred) — or the report and `AGENTS.md` record

the declared exception / the reason the install could not run here.

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`](../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 (on an upgrade: the **per-file summary** of what was added or

changed), 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) — plus the **first usable

outcome**: the verified scoped command and mapping (or the honest gap), the

installed skill identity and version, the active capability limits, and

the **exact post-onboarding next command** — `/dwp-create "<one-line

goal>"` on hosts with slash commands, `#deepworkplan-create "<one-line

goal>"` or plain text ("run deepworkplan-create …") where slash syntax is

unavailable — or, when something must be fixed first, that fix stated as

the next command instead of a vague pointer.

11. **Upgrade idempotency (harness upgrade only):** run the upgrade reconciliation

a second time; it MUST report no changes. If it does not, fix the cause

before reporting done.

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.

- `upgrade` / "upgrade the harness" / "bring this repo to the current DWP

standard" — force the **targeted harness upgrade** (Phase 0): reconcile only

what the newer standard requires, preserve everything handwritten, report

per file, idempotent. Selected automatically when a previously onboarded repo

predates the installed standard.

- `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. A harness upgrade run twice changes nothing

the second time.

- **No invented scoped commands.** A scoped pattern is either verified against

a real path of this repository (non-empty selection recorded) or marked

proposed/unverified with a real fallback. Never label a supported feature

unavailable to avoid checking, and never label an unchecked pattern verified.

- **No required optional addons.** The core outcome (Phases 3–8) never depends

on an optional addon; those are offered, not assumed. The one required

component beyond the core scaffolding is the AI Diff Reviewer local review

(Phase 7a), installed pinned and recorded honestly when it cannot be.