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 — resolve the target repo root, branch, agent tool, and the .dwp/ output location (dwp_dir). Run it; do not reinvent detection.
• ../shared/adaptation.md — the reasoning-over-copy-paste principle and the two archetypes. This sub-skill is its deep elaboration.
• ../shared/dwp-paths.md — the .dwp/ output convention you scaffold in Phase 7.
• presets/README.md — the per-stack reasoning guides spanning backend/API (Django, FastAPI, Rails, Spring Boot, Laravel, NestJS), frontend (Vue/Vite, Next.js, SvelteKit, Nuxt, Angular, Astro/Svelte), mobile (React Native, Flutter, Swift/iOS), and systems/infra (Go, Rust, Terraform, TypeScript Lambda, Node/TS service, Python package/CLI), plus a generic fallback and the orchestrator-hub note. See presets/README.md for the full index. Read the matching preset in Phase 1 and use it in Phases 3–6. Presets are reasoning aids, not templates.
• Bounded autonomy (conditional — read only when the trigger fires): 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 §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 §15 when the repo is large enough for the plan-driven path (Phase 2b); ../guide/orchestrator.md §13 for an orchestrator hub (child-DWP capability); ../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 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 §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 (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.
• all-addons.md (this directory) — read only when the developer asks to set up or update the repository's addons, or on a harness upgrade of a repository that already has addons (it detects every addon, upgrades the ones in use, offers the ones that fit): ../shared/addon_sync.py plan reports each addon's installed version against the pack's pin and one action per addon (install, upgrade, record, available, reconcile, current and the others all-addons.md lists); the file carries the order and the full dev-container stack; the machine-level install commands are in ../addons/machine-installs.md.
• Working principles (conditional): read ../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 — 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.16 --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):

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

   ## 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 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/ — 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 (this directory) Phase 7a and run the ../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 (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 — and bring the installed ones to the pack's pins through all-addons.md (never a downgrade, never a re-offer of a decline). A request to set up the addons that fit uses the same file.

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