Skip to content

j-mauro-r/SAT-Dengue-V2 / .agents/skills/deepworkplan

deepworkplan

Verified

DeepWorkPlan — turn any repo AI-first and run Deep Work Plans. Routes to create, execute, refine, resume, status, verify, upgrade, and repo-onboarding sub-skills based on intent. Use when the developer wants to plan, execute, manage, or verify structured multi-task work, or make a repository AI-agent-ready.

FileKindSize
SKILL.mdskill md12.0 KB
TRUST.mdmarkdown16.1 KB
addons/README.mdmarkdown11.7 KB
addons/machine-installs.mdmarkdown2.9 KB
examples/CREATE_PLAN.mdmarkdown6.9 KB
examples/ORCHESTRATOR_TASK_TEMPLATE_create_child_dwp.mdmarkdown15.0 KB
examples/ORCHESTRATOR_TASK_TEMPLATE_execute_child_dwp.mdmarkdown16.7 KB
examples/ORCHESTRATOR_TASK_TEMPLATE_integration_checkpoint.mdmarkdown9.0 KB
examples/PROMPTS_TEMPLATE.mdmarkdown4.0 KB
examples/TEAM_AGENTS_TASK_TEMPLATE.mdmarkdown5.1 KB
examples/V6_PLAN_EXAMPLE.mdmarkdown5.5 KB
guide/GUIDE.mdmarkdown8.0 KB
guide/authoring.mdmarkdown28.5 KB
guide/execution.mdmarkdown21.0 KB
guide/large-repo-onboarding.mdmarkdown3.3 KB
guide/orchestration-at-scale.mdmarkdown11.4 KB
guide/orchestrator.mdmarkdown37.9 KB
guide/prompts.mdmarkdown10.1 KB
guide/skills-integration.mdmarkdown6.5 KB
guide/structure.mdmarkdown6.2 KB
guide/swarm.mdmarkdown21.2 KB
guide/team-agents.mdmarkdown12.3 KB
shared/adaptation.mdmarkdown2.7 KB
shared/addon_sync.pyscript17.7 KB
shared/benchmark.pyscript97.6 KB
shared/config.pyscript41.5 KB
shared/context.shscript4.2 KB
shared/context_manifest.pyscript40.8 KB
shared/contract_v6.pyscript82.7 KB
shared/delegators.pyscript3.0 KB
shared/dwp-paths.mdmarkdown5.8 KB
shared/finalize_plan.pyscript7.2 KB
shared/install-verification.mdmarkdown1.8 KB
shared/ledger.pyscript141.5 KB
shared/migrate_v6.pyscript46.5 KB
shared/outcomes.pyscript27.2 KB
shared/plan_paths.pyscript4.8 KB
shared/resources.pyscript49.0 KB
shared/scheduler.pyscript41.6 KB
shared/state_contract.pyscript9.8 KB
shared/swarm.pyscript27.3 KB
shared/troubleshooting.mdmarkdown7.4 KB
shared/update-state.pyscript12.5 KB
shared/views.pyscript21.0 KB
shared/working-principles.mdmarkdown7.1 KB
spec/ADDONS.mdmarkdown27.4 KB
spec/AGENT_PROTOCOL.mdmarkdown28.0 KB
spec/ARCHETYPES.mdmarkdown10.6 KB
spec/BENCHMARK.mdmarkdown20.3 KB
spec/CONFIG.mdmarkdown8.7 KB
spec/DOCUMENTATION_STANDARD.mdmarkdown40.7 KB
spec/DWP_SPECIFICATION.mdmarkdown65.1 KB
spec/LITE_PLANS.mdmarkdown4.0 KB
spec/PLAN_STATE.mdmarkdown34.9 KB
spec/README.mdmarkdown11.5 KB
spec/V6_CONTEXT.mdmarkdown6.4 KB
spec/V6_CONTRACT.mdmarkdown12.3 KB
spec/V6_LIFECYCLE.mdmarkdown13.5 KB
spec/V6_RESOURCES.mdmarkdown4.7 KB
spec/V7_ABILITIES.mdmarkdown4.9 KB
spec/V7_CONTRACT.mdmarkdown6.4 KB
spec/V7_ROADMAP.mdmarkdown4.6 KB
spec/schema/addon-descriptor-v1.schema.jsonconfig5.5 KB
spec/schema/benchmark-record.schema.jsonconfig14.0 KB
spec/schema/context-manifest-v6.schema.jsonconfig12.5 KB
spec/schema/dwp-config-v1.schema.jsonconfig3.5 KB
spec/schema/dwp-handoff-v1.schema.jsonconfig3.0 KB
spec/schema/journal-event-v6.schema.jsonconfig22.3 KB
spec/schema/journal-event-v7.schema.jsonconfig24.9 KB
spec/schema/learnings-record.schema.jsonconfig6.0 KB
spec/schema/plan-contract-v6.schema.jsonconfig16.4 KB
spec/schema/plan-contract-v7.schema.jsonconfig16.6 KB
spec/schema/plan-manifest-v2.schema.jsonconfig1.0 KB
spec/schema/plan-manifest-v5.schema.jsonconfig1.3 KB
spec/schema/plan-manifest-v6.schema.jsonconfig2.0 KB
spec/schema/plan-manifest-v7.schema.jsonconfig1.7 KB
spec/schema/plan-manifest.schema.jsonconfig1.8 KB
spec/schema/plan-snapshot-v6.schema.jsonconfig7.8 KB
spec/schema/plan-state-v2.schema.jsonconfig6.4 KB
spec/schema/plan-state-v5.schema.jsonconfig6.7 KB
spec/schema/plan-state.schema.jsonconfig3.7 KB

spec/DOCUMENTATION_STANDARD.md

View on GitHub
# DOCUMENTATION_STANDARD.md — DeepWorkPlan Repository Documentation Standard

> **Version scope:** This is a retained v5.0.0 base document. The current
> v6 standard also requires the applicable `V6_*.md` extensions indexed in
> [README.md](README.md). Existing v5 plans keep this document’s recorded rules.

## Abstract

This document specifies the normative repository-structure standard that makes a
codebase an **AI-first autopilot repo**: a repository whose documentation,
configuration, and conventions give any AI coding agent — Claude Code, Cursor,
OpenAI Codex, Google Gemini, GitHub Copilot, Antigravity, or any future agent —
enough structured context to work reliably without per-session human guidance.

The standard is grounded in an audit of **6 Dailybot repositories**
(an API, a web app, serverless functions, a chat gateway, a marketing site,
and the orchestrator hub). Roughly **90% of the structure is identical
across all six**; roughly **10% is repo-specific** (validation commands, file
paths, stack-specific skills, example plans). This document specifies the common
90% as the normative standard and explicitly flags the 10% as values an
onboarding agent MUST **reason about per repo**, never copy verbatim.

The standard applies to **both archetypes** defined in `ARCHETYPES.md`: the
**individual repo** (the common case) and the **orchestrator hub**. Archetype-specific
requirements are called out inline.

---

## Status of This Document

| Field | Value |
|-------|-------|
| **Version** | 5.0.0 |
| **Status** | Stable |
| **Supersedes** | `DOCUMENTATION_STANDARD.md` 2.3.0, 2.1.0; `PLAN_build_deepworkplan_brand/.../deepworkplan/spec/DOCUMENTATION_STANDARD.md` (v1.0.0) |
| **Companions** | `DWP_SPECIFICATION.md`, `AGENT_PROTOCOL.md`, `ARCHETYPES.md`, `ADDONS.md` |
| **License** | MIT |

> **Divergence from 2.3.0 (overview).** 5.0.0 aligns this document's version
> with the DWP standard it accompanies (the same alignment move
> `DWP_SPECIFICATION.md` 4.0.0 and 5.0.0 made — no existing requirement
> changes) **plus** this generation's additive rules: the lean-index **budget
> is enforced** (§2.1.1 — harness-generated AGENTS.md stays in the 150–500
> line budget by moving detail into `docs/` and linking) and the **feature
> tier** (§4.1 — major capability areas carry their own internal `docs/`,
> with testable triggers for when it applies).

> **Divergence from v1 (overview).** v1 framed the standard as a "3-tier hierarchy"
> with Bronze/Silver/Gold/Platinum conformance badges and used `.agent_commands/`
> as the DWP home. v2 keeps the tier *idea* but: (a) names a concrete **10-category
> `docs/` set** observed across the 6 repos rather than v1's 5-file minimum
> (`RECONCILIATION.md` §"Specs", divergence #6); (b) formalizes **per-module
> `README.md` + `docs/`** as a normative requirement, not an optional Platinum
> add-on (divergence #6); (c) adds the **`.agents/` directory + `.claude → .agents`
> directory symlink** (divergence #4); and (d) relocates DWP output to `.dwp/`
> (see `DWP_SPECIFICATION.md`, divergence #2). The conformance-badge ladder is
> retained as informative, not normative.

---

## 1. Conventions and Terminology

### 1.1. RFC 2119 Keywords

The keywords **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**,
**SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL** are to be
interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).

### 1.2. Terms

| Term | Definition |
|------|-----------|
| **AGENTS.md** | The single canonical root file every agent reads first. Index + mandatory rules + quick commands. |
| **`docs/` hub** | Repository-root `docs/` folder holding the categorized markdown guide set. |
| **Per-module docs** | A `README.md` (and optional `docs/`) inside a major source folder (`app/{module}/`, `src/{module}/`). |
| **`.agents/`** | The cross-agent configuration directory (agents, commands, skills, docs, settings). |
| **Compatibility wrapper / symlink** | A tool-specific path (`CLAUDE.md`, `.claude/`) that points at the canonical artifact without duplicating it. |
| **Common 90%** | Structure identical across the audited repos; the normative standard. |
| **Repo-specific 10%** | Values an onboarding agent MUST reason about per repo (validation commands, paths, stack skills, example plans). |

---

## 2. AGENTS.md — The Canonical Root File

### 2.1. Existence and Format

- Every conformant repository **MUST** contain exactly one `AGENTS.md` at the repository root.
- `AGENTS.md` **MUST** be plain UTF-8 markdown and **MUST NOT** contain YAML frontmatter (maximally compatible across agent toolchains).
- `AGENTS.md` **SHOULD** be 150–500 lines. If it exceeds ~500 lines, content **SHOULD** move into `docs/` and be linked from the index.

`AGENTS.md` **MUST** serve three roles: an **index**, a set of **mandatory rules**, and a **quick commands** reference.

### 2.1.1. Budget enforcement — the lean index is a guarantee, not a hope

The budget above is enforced on what the harness produces:

- The `AGENTS.md` that onboarding — or any later harness-maintained update —
  generates **MUST** stay within the budget. When the reasoned content would
  exceed it, the agent **MUST** move the detail into the focused `docs/` guide
  (or the module/feature doc, §4) that owns it and link it from the index.
  The index **MUST** link every doc that received displaced content: nothing
  silently disappears, and the file stays a lean index by construction (§2.4.1).
- An existing handwritten `AGENTS.md` over the budget is **never silently
  rewritten**: onboarding and upgrade report the overweight with a concrete
  migration proposal — what moves where, which links get added — and apply it
  only with consent (`AGENT_PROTOCOL.md` §6; §3.5's non-destructive
  reconciliation). The proposal, not a forced edit, is the deliverable.
- The two limits of §2.4.1 bind here too: no constraint an agent needs to act
  safely is dropped to fit the budget, and the ceiling is never an excuse to
  hide required context — detail moves, it is not deleted.
- A conformance checker treats an over-budget `AGENTS.md` as an advisory
  (SHOULD): the line count is objective, authorship is not, and the **MUST**
  above binds the harness, not a checker's guess about who wrote the file.

### 2.2. Role 1 — Index (navigation)

`AGENTS.md` **MUST** contain a documentation index: a table linking every
`docs/` category file that exists, with one-line descriptions. It **MUST NOT**
link files that do not exist. For the **orchestrator hub** archetype it **MUST**
additionally link the sub-project navigation index (e.g. `repositories/README.md`)
and each sub-project's `AGENTS.md`. (Observed live: `api/AGENTS.md`
"Detailed Documentation" table; Core Hub `CLAUDE.md` "Documentation Navigation"
and "Project-Specific Documentation" tables.)

`AGENTS.md` **MUST** include an annotated repository-structure tree showing at
least two levels of depth (observed live in both `api/AGENTS.md` and the
Core Hub).

### 2.3. Role 2 — Mandatory Rules

`AGENTS.md` **MUST** contain a "Mandatory Rules" (or equivalently-named) section
stating, in normative language, the non-negotiable rules an agent **MUST** follow.
At minimum it **MUST** cover:

| Rule | Requirement |
|------|-------------|
| **Language** | All code, comments, and documentation **MUST** be in English. |
| **Conventional commits** | Commits **MUST** follow `type(scope): description`. |
| **Testing** | The repo's test pattern and coverage expectation **MUST** be stated, together with the validation rule an agent applies: gates are selected from the change's touched surface using the mapping documented in `TESTING_GUIDE.md` (§3.4), with the documented fallback to the full suite (`DWP_SPECIFICATION.md` §5.1). |
| **Error handling / logging** | The repo's consistent error and logging patterns **MUST** be stated. |
| **Repository boundaries** | Where the agent **MAY** and **MUST NOT** commit (load-bearing for the orchestrator hub, which **MUST** state that sub-project code is committed from inside each sub-repo, never from the hub root). |
| **Progress reporting** | The expectation that agents report progress after significant work, and the "never block work on reporting" rule (see `AGENT_PROTOCOL.md`). |

The test pattern, commit scopes, and validation commands themselves are part of
the **repo-specific 10%** (§7) and **MUST** be reasoned about per repo, not copied.

### 2.3.1. Working principles

`AGENTS.md` **SHOULD** carry compact working principles for autonomous,
precise, verified work. Onboarding and an authorized harness upgrade **MUST**
reconcile these principles using
[`../shared/working-principles.md`](../shared/working-principles.md): retain
equivalent instructions, add missing behaviors inline, and preserve explicit
repository preferences and authority boundaries. The ten behaviors are
ownership, resourcefulness, independent routine decisions, informed
escalation, concrete approval requests, recovery, scope discipline,
proportionate rigor, direct communication, and evidence-backed completion.

The principles apply to ordinary tasks and plans. They **MUST NOT** expand
authorization, override host permissions or plan gates, or convert analysis
into execution. Wording and headings **MAY** vary; semantic coverage is a judgment
check, not a keyword gate. Missing principles in an existing repository are
an advisory upgrade finding, not a new failure against its declared standard.
This addition leaves the umbrella standard and plan schemas unchanged.

### 2.4. Role 3 — Quick Commands

`AGENTS.md` **MUST** contain a quick-commands reference table for the most common
agent actions: install, test, lint, type-check, build, validate. Every command
**MUST** be runnable in the repo's development environment; commands that run only
in CI or only inside a container **MUST** be marked as such (observed: the Core
Hub flags `codecheck -f` as "must run INSIDE the Docker container"). Where the
repository supports it, the table **SHOULD** show the **scoped** variant next to
the full one (for example `pnpm test` / `pnpm test -- tests/unit/<module>`), each
clearly labeled, so an agent can tell which is which without opening the testing
guide. The exact commands are repo-specific (§7).

### 2.4.1. `AGENTS.md` as a compact entry point

`AGENTS.md` is the file every agent reads on every session, so its size is a
cost paid on every task. It **SHOULD** be a concise entry point: the mandatory
constraints (§2.3), the quick commands (§2.4), and **direct links** to the
focused guide that holds each detail (§3), rather than the details themselves.
Detailed, optional, or rarely needed guidance **SHOULD** live in the focused
`docs/` guide or per-module doc it belongs to, one link away. Two limits apply in
both directions: the file **MUST NOT** omit an invariant an agent needs in order
to act safely merely to be shorter, and this standard imposes **no** word cap
that would hide required context — brevity is achieved by linking, never by
dropping constraints.

### 2.5. CLAUDE.md → AGENTS.md

- The repository **MUST** provide a `CLAUDE.md` for Claude Code that resolves to `AGENTS.md` without duplicating content. It **MUST** be either:
  1. a **symlink** `CLAUDE.md → AGENTS.md` (RECOMMENDED; observed live in `repositories/agent-skill/CLAUDE.md` and the Core Hub), or
  2. a one-line **import wrapper** containing exactly `@AGENTS.md`.
- The symlink form **SHOULD** be used wherever the filesystem and git host support symlinks (all Dailybot repos do). The `@AGENTS.md` import form **MAY** be used where symlinks are unsupported (e.g. certain Windows checkouts or archive distributions).
- A `CLAUDE.md` that duplicates `AGENTS.md` content **MUST NOT** be used; `AGENTS.md` is the single source of truth.

> **Divergence from v1.** v1 listed `CLAUDE.md` among several "compatibility wrappers"
> and treated symlink-vs-`@import` as interchangeable prose. v2 makes the
> `CLAUDE.md → AGENTS.md` relationship a **MUST**, prefers the symlink, and pairs it
> with the new `.claude → .agents` *directory* symlink in §6 (`RECONCILIATION.md`
> divergence #4).

---

## 3. The `docs/` Categories

### 3.1. The Categorized Guide Set

A conformant repository **MUST** maintain a root-level `docs/` folder holding
categorized markdown guides. Guides **SHOULD NOT** carry YAML frontmatter (they are
evergreen reference, not lifecycle documents). The audit found 10 categories
common across the 6 repos; this standard adds an 11th — **`PRODUCT_SPEC.md`**,
the product/"why" layer — for **11 categories** total as the normative `docs/`
standard:

| # | Category file | Requirement | Purpose |
|---|---------------|-------------|---------|
| 0 | `PRODUCT_SPEC.md` | **MUST** | The product spec: the problem the repo solves, who it is for, its key capabilities/features, success criteria, and explicit non-goals — the **why** and **for whom**, not the **how**. Deliberately **non-technical**, high-value context. **Every repository is a product** — even a library, CLI, or internal tool: its consumers and their use cases are its product, and they deserve a non-technical spec. A library that omits this hides the very thing a new agent (or human) most needs to understand first. |
| 1 | `ARCHITECTURE.md` | **MUST** | System design, components, data flow, key decisions. |
| 2 | `STANDARDS.md` | **MUST** | Coding conventions, naming, import order, error/logging patterns, forbidden anti-patterns. |
| 3 | `TESTING_GUIDE.md` | **MUST** | Test framework, file-naming pattern, coverage expectation, the **full** and **verified scoped** commands, the source-to-test mapping and its blind spots, and the testing posture — the required content is specified in §3.4. **Where the repo has no test setup, this doc MUST instead specify the *proposed* setup reasoned from the stack** (see §3.3), clearly marked as proposed. |
| 4 | `DEVELOPMENT_COMMANDS.md` | **MUST** | Authoritative command reference (install/test/lint/type-check/build/run), expanding §2.4, including the scoped variants of test/lint/type-check where the toolchain supports them, each marked full or scoped. |
| 5 | `SECURITY.md` | **MUST** | Secrets handling, auth model, sensitive-data boundaries, what agents MUST NOT write to docs. |
| 6 | `PERFORMANCE.md` | **SHOULD** | Performance-critical paths, budgets, profiling guidance. |
| 7 | `AI_AGENT_ONBOARDING.md` | **MUST** | First-session checklist for an agent new to the repo. |
| 8 | `AI_AGENT_COLLAB.md` | **MUST** | How multiple agents/humans collaborate; handoff, ownership, conflict avoidance. |
| 9 | `PR_REVIEW_WORKFLOW.md` | **SHOULD** | How PRs are opened, reviewed, and merged in this repo. |
| 10 | `ECOSYSTEM_CONTEXT.md` | **SHOULD** (individual) / **MUST** (orchestrator hub & multi-repo members) | How this repo relates to sibling repos and the wider product. |

- The **MUST** categories (`PRODUCT_SPEC`, `ARCHITECTURE`, `STANDARDS`, `TESTING_GUIDE`, `DEVELOPMENT_COMMANDS`, `SECURITY`) plus `AI_AGENT_ONBOARDING` and `AI_AGENT_COLLAB` constitute the conformance floor for an AI-first repo.
- `PRODUCT_SPEC.md` is **non-technical by design** and **MUST NOT** be skipped on the grounds that "this repo is just a library/tool." If the repo genuinely has no end users, frame the product as its API/consumers: what it offers, to whom, and why they would choose it. Reason the content from the real repo (README, package description, public API, issues/roadmap) — never a generic stub.
- `SECURITY.md` **MUST NOT** be skipped on the grounds that "this repo has no secrets." Every repository has a security posture: how credentials and config are handled (even when the answer is "none — and none may be added"), what agents MUST NOT write into code or docs, input-handling expectations, and the sensitive-data boundaries of its domain. Reason it from the real repo (env handling, CI secrets, auth code, data models) — never a generic stub. The Final Review (`DWP_SPECIFICATION.md` §6.1) keeps this file current: every completed plan verifies it still reflects reality.
- A repository **MAY** add domain-specific guides beyond these 11 (e.g. `API_REFERENCE.md`, `DATABASE_SCHEMA.md`, `LOGGING_BEST_PRACTICES.md`, `REDIS_CACHING_BEST_PRACTICES.md`) when the stack warrants. Whether a given domain guide is warranted is part of the **repo-specific 10%** (§7). (All four examples observed live in `api/docs/`.)
- A guide that would fall below ~30 lines **SHOULD** be merged into a sibling; a guide above ~700 lines **SHOULD** be split into a subfolder.

> **Divergence from v1.** v1 required only 5 `docs/` files at "Silver"
> (`README`, `ARCHITECTURE`, `SETUP`, `STANDARDS`, `TROUBLESHOOTING`) and listed
> `SECURITY`/`AI_AGENT_ONBOARDING`/`ECOSYSTEM_CONTEXT` as merely "recommended". v2
> elevates a **10-category set audited from the real repos**, makes 7 of them
> **MUST**, and renames `SETUP.md`→`DEVELOPMENT_COMMANDS.md` to match observed
> practice (`RECONCILIATION.md` §"Specs"). `SETUP`/`TROUBLESHOOTING` content is
> not lost: it folds into `DEVELOPMENT_COMMANDS.md` and `AI_AGENT_ONBOARDING.md`.
>
> **Added: `PRODUCT_SPEC.md` (category 0, MUST).** The audited 10-category set was
> entirely engineering/process documentation — it captured the *how* but never the
> *why*. This standard adds `PRODUCT_SPEC.md` as a required, deliberately
> **non-technical** product/purpose document so an agent (or human) learns what the
> repo is *for* and *for whom* before diving into its mechanics. It is a **MUST for
> every archetype, including libraries, CLIs, and internal tools** — every
> repository is a product; the spec frames its users/consumers and the value it
> delivers.

### 3.2. `docs/README.md` Master Index

A repository **SHOULD** provide `docs/README.md` as the master index of the
`docs/` hub: a one-paragraph scope statement, a table linking every guide with a
one-line description, and a "start here" pointer for common tasks. It **MUST** be
present in the orchestrator hub archetype (the hub's `docs/` is large enough that
navigation without an index degrades agent performance).

### 3.3. The Testing & Validation Toolchain Is Essential (discover, or propose)

A repository's **test, lint, type-check, and format** toolchain is the backbone of
the validation gates that make Deep Work Plans reliable (`DWP_SPECIFICATION.md`
§5.1, §5.1.1). It is therefore **not** part of the optional repo-specific surface to
record "if present" — establishing it is a conformance concern:

- An onboarding agent **MUST** discover how the repo validates code — its real
  test runner, test file convention, coverage expectation, and its lint /
  type-check / format commands — by inspecting manifests, config, and CI, and
  record the **concrete** values in `TESTING_GUIDE.md`, `DEVELOPMENT_COMMANDS.md`,
  and the `AGENTS.md` Mandatory Rules + Quick Commands (§2.3, §2.4).
- Where the repository has **no** testing or linting setup, the agent **MUST NOT**
  leave `TESTING_GUIDE.md` empty or write "no tests". It **MUST propose** a setup
  fit to the detected stack — a recommended framework and runner, a test
  file-naming convention, where tests live, a sensible initial coverage target,
  and the lint / type-check / format tooling — document that proposal as the
  **target** in `TESTING_GUIDE.md`, and surface it to the developer. It **SHOULD**
  scaffold a minimal runnable baseline (the test/lint scripts plus at least one
  real smoke test) when doing so is non-destructive and the developer consents.
- The proposal **MUST** be reasoned per repo (§7), proportional to the project's
  size and maturity, and **MUST NOT** be a generic stub — a tiny CLI does not need
  the same suite as a service, but every repo deserves a defined way to validate
  its behavior.

A repository whose `TESTING_GUIDE.md` neither describes a real setup nor specifies
a concrete proposed one is **not** AI-first conformant: agents would have no
objective validation gate to run.

When the toolchain exists and is runnable, the onboarding agent **MUST** execute
at least one **real scoped invocation** against an actual path of the repository
and record the evidence (the command, its working directory, and the selected or
executed test count) in `TESTING_GUIDE.md` per §3.4. When the toolchain is absent
or cannot run in the onboarding environment, the guide **MUST** say so and
present the commands as **proposed** — never as verified, and never fabricated.

### 3.4. `TESTING_GUIDE.md` — Required Content

`TESTING_GUIDE.md` is the document a Deep Work Plan reads to turn a task's
Touched Surface (`DWP_SPECIFICATION.md` §5.0.2) into a validation gate
(`DWP_SPECIFICATION.md` §5.1). It **MUST** therefore contain the following,
each reasoned from the real repository (§7):

#### 3.4.1. Commands

- The **full-suite** command(s) for tests, and the full commands for lint, format,
  and type-check.
- The **scoped invocation pattern(s)** — by file, by module or directory, by
  package (in a monorepo), and by marker or name filter where the runner supports
  it — each with **at least one concrete example from this repository**, the
  **working directory** it runs from, the **tool version** where flag behavior
  depends on it, and the **expected evidence** a correct run produces (for
  example "selects 12 tests", "reports the file under `collected`"). A pattern
  copied from documentation without a repository example is not sufficient.
- Scoped **lint / format / type-check** commands **only where the toolchain
  genuinely supports scoping**; where it does not, or where a project-wide check
  is the cheaper option, the guide **MUST** say so plainly rather than describe a
  scoped form that does not exist.
- Where a cheap complete command is the real trade-off (a suite that finishes in
  seconds), the guide **SHOULD** recommend it over elaborate selection.

#### 3.4.2. Mapping, consumers, and blind spots

- The **source-to-test mapping rule**: how a changed path maps to the tests that
  cover it (co-located files, a mirrored tree, a naming convention, markers, or
  a package boundary).
- The **dependent-consumer policy**: how an agent finds the tests of modules that
  depend on a changed module — an affected-tests tool (`--changed`,
  `--findRelatedTests`, `testmon`, a monorepo task graph), an import graph, or
  a documented list of consumers — and what to do when none is available.
- The **known blind spots** of that mapping and tooling: dynamic loading,
  templates, fixtures, generated inputs, configuration, migrations, and any
  repository-specific case where a change is invisible to static analysis.
- The **escalation paths**: which paths or packages are treated as shared or core
  (a change there widens validation to consumers or to the full suite), and which
  configuration, schema, dependency, or build/test-toolchain changes always
  trigger the full run.
- An **explicit fallback statement** for cases scoping cannot cover: "run
  `<full command>`". An agent that cannot derive a sound scoped gate falls back
  to this by rule (`DWP_SPECIFICATION.md` §5.1.b), never by guesswork.

#### 3.4.3. Testing posture

- **Where each layer lives**: the directories or naming that distinguish unit,
  integration, and end-to-end tests, and how each layer is run.
- **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 without asserting internal
  call sequences (`DWP_SPECIFICATION.md` §5.1.1).
- **Real-seam integration**: which seams (contracts, persistence, routing,
  serialization, auth, framework wiring) carry integration or contract tests,
  and the expectation that a task changing such a seam adds them.
- **Useful end-to-end** coverage: few, high-value flows, and how they run.
- **Deterministic fixtures** and **meaningful assertions** as expectations.
- A clear line between the repository's **current capabilities** and any
  **proposed** setup (§3.3): the two **MUST NOT** be blended so that a reader
  mistakes a proposal for a verified command.

The posture is a default strategy, not a fixed ratio or a speed target; the guide
**MUST NOT** impose test-count quotas or percentages the repository does not
actually enforce.

### 3.5. Adoption — Install, Onboard, Upgrade

Three different actions are easily conflated; a repository's documentation and
the onboarding flow **MUST** keep them distinct:

| Action | What it provides | What it does **not** provide |
|---|---|---|
| **Installing the skill** | The methodology's instructions, on the machine or in the repository. | Any knowledge of *this* repository: no verified test mapping, no context, no permissions. |
| **Onboarding the repository** | The context (§2–§5), the verified commands and mapping (§3.3–§3.4), and the harness a plan needs. | — |
| **Upgrading an existing setup** | A **targeted, non-destructive, idempotent reconciliation** that adds what a newer standard requires (for example §3.4 content) to a repository onboarded under an earlier one. | A rewrite: handwritten rules, custom skills, existing commands and in-flight plans are preserved. |

- **Adoption acceptance check.** After any of the three, a lightweight check
  **SHOULD** confirm: the installed skill is locatable (its router `SKILL.md` and
  version); its essential local links resolve; the repository has a **real** test
  command or an honest, documented absence (§3.3); and the next useful action is
  stated (onboard, upgrade, or create a plan).
- **Non-destructive reconciliation.** Re-running onboarding on a repository that
  already has `AGENTS.md`, `docs/`, or `.agents/` **MUST** reconcile rather than
  overwrite: add missing sections, update stale generated content, and leave
  handwritten content, custom skills, and unrelated files intact; ask before
  replacing anything (`AGENT_PROTOCOL.md` §6). Repeating the reconciliation
  **MUST** produce no further change (idempotent). This includes working
  principles (§2.3.1), even when the declared standard is already current;
  equivalent handwritten rules satisfy the requirement without rewriting.
  The reconciliation **MUST**
  report, per file, what it added or changed.
- **Recorded provenance.** A repository that adopts this standard **SHOULD**
  record it — a line such as
  `DWP standard: 7.0.0 (onboarded YYYY-MM-DD; upgraded YYYY-MM-DD; skill x.y.z)`
  in `AGENTS.md` or `docs/README.md` — so a checker and a future agent can tell
  which standard the repository declares.

  The version in that line is the **umbrella DWP standard** implemented by the
  installed pack, not the version of this retained v5 base document. The v6
  extension documents and their v7 additions in this directory define the
  current plan lifecycle.
  A conformance checker reads the declaration against the standard it
  implements and rejects a newer one. The standard's series are 2.x, 4.x,
  5.x and 6.x (historical) and 7.x (current — there is no 3.x); the skill package
  `version:` and the `/v2.json` and `/v5.json`
  schema URLs are two further, separate series, never compared against this
  line.
- **Legacy versus declared.** A conformance checker **MUST** distinguish a
  repository onboarded under an earlier version (no §3.4 content, no declaration)
  from a repository that declares this version and lacks a **MUST**: the former
  receives a **finding** that names the upgrade path; the latter **fails**. A
  declared requirement is never silently waived. Judgments about the *quality* of
  a mapping (is the consumer policy sound?) are disclosed as manual review items,
  not encoded as automatic passes.

---

> **Divergence from 2.1.0.** 2.3.0 makes the testing guide's content normative
> (§3.4: full and verified scoped commands, mapping, consumers, blind spots,
> escalation, fallback, posture), requires one real scoped invocation at
> onboarding (§3.3), states `AGENTS.md`'s compact-entry-point role (§2.4.1),
> distinguishes install / onboard / upgrade with non-destructive, idempotent
> reconciliation and recorded provenance (§3.5), and separates legacy findings
> from declared-standard failures. Repositories onboarded under 2.1.0 remain
> conformant and receive an upgrade finding.

## 4. Per-Module Nested Docs

This section formalizes the per-module documentation tier observed across the
audited repos (e.g. `api/app/integrations/docs/` with `README.md`,
`MODELS.md`, `API.md`, `SIGNALS.md`, `STRUCTURE.md`, `TASKS.md`, plus
`app/{module}/README.md` in every major module).

- Each **major** source module (a folder under `app/`, `src/`, or the stack
  equivalent that represents a distinct feature or bounded concern) **MUST** carry
  a `README.md` describing that module: its purpose, key files, and how it fits the
  system.
- A module that is **complex or high-velocity** (3+ interconnected concerns, or
  frequently modified) **SHOULD** additionally carry a `docs/` subfolder with
  deeper guides (models, services, signals, tasks, etc.), entered via a
  `README.md`.
- A trivial or stable module **MAY** omit the `docs/` subfolder; a single
  `README.md` is sufficient.
- Per-module docs **MUST** be linked from the module's own `README.md`, and the
  most significant ones **SHOULD** be surfaced in the root `AGENTS.md` index
  (observed: `api/AGENTS.md` links
  `app/integrations/docs/features/AI_SERVICES.md`).

Which modules qualify as "major" or "complex" is part of the **repo-specific 10%**
(§7) and **MUST** be reasoned about per repo.

### 4.1. The feature tier — per-feature `docs/` for major capability areas

Above the per-module tier sits a **feature tier**: a **major feature or
capability area** — bigger than one module — gets its own `docs/` folder next
to its code, entered via its own `README.md`, holding the area's architecture
decisions, contracts, and runbooks.

- An area qualifies when **any** of these triggers fires (heuristics, not
  bureaucracy — the judgment stays with the per-repo reasoning, §7):
  - it **spans 2+ major modules** — a capability several modules cooperate to
    provide (e.g. a domain model shared across services);
  - it **owns a sub-app or subsystem directory** — a self-contained
    application or subsystem folder inside the repo (observed shape:
    `app/{domain}/`, or a top-level sub-app such as `mailtron/`);
  - it **carries its own contracts** — an API surface, event or schema
    contracts, protocol definitions — that multiple consumers depend on.
- Once an area is recorded as major, its feature `docs/` **SHOULD** exist; the
  most significant entries **SHOULD** be linked from the READMEs of the
  modules the area spans and surfaced in the root `AGENTS.md` index, exactly
  like per-module docs. An area deliberately left undocumented carries a
  recorded reason — a decision, not an oversight.
- The feature tier complements the per-module tier, never replaces it: a
  module inside a feature area still carries its own `README.md` (§4).

> **Observed input, adapted by reasoning.** This tier generalizes the audited
> `api` shape — a flat root `docs/` hub plus nested per-area `docs/`
> (e.g. `app/domain/docs/`, `app/mcp/docs/`, and the sub-app `mailtron/docs/`,
> each entered via a `README.md`). Reason the structure from the target
> repo's real feature areas (§7); never copy another repo's folder layout
> verbatim.

> **Divergence from v1.** v1 shipped only a per-module *`AGENTS.md`* template and
> treated nested docs as an optional "Tier 3 / Platinum" extra. v2 makes a per-major-module
> `README.md` a **MUST** and a module `docs/` subfolder a **SHOULD** for complex
> modules, matching the audited 6-repo reality (`RECONCILIATION.md` divergence #6).

---

## 5. The `.agents/` Layout

A conformant repository **MUST** maintain a `.agents/` directory as the canonical,
**cross-agent** configuration home. It **MUST** contain:

| Path | Requirement | Contents |
|------|-------------|----------|
| `.agents/agents/` | **MUST** | Role-based subagent definitions (e.g. `doc-writer.md`, `researcher.md`, `planner.md`). Native to Claude Code; readable as personas by other agents. |
| `.agents/commands/` | **MUST** | Slash commands as markdown procedure files. The five DWP commands (`dwp-create.md`, `dwp-execute.md`, `dwp-refine.md`, `dwp-resume.md`, `dwp-status.md`) **MUST** be present and **SHOULD** be thin delegators that route to the installed `deepworkplan` skill's matching sub-skill (single source of truth, no copied flow). Invoked via `/` by Claude Code and `#`/plain-text by other agents (see `AGENT_PROTOCOL.md`). |
| `.agents/skills/` | **MUST** | Installed skill packs, each a self-contained folder with a `SKILL.md` router. The DWP system itself ships here as `.agents/skills/deepworkplan/`. |
| `.agents/docs/` | **MUST** | Cross-agent catalog docs: a skills/agents catalog and a `COMMANDS_REFERENCE.md` mapping each command to its procedure file. |
| `.agents/settings.json` | **MUST** | Harness configuration (hooks, permissions, team-agent config). Claude-Code-specific but lives here for a unified location; other agents ignore it. |
| `.agents/settings.local.json` | **MAY** | Local, uncommitted-style overrides. |
| `.agents/README.md` | **SHOULD** | Entry point describing the directory. |

- Subagents in `.agents/agents/` **SHOULD** be **role-based** (a documentation
  writer, a researcher, a planner) and **MUST** be described well enough that a
  non-Claude agent can read them as personas.
- The command set **MUST** include the five DWP commands (`create`, `execute`,
  `refine`, `resume`, `status`) once the deepworkplan skill is installed; it **MAY**
  include repo-specific commands.
- The set of stack-specific skills installed under `.agents/skills/` is part of the
  **repo-specific 10%** (§7).

> **Divergence from v1.** The v1 spec did not codify a `.agents/` directory at all;
> agent config was scattered per-tool (`.claude/commands/`, `.cursor/rules/`,
> `.codex/skills/`). v2 makes `.agents/` the **single canonical, cross-agent home**,
> matching the live Core Hub and `repositories/agent-skill` layout
> (`RECONCILIATION.md` divergences #1 and #4; `ORCHESTRATOR_MANIFEST.md` key decisions).

### 2.6. Working directories (gitignored)

A conformant repo keeps two gitignored working areas at its root, serving
different purposes. Both **MUST** be gitignored (tracking only an index
`README.md`/`.gitkeep`).

| Directory | Requirement | Purpose |
|-----------|-------------|---------|
| `.dwp/` | **MUST** (once the DWP skill is installed) | **Structured** Deep Work Plan output — `.dwp/plans/`. Owned by the DWP flows. See `DWP_SPECIFICATION.md`. |
| `tmp/` | **SHOULD** | **Unstructured** repo-root scratch space for ephemeral agent/developer work: exploratory output, data exports, inter-agent prompt handoffs, throwaway experiments. Agents **SHOULD** write *non-plan* temporary/throwaway artifacts here rather than polluting the source tree, `docs/`, or `.dwp/`. Output produced **about a plan** is the exception and goes in that plan's own `analysis_results/` (`DWP_SPECIFICATION.md` §5), never in `tmp/` and never at the repository root. |

The distinction matters: `.dwp/` is the methodology's **structured** output (plans an agent can resume), while `tmp/` is **freeform** scratch that can be deleted at any time. The test is *ownership, not lifetime*: a gate log, an audit report or a scratch measurement produced **while executing a plan** is that plan's evidence — a later session retrieves it by pointer — so it belongs in `.dwp/plans/<plan>/analysis_results/` even though it is temporary. `tmp/` is for work no plan will ever read back. Common `tmp/` sub-uses observed across the audited repos: `tmp/scratch/`, `tmp/exports/`, `tmp/{tool}_prompts/`. An onboarding agent **SHOULD** create `tmp/` (with a `.gitkeep`) and add it to `.gitignore`, and **SHOULD** note the convention in `AGENTS.md`.

---

## 6. Agent-Facing Directory Symlinks

A conformant repository **MUST** provide directory-level symlinks so that each
agent finds its expected configuration path while `.agents/` remains the single
canonical store:

- **`.claude → .agents`** (for Claude Code) — **MUST**. Claude Code reads
  configuration from `.claude/`; this symlink satisfies that expectation.
  (Observed live: the Core Hub's `.claude → .agents`.)
- **`.cursor → .agents`** (for Cursor) — **MUST**. Cursor reads configuration
  from `.cursor/`; this symlink satisfies that expectation.

Both symlinks follow the same principle as the file-level `CLAUDE.md → AGENTS.md`
convention (§2.5): the canonical artifact carries the agent-neutral name
(`.agents/`); agent-facing names are symlinks into it.

- `.agents/` content **MUST** be authored as cross-agent (consumed by Claude Code,
  Cursor, Codex, Gemini, Copilot, Antigravity through their own conventions per
  `AGENT_PROTOCOL.md`); neither the `.claude` nor `.cursor` symlink **MUST NOT**
  introduce agent-specific divergence in shared files.
- Where symlinks are unsupported by the host, the repository **MAY** substitute a
  tool-native pointer, but **MUST** keep `.agents/` canonical and document the
  substitution.

> **Divergence from v1.** v1 documented only the *file* symlink
> `CLAUDE.md → AGENTS.md` (in the Claude adapter). The *directory* symlink
> `.claude → .agents` is **net-new in v2** (`RECONCILIATION.md` divergence #4,
> idea #1). The `.cursor → .agents` symlink is **net-new in this version**,
> extending the same principle to Cursor.

---

## 7. The Repo-Specific 10% — "Reason Per Repo"

The following values are **repo-specific** and **MUST NOT** be copied verbatim from
this standard or from another repo. An onboarding agent (`AGENT_PROTOCOL.md`)
**MUST** reason about each by inspecting the target repo's stack, config, and CI:

| Repo-specific value | How the agent reasons about it |
|---------------------|--------------------------------|
| **Validation commands** | Derive `test`/`lint`/`type-check`/`build`/`validate` from package manager, lockfiles, CI config (e.g. `codecheck -f` in Docker for Django; `eslint:check && test` for Node; `astro:check` for Astro). **If the repo has no test/lint commands, propose stack-appropriate ones (§3.3) rather than recording their absence.** |
| **Scoped invocation and mapping** | Derive the scoped test/lint/type-check patterns from the runner's real capabilities and the repository's layout; verify at least one against a real path (§3.3); document the source-to-test mapping, consumer policy, blind spots, escalation paths, and fallback (§3.4). Never present an example from another repository or from tool documentation as a verified command. |
| **File paths & structure** | Derive module layout from the actual source tree (`app/` vs `src/` vs `pages/`). |
| **Test file naming** | Derive from existing tests (`*_test.py`, `*.spec.ts`, `*.test.ts`). |
| **Stack-specific skills** | Decide which `.agents/skills/` to install based on the stack and the repo's needs. |
| **Example plans / domain docs** | Decide which optional `docs/` guides and `.dwp/` examples are warranted. |
| **Commit scopes** | Derive valid `scope` values from the repo's domains. |

The agent **MUST** record, in the generated `AGENTS.md` and `docs/`, the *concrete*
resolved values for the target repo — never the placeholder or another repo's value.

---

## 8. Archetype Notes (cross-reference)

Both archetypes from `ARCHETYPES.md` follow §§2–7. The **individual repo** (common
case) is the default; an onboarding agent **MUST** assume it unless the repo is
clearly a hub. The **orchestrator hub** **MUST** additionally provide: the
sub-project navigation index (§2.2), `ECOSYSTEM_CONTEXT.md` and a cross-project
standards guide (§3.1), repository-boundary rules in `AGENTS.md` (§2.3), and the
orchestrator DWP capability (`DWP_SPECIFICATION.md` §8). See `ARCHETYPES.md` for
the classification heuristic and the full onboarding-difference matrix.

---

## 9. Conformance (informative)

The v1 Bronze/Silver/Gold/Platinum badge ladder is retained as an **informative**
self-assessment aid, not a normative requirement. A repository is **AI-first
conformant** when it satisfies every **MUST** in §§2–7. For a repository that declares 2.3.0 or later, the floor includes the
`TESTING_GUIDE.md` content of §3.4; a repository onboarded under an earlier
version that lacks it receives an upgrade finding (§3.5), not a failure. The
optional ladder maps,
roughly: Bronze = §2 only; Silver = §2 + the six MUST `docs/` categories
(`PRODUCT_SPEC`, `ARCHITECTURE`, `STANDARDS`, `TESTING_GUIDE`,
`DEVELOPMENT_COMMANDS`, `SECURITY`); Gold =
+ remaining MUST categories + `.agents/` + symlinks; Platinum = + per-module docs
for all complex modules (§4).

---

## 10. References

- [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119)
- [agents.md](https://agents.md) — the cross-tool AGENTS.md convention
- `DWP_SPECIFICATION.md`, `AGENT_PROTOCOL.md`, `ARCHETYPES.md`, `ADDONS.md` — companion specs
- `../RECONCILIATION.md`, `../ARTIFACT_INVENTORY.md` — Task 1 carry-forward decisions
- Audited live references: `repositories/api/AGENTS.md`, `repositories/agent-skill/` (`.agents/` + skill-pack + `CLAUDE.md`/`.claude` symlinks), the Core Hub `CLAUDE.md`/`.claude → .agents`

---

*Part of the DeepWorkPlan methodology v5.0.0, MIT License, by [Dailybot](https://dailybot.com) / dailybotops.*
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall