AGENTS.md — Documentation for AI Agents working on this repo

Purpose: Single source of truth for any AI coding assistant (Claude Code, Cursor AI, OpenAI Codex, Gemini CLI, GitHub Copilot, others) that edits this repository. This file is for contributors, not for end users of the skill.

[!IMPORTANT] This file is NOT installed. When users install the skill (via npx skills add, openclaw skills install, or git clone + setup.sh), only the contents of skills/deepworkplan/ ship to their machine. Anything outside that directory — including this file, .github/, tests/, scripts/, docs/, README.md, LICENSE, etc. — is repo-development infrastructure that lives only on GitHub and on contributors' machines.

CLAUDE.md at the repo root is a symlink to this file so Claude Code reads the same instructions other agents do.

Working principles

Work with autonomy, ownership, and sound judgment. Pursue excellence through correctness, clarity, simplicity, and verified completion.

• Own the outcome. Carry authorized work through investigation, execution, and appropriate validation. Continue until the requested outcome is complete or a concrete blocker prevents further progress.
• Be resourceful before asking. Inspect available code, documentation, tools, and prior decisions. Resolve questions you can answer through reasonable investigation instead of transferring that work to the user.
• Make routine decisions independently. Choose sensible approaches within the authorized scope; take the recommended option and record consequential decisions. Avoid confirmation requests for routine or authorized steps.
• Ask when judgment or authorization is missing. Escalate only what is critical, and name its class (AGENT_PROTOCOL §7.5: approval, consent screen, ambiguity, quality conflict, damage, terms, capacity). Bring the investigation, relevant options, and your recommendation.
• Make approvals concrete. Complete authorized preparation before asking for approval. Present a reviewable result and identify the action requiring approval and why it requires it.
• Work through obstacles. Investigate failures and attempt reasonable recovery within scope. Continue independent authorized work when possible. Respect applicable stop conditions; escalate when progress requires user input or an external change.
• Respect intent and scope. Analysis requests remain analysis. Propose broader improvements separately unless already authorized. Preserve the user's existing work, decisions, and repository-specific approval rules.
• Apply proportionate rigor. Address underlying causes and favor maintainable solutions. Match investigation, validation, and polish to the task's impact. Avoid unnecessary complexity and unrelated changes.
• Communicate directly and precisely. Lead with the result or decision. Explain consequential tradeoffs concisely. Distinguish verified facts, assumptions, and unresolved uncertainty.
• Verify before declaring completion. Review the result against the request, perform appropriate checks, and fix issues within scope. Report what was validated and any remaining limitations. Never claim actions, checks, or outcomes that did not occur.

Detailed Documentation

Project Overview

This repository is the official DeepWorkPlan agent skill pack, maintained by Dailybot and distributed via skills.sh, OpenClaw, and direct git clone. It is a Markdown-first skill: it teaches AI coding agents how to (1) turn any repository AI-first — generating an adapted AGENTS.md, docs/, per-module docs, .agents/, and the .claude → .agents / .cursor → .agents symlinks — and (2) run structured multi-task Deep Work Plans whose outputs land in a gitignored .dwp/ directory. The skill follows the Open Agent Skills standard.

Stack: Markdown + Bash + Python 3.9 standard library. No application runtime or compiled artifacts. The runtime includes SKILL.md instructions, context.sh for repo and .dwp/ resolution, plan_paths.py for plan ID allocation and selection, and the v6 state helpers. setup.sh is the repository-root symlink installer. There is no standalone application CLI, HTTP API, auth flow, or network call.

Project Structure

deepworkplan-skill/
├── AGENTS.md, CLAUDE.md (symlink)              ← this file (NOT installed)
├── README.md                                   ← public README on GitHub (NOT installed)
├── assets/                                      ← README brand marks (NOT installed)
├── LICENSE, SECURITY.md, CHANGELOG.md          ← repo metadata (NOT installed)
├── PUBLISHING.md                               ← launch playbook (NOT installed)
├── setup.sh                                    ← symlink installer for non-skills.sh users (NOT installed)
├── .gitignore                                  ← repo hygiene (NOT installed)
├── CONTRIBUTING.md                             ← human contributor guide (NOT installed)
├── .vscode_example/                            ← shared editor settings template (NOT installed)
├── .github/
│   ├── workflows/auto-release.yml              ← conventional-commit auto-release + addon dogfood (NOT installed)
│   ├── workflows/prerelease.yml                ← manual X.Y.Z-beta.N pre-release, never latest (NOT installed)
│   ├── workflows/ci.yml                        ← frontmatter + shellcheck + bats + smoke + public hygiene (NOT installed)
│   ├── docs/WORKFLOWS.md                       ← per-workflow reference (Trigger / Jobs / Gate / Failures) (NOT installed)
│   ├── PULL_REQUEST_TEMPLATE.md                ← PR checklist (NOT installed)
│   ├── ISSUE_TEMPLATE/ · CODEOWNERS · dependabot.yml ← issue forms + config.yml, owners, Actions updates (NOT installed)
│   └── markdown-link-check.json                ← link-check config (NOT installed)
├── .agents/skills/                             ← THREE vendored dogfood copies (NOT installed on end-user machines)
│   ├── deepworkplan/                           ← byte-identical dogfood copy of this skill (scripts/refresh-dogfood-skill.sh; auto-release re-syncs it in the release commit)
│   ├── dailybot/                               ← DailybotHQ/agent-skill — auto-refreshed on release
│   └── ai-diff-reviewer/                       ← DailybotHQ/ai-diff-reviewer — auto-refreshed on release
├── skills-lock.json                            ← pinned versions/hashes for the vendored skills (NOT installed)
├── .review/extension.md                        ← repo-tailored severity overrides read by both local skill + CI Action
├── scripts/
│   ├── validate-frontmatter.py                 ← schema check on every SKILL.md (NOT installed)
│   ├── check-public-hygiene.sh                 ← CI: no private names, personal paths or secrets (NOT installed)
│   └── smoke-ecosystem-pins.sh                 ← release: installs each pinned product, checks its interface (NOT installed)
├── tests/                                      ← bats-core tests: context-sh.bats, setup-sh.bats (NOT installed)
├── docs/                                       ← contributor docs: DESIGN, INSTALLATION, OPENCLAW, SUB_SKILL_GUIDE (NOT installed)
├── tmp/                                        ← gitignored scratch space (only .gitkeep tracked; NOT installed)
└── skills/deepworkplan/                        ← THE INSTALLED ARTIFACT — only this ships
    ├── SKILL.md                                ← router (version source of truth)
    ├── spec/                                   ← retained v5 base, v6 extensions, v7 additions (ships)
    ├── shared/                                 ← context.sh, plan_paths.py (numbered plan allocation), dwp-paths.md, adaptation.md, troubleshooting.md, install-verification.md, update-state.py, state_contract.py, finalize_plan.py, config.py (.dwp/config.json + addon registry)
    ├── create/SKILL.md                         ← create a Deep Work Plan
    ├── execute/SKILL.md                        ← execute a plan task-by-task
    ├── refine/SKILL.md                         ← modify a plan / promote Lite to Full
    ├── resume/SKILL.md                         ← resume an interrupted plan
    ├── status/SKILL.md                         ← report plan status
    ├── verify/SKILL.md                         ← verify repo/plan conformance (read-only)
    ├── onboard/SKILL.md                        ← make any repo AI-first (+ presets/)
    ├── author/SKILL.md                         ← author/update skills, agents, commands (+ templates/)
    ├── guide/GUIDE.md                          ← methodology guide
    ├── examples/                               ← plan + orchestrator templates
    └── addons/                                 ← opt-in addons (each with its own SKILL.md + INTEGRATION.md)
        ├── devcontainer/                       ← thin integrator of devcontainer-kit (dck)
        ├── agentkit/ · herdr/ · vim/           ← thin integrators of coding-agents-kit, herdr-peers, deepworkplan-vim
        ├── dailybot/                           ← Dailybot standup reporting for plan lifecycle events
        ├── ai-diff-reviewer/                   ← AI Diff Reviewer for PR reviews (defers to upstream skill + Action)
        ├── dependency-upgrade/                 ← safe, batched, revertible dependency upgrades
        └── design-system/                      ← DESIGN.md generator for UI-having repos

The hard rule: anything you put outside skills/deepworkplan/ is invisible to the runtime agent. Use that to keep this repo discoverable and auditable on GitHub without polluting the skill itself.

Quick Commands

# Validate every SKILL.md frontmatter (kebab-case name, quoted SemVer, etc.):
python3 scripts/validate-frontmatter.py

# Lint the shell scripts we ship + the installer:
shellcheck setup.sh skills/deepworkplan/shared/context.sh scripts/*.sh

# Run the bats-core unit tests (context.sh + setup.sh):
bats tests/

# Smoke-test setup.sh against a throwaway HOME (won't touch ~/.claude):
HOME="$(mktemp -d)" ./setup.sh --host claude

# Smoke-test context.sh (should emit single-line JSON):
bash skills/deepworkplan/shared/context.sh

CRITICAL: Mandatory Rules

1. English only

All code, comments, documentation, and commit messages MUST be in English. This is a public open-source repo consumed worldwide.

2. The runtime artifact is skills/deepworkplan/ — keep it pure

If you create a new file or directory, ask: "does this need to be on the end user's disk for the skill to work at runtime?"

• Yes → it lives under skills/deepworkplan/
• No → it lives at the repo root or under .github/, tests/, scripts/, docs/

Never reach out of skills/deepworkplan/ for anything at runtime — every runtime file must be self-contained inside that directory because that's what skills.sh ships. The frontmatter validator, the CI workflow, and the auto-release workflow all depend on this boundary holding.

3. SKILL.md frontmatter conventions

Every SKILL.md MUST have YAML frontmatter with at least:

---
name: deepworkplan-<thing>       # kebab-case, never snake_case (deepworkplan_thing) or camelCase
description: <one paragraph>     # used by skills.sh + every agent harness for relevance scoring
version: "2.0.0"                 # SemVer, quoted to keep it a string
documentation_url: https://deepworkplan.com  # NEVER use `homepage:` (legacy, dangerous)
user-invocable: true|false       # whether `/<name>` becomes a slash command
allowed-tools: Bash, Read, Grep, Glob, Edit, Write
---

The router skill is named deepworkplan; sub-skills are deepworkplan-create, deepworkplan-execute, deepworkplan-refine, deepworkplan-resume, deepworkplan-status, deepworkplan-verify, deepworkplan-onboard, deepworkplan-author, deepworkplan-upgrade, and the addons are named deepworkplan-addon-<name> (for example deepworkplan-addon-devcontainer). The documentation_url field replaces the legacy homepage because some agent harnesses interpret homepage as a re-fetch source. validate-frontmatter.py fails CI if any SKILL.md uses the old key, is not kebab-case, does not start with deepworkplan, or has an unquoted version.

4. Versioning is automatic — write good commits

You do not edit version: fields, CHANGELOG.md, or git tags by hand. The auto-release.yml workflow runs on every merge to main and:

1. Reads the current version from the router skills/deepworkplan/SKILL.md frontmatter (single source of truth).
2. Looks at commits merged since the last stable vX.Y.Z tag (pre-releases ignored).
3. Decides the bump level:

• feat(scope)!: or BREAKING CHANGE: in body → MAJOR
• feat(scope): → MINOR
• everything else (fix:, chore:, no prefix, etc.) → PATCH

4. Bumps version: in all SKILL.md files in sync (router + nine sub-skills

• addons), re-syncs the dogfood mirror and its lock hash, prepends a section to CHANGELOG.md, commits as chore(release): X.Y.Z [skip ci], tags vX.Y.Z, and pushes.

5. Smoke-tests the just-published tag — runs npx skills add https://github.com/DailybotHQ/deepworkplan-skill/tree/vX.Y.Z into a temp directory and asserts the installed version: matches (never over the dogfood copy).
6. Dogfoods addon skills only — refreshes .agents/skills/dailybot/ and .agents/skills/ai-diff-reviewer/ to their latest upstream tags (see "Vendored agent skills" below).
7. Creates a GitHub Release with auto-generated notes and the SHA256SUMS provenance artifact attached.

To refresh the in-repo deepworkplan dogfood after changing skills/deepworkplan/, run bash scripts/refresh-dogfood-skill.sh, review the diff, and commit it on a PR; the release re-syncs only its own stamp.

What this means for you:

• Write meaningful commit messages with the right <type>(<scope>): prefix. The workflow reads them.
• A bug-fix-only PR → PATCH automatically. A new sub-skill or addon → MINOR (use feat(...):). A removed slash command, renamed name:, or changed .dwp/ convention → MAJOR (use feat(...)!: and explain in the PR body).
• Don't touch CHANGELOG.md or version: fields manually. The bot owns them (a hand edit is overwritten or duplicated); hand-written release notes go only in a ## [Unreleased] block, which the next release folds in.
• Bump-level guide for this skill specifically:
  • MAJOR = breaking the public surface (see rule 5).
  • MINOR = additive (new sub-skill, new addon, new preset, new flag).
  • PATCH = bug fixes, docs, internal refactors, CI changes.

5. Don't break the public surface

These are public contracts other systems depend on. Changing them is a breaking change that requires a MAJOR version bump and a migration note in CHANGELOG.md:

• Skill name fields in frontmatter (skills.sh registry references them).
• The /deepworkplan-* slash commands (create, execute, refine, resume, status, onboard, verify, author, upgrade) — the same set setup.sh links as deepworkplan-<name> symlinks.
• The .dwp/ output convention (.dwp/plans/) and the DWP_DIR / DWP_AGENT_TOOL env-var overrides read by shared/context.sh.
• setup.sh flags (--host, --help) and the resulting symlink names.

6. set -euo pipefail everywhere + bash 3.2 compatibility

macOS still ships bash 3.2 by default. setup.sh and skills/deepworkplan/shared/context.sh must run on bash 3.2:

• ❌ No mapfile / readarray (bash 4+)
• ❌ No associative arrays declare -A (bash 4+)
• ❌ No ${var^^} / ${var,,} case conversion (bash 4+)
• ✅ Use while IFS= read -r line; do ...; done < <(cmd) instead of mapfile
• ✅ Use tr '[:lower:]' '[:upper:]' for case conversion

All shell scripts start with #!/usr/bin/env bash then set -euo pipefail. CI runs the setup.sh smoke job on both ubuntu-latest and macos-latest to enforce bash 3.2 compatibility.

Commit Message Format (MANDATORY)

<type>(<scope>): <short description>

<body — Summary, motivation, what changed, risks>

Co-Authored-By: <agent name + version> <noreply@anthropic.com>

Types: feat (new behavior), fix (bug fix), docs (docs only), chore (repo maintenance), test (adding tests), ci (CI config), refactor (no user-visible change).

Scopes: skill (general pack/router), create / execute / refine / resume / status / onboard (specific sub-skill), addon (an addon under addons/), shared (context.sh, dwp-paths.md, adaptation.md, update-state.py, state_contract.py, finalize_plan.py), setup (setup.sh), ci (.github/), docs (docs/, README, guide), release (versioning, CHANGELOG).

Examples:

feat(onboard): reason about monorepo workspaces when generating per-module docs
fix(execute): handle a plan with zero remaining tasks gracefully
docs(skill): polish the router SKILL.md to read well on the skills.sh listing
feat(create)!: replace the two-step draft flow with a single-step create

Pre-Commit Checklist

• All changes in English
• python3 scripts/validate-frontmatter.py passes
• shellcheck setup.sh skills/deepworkplan/shared/context.sh scripts/*.sh clean
• bats tests/ passes
• Ship boundary intact — no runtime file added outside skills/deepworkplan/, no dev-infra file added inside it
• No name: deepworkplan_* (snake_case) introduced
• No homepage: (legacy field) introduced; version: stays quoted
• No bash 4+ idioms (mapfile, declare -A, ${var^^}) introduced
• Public surface preserved (slash-command names, .dwp/ convention, setup.sh flags, skill name fields)
• Did NOT hand-edit version: or CHANGELOG.md (the bot owns them)
• setup.sh tested with at least ./setup.sh --host claude
• Commit message follows <type>(<scope>): description format

Common Mistakes

DON'T

1. Put runtime files outside skills/deepworkplan/ — they won't ship to users
2. Use name: deepworkplan_create (snake_case) — must be deepworkplan-create (kebab)
3. Use homepage: in frontmatter — use documentation_url:
4. Hand-edit version: fields or CHANGELOG.md — the auto-release bot owns them
5. Use bash 4+ features (mapfile, associative arrays, ${var^^}) in any script — they break on macOS bash 3.2
6. Rename a slash command or change the .dwp/ convention without a MAJOR bump
7. Add a new sub-skill or addon folder without giving it its own SKILL.md with full frontmatter

DO

1. Keep dev infrastructure (.github/, tests/, scripts/, docs/, this file) at the repo root
2. Use kebab-case deepworkplan-* for name: in frontmatter
3. Run python3 scripts/validate-frontmatter.py and shellcheck setup.sh skills/deepworkplan/shared/context.sh before pushing
4. Write conventional commits so the auto-release picks the right bump level
5. Test setup.sh manually with --host claude after touching it

Shared Agent Coordination

Multiple AI agents may work on this repo simultaneously. They all read this AGENTS.md:

• Claude Code reads CLAUDE.md (symlink to AGENTS.md)
• Cursor AI reads AGENTS.md
• OpenAI Codex reads AGENTS.md
• Gemini CLI reads AGENTS.md
• GitHub Copilot reads AGENTS.md

AGENTS.md is the canonical source — you don't need to mirror to per-agent files.

Vendored agent skills — three dogfood copies under .agents/skills/

The tracked copies are pinned in skills-lock.json. Treat DeepWorkPlan as a generated mirror of skills/deepworkplan/: refresh only with bash scripts/refresh-dogfood-skill.sh, review the checksum-verified diff, and commit the updated lockfile. Both release workflows run the same script in the release commit, after stamping version:.

Do not hand-edit the Dailybot or AI Diff Reviewer copies; contribute upstream. Auto-release refreshes those two addons. Every exact https://github.com/DailybotHQ/ai-diff-reviewer/tree/vX.Y.Z install pin in the shipped pack must match the vendored reviewer's version (tests/agents-dogfood.bats). The Action's floating @v2 pin is exempt.

The full refresh procedure, rationale, and release-loop safeguards are in Design — vendored agent skills.

Local AI Diff Reviewer

The vendored ai-diff-reviewer skill remains available for local reviews during Deep Work Plan Final Reviews. The repository also runs a CI self-review (.github/workflows/self-review.yml): a single grok leg via DailybotHQ/ai-diff-reviewer@v3, label-gated on ready (case-insensitive, run-once per application — remove and re-add the label to re-run), with an honest skip when XAI_API_KEY is not configured. That secret is required only for the CI leg; the local review never needs it. The repository-specific .review/extension.md configures both the local and the CI review.

The ai-diff-reviewer addon (required local review, optional CI surface)

Living alongside the vendored skill above, this repo also ships the DWP addon at skills/deepworkplan/addons/ai-diff-reviewer/SKILL.md. It is the DWP-side counterpart to the raw skill: while the vendored skill at .agents/skills/ai-diff-reviewer/ is a general-purpose reviewer that any repo can use, the addon is what onboards ai-diff-reviewer into a concrete plan.

Two adoption flows (documented in the addon's SKILL.md + INTEGRATION.md):

• Flow A — local-only. Vendor the skill under .agents/skills/, bootstrap .review/extension.md (required for SR detection), and run the local review pre-push. No CI Action, no GitHub secret.
• Flow B — dual-surface. Vendor the skill AND install pr-review.yml. Local and CI read the same inputs — the same prompt.md and the same .review/extension.md — so the review criteria are identical by construction. The findings a model returns on a given diff are not guaranteed to be identical run to run; input parity is the claim, output equality is not.

Six capabilities (the parent default flow plus five sub-skills) the addon defers to (all live in the upstream ai-diff-reviewer repo — the DWP addon does NOT re-implement them):

• parent default flow — run a local review on the current branch.
• generate-extension — draft a repo-specific .review/extension.md.
• setup — install pr-review.yml (Flow B). Reference manual for every action.yml input.
• open-pr — draft a PR title + body from the current diff.
• apply-review — read CI reviews on a PR and walk through findings per-finding (apply / defer / skip). Read-only by default. Optional Flow B companion.
• address-review — close the loop: resolve the CI review's findings, repair the PR's other failing workflows and re-arm the reviewer (commits and pushes: only on the developer's explicit request).

How the addon fits a DWP plan. Since DWP standard 2.3.0 the local review is part of the baseline (skills/deepworkplan/spec/ADDONS.md §6.5): onboard installs the vendored skill and bootstraps .review/extension.md in Phase 7a, and the deepworkplan-create / deepworkplan-execute sub-skills run the ai-diff-reviewer local pass inside the Final Review's security pass, appending its findings to .dwp/plans/<plan>/analysis_results/SECURITY_REVIEW.md. A missing skill or extension is a recorded local reviewer not installed finding, carried into the completion report, never a silent skip; installation belongs to onboarding Phase 7a or an explicit addon invocation; invocation errors soft-fail; critical findings from a completed pass still block completion until fixed or explicitly accepted. The CI Action (Flow B) remains an explicit opt-in. Legacy plans keep their recorded three-final-task shape and get the same pass on their Security Review task.

When in Doubt

• Behavior of an end-user-facing flow → read the relevant SKILL.md inside skills/deepworkplan/
• An install / packaging decision → consult the skills.sh CLI README and the Open Agent Skills spec
• A breaking-change decision → bump major version (via feat(...)!:), document the migration path in CHANGELOG.md, mention in the PR description

This repository is small but plays in a public ecosystem. Lean toward caution on behavior changes — your work is auditable by every agent that reads our SKILL.md and by every team that evaluates the skill.