diff --git a/AGENTS.md b/AGENTS.md index 5dd7534..981cc3e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -39,6 +39,7 @@ the same instructions other agents do. | `resume` sub-skill | [skills/deepworkplan/resume/SKILL.md](skills/deepworkplan/resume/SKILL.md) | | `status` sub-skill | [skills/deepworkplan/status/SKILL.md](skills/deepworkplan/status/SKILL.md) | | `onboard` sub-skill (make any repo AI-first) | [skills/deepworkplan/onboard/SKILL.md](skills/deepworkplan/onboard/SKILL.md) | +| `author` sub-skill (author/update skills, agents, commands) | [skills/deepworkplan/author/SKILL.md](skills/deepworkplan/author/SKILL.md) | | Methodology guide | [skills/deepworkplan/guide/GUIDE.md](skills/deepworkplan/guide/GUIDE.md) | | Context detection + `.dwp/` resolution | [skills/deepworkplan/shared/context.sh](skills/deepworkplan/shared/context.sh) | | `.dwp/` output path convention | [skills/deepworkplan/shared/dwp-paths.md](skills/deepworkplan/shared/dwp-paths.md) | @@ -98,6 +99,7 @@ deepworkplan-skill/ ├── resume/SKILL.md ← resume an interrupted plan ├── status/SKILL.md ← report plan status ├── 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/devcontainer/SKILL.md ← opt-in devcontainer addon diff --git a/README.md b/README.md index b265122..d58402b 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,7 @@ living in a gitignored `.dwp/` directory. | **deepworkplan-refine** | Refine a plan draft, or modify the scope/tasks of an existing final plan. | | **deepworkplan-resume** | Resume an interrupted plan from its recorded progress state. | | **deepworkplan-status** | Report the status of a plan — completed tasks, what's left, and blockers — without executing. | +| **deepworkplan-author** | Author or update reusable skills, agents, and commands in the current repo — reasons about the repo's `.agents/` layout, follows the Open Agent Skills frontmatter contract, and keeps the `.agents/docs/` catalog in sync. Backs the `/skill-create` and `/agent-create` aliases. | A root **deepworkplan** meta-skill acts as a router — it describes all capabilities and routes to the right sub-skill based on the developer's intent. @@ -99,6 +100,7 @@ sub-skill: - "Create a plan to ship feature X" → **deepworkplan-create** - "Execute the plan" / "continue the plan" → **deepworkplan-execute** - "What's left on the plan?" → **deepworkplan-status** +- "Create a skill / agent" / "evolve the kit" → **deepworkplan-author** (also `/skill-create`, `/agent-create`) Or invoke directly: `/deepworkplan-create`, `/deepworkplan-onboard`, etc. @@ -178,4 +180,4 @@ checklist. Deeper background lives under [`docs/`](docs/) — [DESIGN.md](docs/D ## :electric_plug: Powered by [Dailybot](https://www.dailybot.com?utm_source=dailybotopensource&utm_medium=deepworkplan-skill) -Dailybot is an [AI Assistant](https://www.dailybot.com/product/ai) powered by ChatGPT that takes chat and collaboration to the next level helping to automate: daily standups, team check-ins, surveys, kudos, virtual watercooler, 1:1 intros, motivation tracking, chatops and more. [Learn more](https://www.dailybot.com?utm_source=dailybotopensource&utm_medium=deepworkplan-skill). +[Dailybot](https://www.dailybot.com/product/ai) is an AI-powered async communication platform that keeps **people and agents** visible — without adding more meetings or tools. It lives where your team already works (Slack, Teams, Google Chat, Discord, VS Code, and the CLI) and turns scattered signals into clear progress: async check-ins and standups, AI summaries that detect blockers and read team sentiment, workflow automation and approvals, team analytics, and recognition. As AI agents join the workflow, Dailybot surfaces their status and activity right alongside your team's — so long-running agents never go dark. [Learn more](https://www.dailybot.com?utm_source=dailybotopensource&utm_medium=deepworkplan-skill). diff --git a/docs/SUB_SKILL_GUIDE.md b/docs/SUB_SKILL_GUIDE.md index e178874..b85168f 100644 --- a/docs/SUB_SKILL_GUIDE.md +++ b/docs/SUB_SKILL_GUIDE.md @@ -1,8 +1,8 @@ # Adding a New Sub-Skill Step-by-step for adding a new capability under `skills/deepworkplan/`. Use this -when you have a new verb that's distinct enough from the existing six -(`onboard`, `create`, `execute`, `refine`, `resume`, `status`) to deserve its own +when you have a new verb that's distinct enough from the existing seven +(`onboard`, `create`, `execute`, `refine`, `resume`, `status`, `author`) to deserve its own `SKILL.md`, but tightly enough coupled to the DeepWorkPlan methodology that it belongs in this pack rather than a separate repo. diff --git a/skills/deepworkplan/SKILL.md b/skills/deepworkplan/SKILL.md index af763c1..11cd414 100644 --- a/skills/deepworkplan/SKILL.md +++ b/skills/deepworkplan/SKILL.md @@ -41,6 +41,7 @@ full step-by-step flow. | "resume", "continue the interrupted plan", "/dwp-resume" | **Resume** → read [`resume/SKILL.md`](resume/SKILL.md) | | "plan status", "what's left", "/dwp-status" | **Status** → read [`status/SKILL.md`](status/SKILL.md) | | "make this repo AI-first", "onboard this repo", "set up AGENTS.md + docs + .agents" | **Onboard** → read [`onboard/SKILL.md`](onboard/SKILL.md) | +| "create/update a skill or agent", "evolve the kit", "/skill-create", "/agent-create" | **Author** → read [`author/SKILL.md`](author/SKILL.md) | If the intent is ambiguous between planning and managing existing work, ask the developer which they mean before routing. diff --git a/skills/deepworkplan/addons/README.md b/skills/deepworkplan/addons/README.md index 0162094..913985a 100644 --- a/skills/deepworkplan/addons/README.md +++ b/skills/deepworkplan/addons/README.md @@ -62,9 +62,12 @@ An addon MAY additionally ship per-stack presets, examples, or migration notes. |-------|--------|--------| | Devcontainer support | [`addons/devcontainer/`](devcontainer/SKILL.md) | **Authored** — compose-based `.devcontainer/` + `docker/` with AI-CLI persistence, `dailybot-project-network`, `DOCKER_DEV_ENV=vscode`, project-identity precedence, public-OSS variant, 7 reasoning presets. | | Dailybot integration | [`addons/dailybot/`](dailybot/SKILL.md) | **Authored** — opt-in install of the Dailybot agent skill / CLI, auth **deferred** to the Dailybot skill's own consent flow, and an **optional, best-effort, never-blocking** progress/milestone report wired into DWP execution (a plan completion → a Dailybot milestone report). The core methodology has **zero** Dailybot dependency. | +| Dependency upgrade | [`addons/dependency-upgrade/`](dependency-upgrade/SKILL.md) | **Authored** — opt-in, **package-manager-agnostic** dependency upgrades: detect the repo's real manager (npm/pnpm/yarn + ncu, pip/poetry/uv, cargo, go mod, bundler, composer…), classify by semver, upgrade in safe batches, run the repo's **real** validation gate after each batch, revert a failing batch, summarize. Installs a `/lib-upgrade` delegator into the repo's `.agents/commands/` only when accepted. | > This README is the mechanism doc. The first addon, `addons/devcontainer/`, is > the methodology's proof that the mechanism works; the second, > `addons/dailybot/`, shows an addon can layer optional team visibility while -> keeping the methodology fully vendor-neutral (a repo is conformant with zero -> addons). +> keeping the methodology fully vendor-neutral; the third, +> `addons/dependency-upgrade/`, shows an addon can encode a recurring maintenance +> workflow that reasons about each repo's actual stack (a repo is conformant with +> zero addons). diff --git a/skills/deepworkplan/addons/dependency-upgrade/SKILL.md b/skills/deepworkplan/addons/dependency-upgrade/SKILL.md new file mode 100644 index 0000000..33ba29f --- /dev/null +++ b/skills/deepworkplan/addons/dependency-upgrade/SKILL.md @@ -0,0 +1,130 @@ +--- +name: deepworkplan-addon-dependency-upgrade +description: Optional DeepWorkPlan addon that safely upgrades a repo's dependencies — reasoning about the repo's ACTUAL package manager (npm/pnpm/yarn + ncu, pip/poetry/uv, cargo, go mod, bundler, composer, and more) rather than assuming npm — with a batched, validated, revertible workflow that detects the manager and manifests/lockfiles, classifies upgrades (patch/minor/major), upgrades in safe batches, runs the repo's real validation gate after each batch, reverts a failing batch, and summarizes. Opt-in, never required, reconciles with the repo's existing tooling. Use when the developer wants to bring dependencies up to date without breaking the build. +version: "2.0.2" +documentation_url: https://deepworkplan.com +user-invocable: true +allowed-tools: Bash, Read, Grep, Glob, Edit, Write +metadata: {"openclaw":{"emoji":"⬆️","homepage":"https://deepworkplan.com"}} +--- + +# DeepWorkPlan — Dependency-Upgrade Addon + +Safely bring a repo's dependencies up to date with a **batched, validated, +revertible** workflow. This is the methodology's **third opt-in addon** — it is +**never** required for a repo to be AI-first. + +> ## The rule that overrides everything: REASON about the package manager, then upgrade +> +> The legacy version of this workflow assumed npm. **It does not.** The first job +> is to **detect the repo's actual package manager from the manifest and lockfile +> that exist** (see `SPEC.md` §2 and `templates/ecosystems.md`), then drive that +> manager's real upgrade and install commands. Never run `ncu`/`pnpm` in a Go, +> Rust, Python, Ruby, or PHP repo. Never assume a lockfile you have not seen. + +## Read these first (all relative inside the skill) + +- [`SPEC.md`](SPEC.md) — the normative (RFC-2119) contract: detection, semver + classification, batched-upgrade rule, validate-after-each-batch gate, + revert-on-failure rule, reconcile-don't-clobber, validation step. +- [`templates/ecosystems.md`](templates/ecosystems.md) — the **per-ecosystem + reasoning table**: how to detect each manager and its real detect / classify / + upgrade / install / lockfile commands. Match the row for the detected stack as + a *checklist*, then verify against the real repo — **detected reality wins**. +- [`templates/upgrade-report.md`](templates/upgrade-report.md) — the report shape + to summarize what was upgraded, skipped, reverted, and validated. +- [`templates/lib-upgrade-command.md`](templates/lib-upgrade-command.md) — the + `/lib-upgrade` delegator this addon installs into the target repo's + `.agents/commands/` **only when accepted**. +- `../README.md` — the addon mechanism (opt-in, reconcile-don't-clobber, contract). + +## When this runs + +- From **`onboard` Phase 7b** — after the core AI-first scaffolding, `onboard` + offers this addon; if accepted it reads this SKILL and runs the flow below. +- **Directly** — `/deepworkplan-addon-dependency-upgrade` on an already-onboarded + repo to upgrade dependencies, or via the installed `/lib-upgrade` delegator. + +## The flow + +### Step 0 — Consent + clean tree +1. Confirm the developer wants a dependency upgrade (skip silently if declined — + the repo stays baseline-conformant). +2. **Require a clean (or backed-up) working tree.** Run `git status`; if there + are uncommitted changes, ask the developer to commit or stash first. A clean + tree is what makes a batch revertible (Step 4). + +### Step 1 — Detect the package manager (the part you MUST reason about) +Detect the manager(s) from the **manifest + lockfile that actually exist**, never +by assuming npm. Use `templates/ecosystems.md`: + +- **JS/TS** → `package.json` + which lockfile: `pnpm-lock.yaml` (pnpm), + `yarn.lock` (yarn), `package-lock.json` (npm). `ncu` is the cross-manager + version checker; the install/update verb is the detected manager's. +- **Python** → `pyproject.toml` + `poetry.lock` (poetry) / `uv.lock` (uv); + `requirements*.txt` (pip / pip-tools); `Pipfile.lock` (pipenv). +- **Rust** → `Cargo.toml` + `Cargo.lock` (`cargo update`). +- **Go** → `go.mod` + `go.sum` (`go get -u` / `go get` per module + `go mod tidy`). +- **Ruby** → `Gemfile` + `Gemfile.lock` (`bundle update`). +- **PHP** → `composer.json` + `composer.lock` (`composer update`). + +A repo MAY have **more than one** ecosystem (e.g. a JS frontend + a Python +service). Handle each ecosystem with its own manager, in its own batches. + +### Step 2 — Classify upgrades (patch / minor / major) +For every outdated dependency, classify by semver against the version in the +manifest/lockfile: + +- **patch** `X.Y.Z → X.Y.(Z+1)` — safest (bug fixes). +- **minor** `X.Y.Z → X.(Y+1).0` — usually safe (additive, backward-compatible). +- **major** `X.Y.Z → (X+1).0.0` — breaking changes possible. + +Group **patch + minor** as the auto-batchable set. **Majors require explicit +developer approval** before inclusion (present them and wait). Upgrade tightly +coupled packages **together** (e.g. `typescript` + its plugins; a framework + its +companion packages) so a peer-dependency constraint is not split across batches. + +### Step 3 — Upgrade in safe batches +Apply upgrades in **small, coherent batches** — never all at once (that makes a +failure impossible to isolate). A reasonable order: patch batch → minor batch → +each approved major **on its own**. For each batch, run the detected manager's +**update-manifest + install** commands (e.g. `ncu -u --target minor` then the +manager's install; `cargo update -p `; `go get @latest`; +`poetry update `; `bundle update `; `composer update `). The +lockfile is regenerated by the manager — never hand-edit it. + +### Step 4 — Validate after EACH batch (the gate) +After every batch, run the **repo's real validation gate** — the commands the +repo actually uses, discovered from `AGENTS.md` Quick Commands / +`docs/DEVELOPMENT_COMMANDS.md` / the manifest's scripts, or the devcontainer's +`codecheck`/`check`/`fix`/`test` aliases if that addon is present. Examples: +`pnpm run biome:check && pnpm run astro:check && pnpm run build`; +`ruff check && mypy && pytest`; `cargo test`; `go build ./... && go test ./...`; +`bundle exec rspec`; `composer test`. **Never invent a gate** — use the repo's +real one. + +### Step 5 — Revert a failing batch +If the gate fails for a batch, **revert just that batch** and continue: +restore the manifest **and** lockfile (`git checkout -- `), +re-run install to resync, confirm the gate passes again, then record the batch as +**skipped/failed** with the reason. Optionally retry the batch one package at a +time to isolate the culprit. A failing major is set aside, not forced. + +### Step 6 — Summarize +Produce the report from `templates/upgrade-report.md`: upgraded (by tier), +skipped (with reason), reverted (with the failing gate), the manager(s) used, the +files changed (manifest + lockfile), and recommended follow-ups. **Do not commit +automatically** — surface the diff and let the developer commit (suggest +`chore(deps): …`). + +## Failure-mode guardrails + +- **Never required, never blocking.** If the developer declines, stop cleanly. +- **Reason about the manager.** Never run npm/ncu in a non-JS repo; never assume a + lockfile you have not seen. +- **Never all-at-once.** Batch so a failure is isolable and revertible. +- **Real gate only.** Validate with the repo's actual commands, never a guess. +- **Revert, don't push through.** A failing batch is reverted and recorded, never + force-installed past a broken gate. +- **Don't hand-edit lockfiles.** The manager owns them; regenerate via install. +- **Don't auto-commit.** Surface the diff; the developer commits. diff --git a/skills/deepworkplan/addons/dependency-upgrade/SPEC.md b/skills/deepworkplan/addons/dependency-upgrade/SPEC.md new file mode 100644 index 0000000..d29f00c --- /dev/null +++ b/skills/deepworkplan/addons/dependency-upgrade/SPEC.md @@ -0,0 +1,175 @@ +# SPEC.md — Dependency-Upgrade Addon (Normative) + +## Abstract + +This document is the **normative specification** of the DeepWorkPlan +**dependency-upgrade addon**: an opt-in capability that **safely upgrades a +repository's dependencies** with a **batched, validated, revertible** workflow. +It defines **package-manager detection** (RFC-2119), **semver classification**, +the **batched-upgrade** rule, the **validate-after-each-batch** gate, the +**revert-on-failure** rule, the **reconcile-don't-clobber** behavior, and the +**validation** step. + +The addon is **package-manager agnostic**: it reasons about the repo's **actual** +manager (npm/pnpm/yarn, pip/poetry/uv/pipenv, cargo, go mod, bundler, composer, +and more) rather than assuming npm. It is governed by `../README.md` and +`methodology-spec/ADDONS.md`: it is **never** required for baseline AI-first +conformance. + +## Status of This Document + +| Field | Value | +|-------|-------| +| **Version** | 2.0.0 | +| **Status** | Stable | +| **Companions** | `SKILL.md`, `templates/ecosystems.md`, `templates/upgrade-report.md`, `templates/lib-upgrade-command.md`, `../README.md`, `methodology-spec/ADDONS.md` | +| **License** | MIT | + +## 1. Conventions + +The RFC 2119 keywords (**MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, +**MAY**, **OPTIONAL**) are interpreted as in +[RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). + +Throughout, a **batch** is a small, coherent set of dependency upgrades applied +and validated together, and the **gate** is the repo's real validation command +set (lint + typecheck + build + test, as applicable). + +--- + +## 2. Package-Manager Detection (the part the addon reasons about) + +- The addon **MUST** detect the package manager(s) from the **manifest and + lockfile that actually exist** in the repo. It **MUST NOT** assume npm or any + single ecosystem. +- Detection signals **MUST** be derived from real files, e.g.: + + | Ecosystem | Manifest | Lockfile → manager | + |-----------|----------|--------------------| + | JS / TS | `package.json` | `pnpm-lock.yaml` → pnpm · `yarn.lock` → yarn · `package-lock.json` → npm | + | Python | `pyproject.toml` / `requirements*.txt` / `Pipfile` | `poetry.lock` → poetry · `uv.lock` → uv · `Pipfile.lock` → pipenv · pinned `requirements*.txt` → pip / pip-tools | + | Rust | `Cargo.toml` | `Cargo.lock` → cargo | + | Go | `go.mod` | `go.sum` → go modules | + | Ruby | `Gemfile` | `Gemfile.lock` → bundler | + | PHP | `composer.json` | `composer.lock` → composer | + +- A repo **MAY** contain **multiple** ecosystems (e.g. a JS frontend + a Python + service). The addon **MUST** handle each ecosystem with its own manager and its + own batches. +- For JS/TS, `ncu` (npm-check-updates) **MAY** be used as the cross-manager + **version checker**, but the **install/update verb MUST** be the detected + manager's (`pnpm install`, `yarn install`, `npm install`). +- The full per-ecosystem command reference is `templates/ecosystems.md`; it is a + **checklist**, not an answer key — **detected reality wins**. + +--- + +## 3. Semver Classification + +- Every outdated dependency **MUST** be classified by semantic version against + its current pinned version: + - **patch** `X.Y.Z → X.Y.(Z+1)` (safest), + - **minor** `X.Y.Z → X.(Y+1).0` (usually safe), + - **major** `X.Y.Z → (X+1).0.0` (breaking changes possible). +- **patch + minor** upgrades **MAY** be batched automatically. +- **major** upgrades **MUST** require explicit developer approval before + inclusion; the addon **MUST** present them and wait. +- Tightly coupled packages (a tool + its plugins; a framework + its companion + packages) **SHOULD** be upgraded in the **same** batch so a peer-dependency + constraint is not split across batches. + +--- + +## 4. Batched Upgrade + +- The addon **MUST** apply upgrades in **small, coherent batches** and **MUST + NOT** upgrade everything at once (an all-at-once upgrade makes a failure + impossible to isolate or revert cleanly). +- A reasonable order is: **patch** batch → **minor** batch → each approved + **major** on its own. +- Each batch **MUST** update the manifest and regenerate the lockfile **via the + detected manager's install/update command**. The addon **MUST NOT** hand-edit + a lockfile. + +--- + +## 5. Validate-After-Each-Batch Gate + +- After every batch, the addon **MUST** run the **repo's real validation gate** — + the actual lint / typecheck / build / test commands the repo uses. +- The gate **MUST** be discovered from the repo (`AGENTS.md` Quick Commands, + `docs/DEVELOPMENT_COMMANDS.md`, the manifest's scripts, or the devcontainer + addon's `codecheck`/`check`/`fix`/`test` aliases if present). The addon **MUST + NOT** invent a gate. +- A batch is **accepted** only if the gate passes. A batch whose gate fails + **MUST** be handled per §6. + +--- + +## 6. Revert on Failure + +- If a batch's gate fails, the addon **MUST** revert **just that batch**: + restore the manifest **and** lockfile (e.g. `git checkout -- + `), re-run install to resync, and confirm the gate passes again. +- The addon **MUST** record the reverted batch as skipped/failed with the failing + gate and reason. It **MAY** retry the batch one package at a time to isolate the + culprit. +- A failing major upgrade **MUST** be set aside, never force-installed past a + broken gate. +- The addon **MUST NOT** auto-commit; it surfaces the diff and lets the developer + commit (suggested: `chore(deps): …`). + +--- + +## 7. Reconcile, Don't Clobber + +- The addon operates on the repo's **existing** manifests and lockfiles; it + **MUST** preserve every pin and constraint it does not deliberately upgrade. +- It **MUST NOT** delete or rewrite a lockfile wholesale, change the package + manager, or remove dependencies without explicit approval. +- It **MUST** record what it changed (in the upgrade report). + +--- + +## 8. Onboarding Hook + `/lib-upgrade` Delegator + +- The addon's onboarding hook (`SKILL.md`) is offered by `onboard` Phase 7b as an + **opt-in** step and **MUST NOT** be applied without acceptance. +- **Only when accepted**, the addon **MUST** install a `/lib-upgrade` delegator + command into the target repo's `.agents/commands/` (template: + `templates/lib-upgrade-command.md`) that delegates to this addon. A declined + addon installs **no** command and leaves a baseline-conformant repo. + +--- + +## 9. Validation Step (run after applying) + +The addon is correctly applied when **all** hold: + +1. The package manager(s) were **detected from real manifests/lockfiles**, not + assumed (no npm/ncu run in a non-JS repo). +2. Upgrades were **classified** by semver and **batched** (never all-at-once); + majors required explicit approval. +3. The **repo's real gate** ran after **each** batch and every accepted batch + passes it. +4. Any failing batch was **reverted** (manifest + lockfile restored, install + resynced, gate green) and recorded. +5. No lockfile was hand-edited; no auto-commit happened. +6. An upgrade **report** (`templates/upgrade-report.md`) summarizes upgraded / + skipped / reverted / validated. +7. If accepted via onboarding, a `/lib-upgrade` delegator exists in the repo's + `.agents/commands/`; if declined, none was installed. + +--- + +## 10. References + +- [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) +- `SKILL.md` (the onboarding hook + flow), `templates/*` (reasoning aids) +- `../README.md` (addon mechanism), `methodology-spec/ADDONS.md` (concept + pointer) +- [Semantic Versioning](https://semver.org/) +- [npm-check-updates](https://github.com/raineorshine/npm-check-updates) + +--- + +*Part of the DeepWorkPlan methodology v2.0.0, MIT License, by [Dailybot](https://dailybot.com) / dailybotops.* diff --git a/skills/deepworkplan/addons/dependency-upgrade/templates/ecosystems.md b/skills/deepworkplan/addons/dependency-upgrade/templates/ecosystems.md new file mode 100644 index 0000000..872dcdc --- /dev/null +++ b/skills/deepworkplan/addons/dependency-upgrade/templates/ecosystems.md @@ -0,0 +1,103 @@ +# Template — Per-Ecosystem Upgrade Reference (reasoning aid) + +This is a **reasoning aid**, not a copy-paste script. Detect the repo's **actual** +package manager from the manifest and lockfile that exist, then drive **that** +manager's real commands. Match the row for the detected stack as a *checklist* and +verify each command against the real repo — **detected reality wins**. A repo MAY +have more than one ecosystem; handle each with its own manager, in its own batches. + +## How to detect the manager (lockfile is the tell) + +| Ecosystem | Manifest | Lockfile present → manager | +|-----------|----------|----------------------------| +| JS / TS | `package.json` | `pnpm-lock.yaml` → **pnpm** · `yarn.lock` → **yarn** · `package-lock.json` → **npm** | +| Python | `pyproject.toml` / `requirements*.txt` / `Pipfile` | `poetry.lock` → **poetry** · `uv.lock` → **uv** · `Pipfile.lock` → **pipenv** · pinned `requirements*.txt` → **pip / pip-tools** | +| Rust | `Cargo.toml` | `Cargo.lock` → **cargo** | +| Go | `go.mod` | `go.sum` → **go modules** | +| Ruby | `Gemfile` | `Gemfile.lock` → **bundler** | +| PHP | `composer.json` | `composer.lock` → **composer** | + +> Never assume npm. Never run a manager whose lockfile is absent. If two JS +> lockfiles exist, the committed one wins; flag the inconsistency. + +## Per-ecosystem command reference + +> `{pkg}` = a single dependency · `{mgr}` = the detected JS manager +> (`pnpm`/`yarn`/`npm`). The **gate** in every row is the **repo's real** +> validation command set, discovered from `AGENTS.md` / `docs/` / the manifest — +> the examples below are illustrative, not prescriptive. + +### JS / TS (npm · pnpm · yarn) — `ncu` is the cross-manager checker + +| Step | Command | +|------|---------| +| Check outdated | `ncu` (or `ncu --format json`); fallback `{mgr} outdated` | +| Classify | parse current vs target semver from `ncu` output → patch / minor / major | +| Update manifest (patch) | `ncu -u --target patch` | +| Update manifest (minor) | `ncu -u --target minor` | +| Update manifest (chosen) | `ncu -u --filter "{pkg-a} {pkg-b}"` | +| Install / regenerate lock | `{mgr} install` (pnpm/yarn/npm) | +| Gate (example) | `pnpm run biome:check && pnpm run astro:check && pnpm run build && pnpm run test` | +| Revert a batch | `git checkout -- package.json && {mgr} install` | + +### Python — poetry · uv · pip / pip-tools · pipenv + +| Step | poetry | uv | pip-tools | pipenv | +|------|--------|-----|-----------|--------| +| Check outdated | `poetry show -o` | `uv pip list --outdated` | `pip list --outdated` | `pipenv update --outdated` | +| Update chosen | `poetry update {pkg}` | `uv lock --upgrade-package {pkg}` | bump in `requirements*.in` then `pip-compile` | `pipenv update {pkg}` | +| Install / sync | `poetry install` | `uv sync` | `pip-sync` / `pip install -r …` | `pipenv install` | +| Lockfile | `poetry.lock` | `uv.lock` | pinned `requirements*.txt` | `Pipfile.lock` | +| Revert | `git checkout -- pyproject.toml poetry.lock && poetry install` | `git checkout -- pyproject.toml uv.lock && uv sync` | `git checkout -- requirements*.txt && pip-sync` | `git checkout -- Pipfile Pipfile.lock && pipenv install` | +| Gate (example) | `ruff check && mypy && pytest` | (same) | (same) | (same) | + +### Rust — cargo + +| Step | Command | +|------|---------| +| Check outdated | `cargo update --dry-run` (or `cargo outdated` if installed) | +| Update chosen | `cargo update -p {pkg}` (minor/patch within semver) | +| Major bump | edit the version req in `Cargo.toml`, then `cargo update -p {pkg}` | +| Lockfile | `Cargo.lock` (regenerated by `cargo update`) | +| Gate (example) | `cargo build && cargo test && cargo clippy -- -D warnings` | +| Revert | `git checkout -- Cargo.toml Cargo.lock` | + +### Go — go modules + +| Step | Command | +|------|---------| +| Check outdated | `go list -u -m all` | +| Update chosen (minor/patch) | `go get {module}@latest` (or a specific tag) | +| Tidy | `go mod tidy` | +| Lockfile | `go.mod` + `go.sum` | +| Gate (example) | `go build ./... && go test ./... && go vet ./...` | +| Revert | `git checkout -- go.mod go.sum` | + +### Ruby — bundler + +| Step | Command | +|------|---------| +| Check outdated | `bundle outdated` | +| Update chosen | `bundle update {gem}` (conservative: `--conservative`) | +| Lockfile | `Gemfile.lock` | +| Gate (example) | `bundle exec rubocop && bundle exec rspec` | +| Revert | `git checkout -- Gemfile Gemfile.lock && bundle install` | + +### PHP — composer + +| Step | Command | +|------|---------| +| Check outdated | `composer outdated` | +| Update chosen | `composer update {pkg} --with-dependencies` | +| Lockfile | `composer.lock` | +| Gate (example) | `composer lint && composer test` | +| Revert | `git checkout -- composer.json composer.lock && composer install` | + +## Reasoning notes + +- **The lockfile is regenerated by the manager** — never hand-edit it. +- **Discover the gate, don't guess it.** Read the repo's `AGENTS.md` Quick + Commands / `docs/DEVELOPMENT_COMMANDS.md` / manifest scripts, or use the + devcontainer addon's `codecheck`/`check`/`fix`/`test` aliases if present. +- **Batch + validate + revert** is the same loop in every ecosystem; only the + detect / update / install / gate verbs change. diff --git a/skills/deepworkplan/addons/dependency-upgrade/templates/lib-upgrade-command.md b/skills/deepworkplan/addons/dependency-upgrade/templates/lib-upgrade-command.md new file mode 100644 index 0000000..cf14ee9 --- /dev/null +++ b/skills/deepworkplan/addons/dependency-upgrade/templates/lib-upgrade-command.md @@ -0,0 +1,43 @@ +# Template — `/lib-upgrade` delegator command (reasoning aid) + +This is the **delegator command** the dependency-upgrade addon installs into the +target repo's `.agents/commands/lib-upgrade.md` **only when the addon is +accepted** during `onboard` Phase 7b (or when the addon is run directly). It is a +**thin delegator**: it carries no upgrade logic of its own — it routes to the +`deepworkplan-addon-dependency-upgrade` addon, which holds the real flow. + +Fill the placeholders by reasoning about the target repo (its detected package +manager and real validation gate); do not copy verbatim. Decline the addon → do +**not** install this command. + +```markdown +--- +name: lib-upgrade +description: Safely upgrade this repo's dependencies (batched, validated, revertible) via the DeepWorkPlan dependency-upgrade addon. +--- + +# /lib-upgrade + +Bring this repository's dependencies up to date **without breaking the build**. +This command is a **thin delegator** to the DeepWorkPlan +`deepworkplan-addon-dependency-upgrade` addon — it does not contain the upgrade +logic itself. + +## Steps + +1. Invoke the `deepworkplan-addon-dependency-upgrade` addon (via + `/deepworkplan-addon-dependency-upgrade` or by reading the addon's `SKILL.md`). +2. Follow the addon's flow: detect this repo's package manager + (), classify upgrades (patch/minor/major), + upgrade in safe batches, run this repo's real gate after each batch + (), + revert any batch whose gate fails, and summarize. +3. Surface the upgrade report and the diff; do **not** auto-commit. + +## Notes + +- Detected package manager for this repo: . +- Real validation gate for this repo: . +- Majors require explicit approval before they are included in a batch. +- The lockfile is regenerated by the manager — never hand-edit it. +``` diff --git a/skills/deepworkplan/addons/dependency-upgrade/templates/upgrade-report.md b/skills/deepworkplan/addons/dependency-upgrade/templates/upgrade-report.md new file mode 100644 index 0000000..3deea36 --- /dev/null +++ b/skills/deepworkplan/addons/dependency-upgrade/templates/upgrade-report.md @@ -0,0 +1,51 @@ +# Template — Dependency Upgrade Report (reasoning aid) + +This is the **report shape** to produce after the upgrade flow. Fill it by +reasoning about what actually happened; keep the sections, drop rows that do not +apply. Do **not** auto-commit — surface this report and the diff, and let the +developer commit. + +```markdown +# Dependency Upgrade Report + +**Date:** +**Ecosystem(s):** +**Package manager(s) detected from:** + +## Summary + +- Upgraded: dependencies across batches +- Skipped / reverted: (see below) +- Majors: + +## Upgraded (by tier) + +### Patch +- : → + +### Minor +- : → + +### Major (developer-approved) +- : → + +## Skipped / Reverted + +- : → — **reverted**; gate failed: `` () +- : → — **deferred** (major, awaiting review) + +## Validation + +- Gate used (the repo's real commands): `` +- Result per accepted batch: ✅ pass + +## Files changed + +- (e.g. package.json / pyproject.toml / Cargo.toml / go.mod) +- (e.g. pnpm-lock.yaml / poetry.lock / Cargo.lock / go.sum) + +## Recommended follow-ups + +- +- Suggested commit: `chore(deps): upgrade dependencies (patch + minor)` +``` diff --git a/skills/deepworkplan/author/SKILL.md b/skills/deepworkplan/author/SKILL.md new file mode 100644 index 0000000..936ec31 --- /dev/null +++ b/skills/deepworkplan/author/SKILL.md @@ -0,0 +1,177 @@ +--- +name: deepworkplan-author +description: Author or update reusable skills, agents, and commands in the current repo — reason about the repo's .agents/ layout, follow the Open Agent Skills frontmatter contract, and keep the .agents/docs/ catalog in sync. Use when a developer wants to create or evolve the repo's agent kit (skills, agents, commands), or runs /skill-create or /agent-create. +version: "2.0.2" +documentation_url: https://deepworkplan.com +user-invocable: true +allowed-tools: Bash, Read, Grep, Glob, Edit, Write +--- + +# DeepWorkPlan — Author + +Author and maintain the current repository's **agent kit**: reusable **skills**, **agents**, and +**commands**. Reason about the repo — never copy a generic kit. This sub-skill is also the executor of +the mandatory "Skills & Agents Discovery" plan task. + +--- + +## Concepts + +- **Skill** — a reusable, parameterized *procedure* invoked in-session (e.g. `/fix-lint`). Encodes + "how to do X". Lives in `//SKILL.md`. +- **Agent** — a specialized *worker definition* (role, model tier, tools, system prompt) dispatched to + handle a class of tasks (e.g. `reviewer`, `executor`). Encodes "who does X". Lives in + `/.md`. +- **Command** — a thin slash-command entry point that routes to a skill or agent. Logic stays in the + skill/agent; the command is a delegator. + +| Need | Create | +|------|--------| +| A repeatable procedure run in-session | Skill | +| A persistent role with its own model tier / tools | Agent | +| A shortcut to invoke a skill or agent | Command | + +--- + +## Step 0 — Detect the repo layout (do NOT assume) + +Before authoring anything, discover where this repo keeps its kit. Do not hardcode any single repo's +conventions. + +1. Find the agent root: look for `.agents/`, then `.claude/` (often a symlink to `.agents/`), then any + `AGENTS.md` / `CLAUDE.md` at the repo root for documented paths. +2. Within it, locate `skills/`, `agents/`, `commands/`, and a catalog under `docs/`. +3. Inspect 1-2 existing skills/agents to learn the repo's **local conventions** (frontmatter keys it + uses, naming, body structure, whether commands are thin delegators). Match them. + +```bash +ls -d .agents .claude 2>/dev/null +ls .agents/skills .agents/agents .agents/commands .agents/docs 2>/dev/null +ls AGENTS.md CLAUDE.md 2>/dev/null +``` + +If the repo has no `.agents/` layout yet, route the developer to the **onboard** sub-skill first +(`onboard/SKILL.md`) — onboarding scaffolds the directories this sub-skill writes into. + +--- + +## Flows + +Pick the flow that matches the developer's intent. + +### A. Create a skill + +1. **Audit fit** — confirm a real, repeatable workflow exists (see "Repo-fit rubric" below). Skip + generic skills that do not match an actual workflow. +2. **Name it** — kebab-case, English, unique. Check for collisions in the skills dir. +3. **Scaffold** — copy `templates/SKILL_TEMPLATE.md` into `//SKILL.md`. Adapt the + frontmatter to the repo's local convention (keys it already uses). +4. **Fill** — one-procedure focus; clear Goal, When-to-use, Steps, Validation. +5. **Keep commands thin** — if it needs a slash command, add a delegator (see Flow C). +6. **Catalog** — update the repo's catalog under the docs dir (see "Keep the catalog in sync"). +7. **Validate** — naming, structure, frontmatter, and that any command is thin. + +### B. Create an agent + +1. **Confirm a recurring role** with distinct model/tools needs (not just a one-off procedure → that + is a skill). +2. **Name it** — kebab-case, English, unique. +3. **Scaffold** — copy `templates/AGENT_TEMPLATE.md` into `/.md`. +4. **Choose a model tier** — reason about it (see "Model tiers" below). Do NOT hardcode vendor model + IDs inside the agent body; keep the abstract tier and map it in repo config. +5. **Fill** — Role, Inputs, Process, Output, escalation rules. +6. **Catalog** — update the catalog under the docs dir. +7. **Validate** — naming, structure, tier chosen with justification. + +### C. Create a command (thin delegator) + +1. Confirm the target skill or agent exists. +2. Add `/.md` as a ~20-line delegator: read the target skill/agent fresh and follow + it, passing along args. Do NOT embed logic — logic lives in the skill/agent so updates propagate. +3. Reference the new command in the catalog / commands reference. + +### D. Update an existing skill / agent / command + +1. Read the existing file and the repo's conventions first. +2. Make the smallest change that satisfies the request; preserve frontmatter the repo relies on. +3. Keep delegators thin; keep skills single-procedure. +4. Update the catalog if name, description, or surface changed. + +### E. Evaluate the catalog (Skills & Agents Discovery) + +This is the flow invoked by the mandatory plan task. + +1. Enumerate every skill (`/*/SKILL.md`) and agent (`/*.md`). +2. For each, capture name, one-line description, and model tier (if any). +3. Cross-check against the repo's catalog under the docs dir: flag missing entries, stale + descriptions, orphaned commands, and duplicates. +4. Reconcile: update the catalog so it matches reality. Report drift found and fixed. + +--- + +## Repo-fit rubric (before creating) + +Gather: stack & tooling (languages, frameworks, package manager, test runner, linter); workflows (how +code is built, tested, reviewed, released); pain points (repetitive manual steps); the existing kit +(avoid duplicates). Then: + +- Create a **skill** for a repeatable procedure people do by hand. +- Create an **agent** for a recurring role with distinct model/tools needs. +- Create a **command** only as a thin entry point. +- Skip anything generic that does not match a real workflow. + +Anti-patterns to avoid: generic kits that do not match the repo; fat commands with embedded logic; +duplicates of existing skills/agents; agents pinned to vendor model IDs in their bodies. + +--- + +## Model tiers (for agents) + +Skills inherit the session model; agents may pin an abstract tier. + +| Tier | Use for | Examples | +|------|---------|----------| +| **light** | Mechanical, well-specified, low-judgment tasks | formatting, lint fixes, renames, list/status commands | +| **standard** | Most engineering work; moderate reasoning | feature work, refactors, test writing, reviews | +| **heavy** | High-judgment, architectural, ambiguous tasks | architecture, security audits, complex planning | + +How to choose: default to **standard**; drop to **light** only if mechanical and well-specified; raise +to **heavy** only for deep reasoning or high blast radius. Keep tiers abstract — map them to concrete +model IDs in the repo's runtime/config, in one place, never inside skill bodies. + +--- + +## Keep the catalog in sync + +After any create/update, reconcile the repo's catalog (commonly under the docs dir, e.g. a +skills/agents catalog and a commands reference). Add or update the row for the affected skill/agent/ +command: name, one-line description, tier (agents), and the command that invokes it. The catalog must +always match what is on disk. + +--- + +## Templates + +- `templates/SKILL_TEMPLATE.md` — skill scaffold. +- `templates/AGENT_TEMPLATE.md` — agent scaffold. + +Reference them by these relative paths. Adapt the frontmatter to the host repo's local convention +(some repos add `version`, `documentation_url`, or `user-invocable`; match what neighboring files use). + +--- + +## Validation + +- Names are kebab-case, English, unique. +- Frontmatter matches the repo's convention; descriptions are a single line starting with a verb. +- Skills are single-procedure; agents declare a justified tier (no hardcoded vendor model IDs). +- Commands are thin delegators with no embedded logic. +- The catalog under the docs dir reflects every change. + +--- + +## Notes + +- Reason about the repo; never copy a generic kit. +- Propose before creating when scope is broad — confirm the short list with the developer first. +- All references inside the skill are relative; nothing outside the skill root is required at runtime. diff --git a/skills/deepworkplan/author/templates/AGENT_TEMPLATE.md b/skills/deepworkplan/author/templates/AGENT_TEMPLATE.md new file mode 100644 index 0000000..60e8b95 --- /dev/null +++ b/skills/deepworkplan/author/templates/AGENT_TEMPLATE.md @@ -0,0 +1,30 @@ +--- +name: +description: +model: +tools: [Read, Grep, Glob, Edit, Write, Bash] +--- + +# + +## Role + + + +## Inputs + + + +## Process + +1. +2. + +## Output + + + +## Notes + + diff --git a/skills/deepworkplan/author/templates/SKILL_TEMPLATE.md b/skills/deepworkplan/author/templates/SKILL_TEMPLATE.md new file mode 100644 index 0000000..9a043cf --- /dev/null +++ b/skills/deepworkplan/author/templates/SKILL_TEMPLATE.md @@ -0,0 +1,28 @@ +--- +name: +description: +--- + +# + +## Goal + + + +## When to use + + + +## Steps + +1. +2. +3. + +## Validation + + + +## Notes + + diff --git a/skills/deepworkplan/onboard/SKILL.md b/skills/deepworkplan/onboard/SKILL.md index f001b12..02e4995 100644 --- a/skills/deepworkplan/onboard/SKILL.md +++ b/skills/deepworkplan/onboard/SKILL.md @@ -304,7 +304,11 @@ and **stack-appropriate**, not generic boilerplate. `dwp-*` files are the shorter, conventional aliases.) Copy and adapt the ready delegator templates at [`command-templates/`](command-templates/) — one per `dwp-*` command — fixing the `` to where the skill is - installed in the target repo. + 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 ``. - **`.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 @@ -350,12 +354,13 @@ After the core AI-first scaffolding, **enumerate** the available addons under required** — a repo is fully conformant with zero addons. In **trust mode**, you MAY recommend the obviously-applicable ones, but still surface them. -Two addons ship today; enumerate **both** and offer each independently: +Three addons ship today; enumerate **all** and offer each independently: | Addon | Folder | Recommend in trust mode when… | |-------|--------|-------------------------------| | **Devcontainer support** | [`../addons/devcontainer/`](../addons/devcontainer/SKILL.md) | the repo benefits from a reproducible isolated dev container (most repos with Docker/services). | | **Dailybot integration** | [`../addons/dailybot/`](../addons/dailybot/SKILL.md) | the developer/team **already uses Dailybot** or asks for team progress reporting — **do NOT auto-install for everyone**. | +| **Dependency upgrade** | [`../addons/dependency-upgrade/`](../addons/dependency-upgrade/SKILL.md) | the repo has a lockfile + a dependency-heavy stack and wants safe, batched, validated upgrades — recommend only when a lockfile is present; **never auto-install for everyone**. | The first addon is **devcontainer support** ([`../addons/devcontainer/SKILL.md`](../addons/devcontainer/SKILL.md) + @@ -396,6 +401,20 @@ absent, unauthenticated, or unreachable. The core DeepWorkPlan methodology has After applying, run the addon's validation step (SPEC §8). If declined, skip it and continue — the repo stays baseline-conformant. +The third addon is **dependency upgrade** +([`../addons/dependency-upgrade/SKILL.md`](../addons/dependency-upgrade/SKILL.md) + +[`SPEC.md`](../addons/dependency-upgrade/SPEC.md)). It is **package-manager +agnostic** — offer it when the repo has a lockfile and a dependency-heavy stack; +in trust mode recommend it **only** when a lockfile is present, and **never** +auto-install it for everyone. If accepted: read that addon's `SKILL.md` and run +its flow — detect the repo's real package manager (npm/pnpm/yarn + ncu, +pip/poetry/uv, cargo, go mod, bundler, composer…), classify upgrades by semver, +upgrade in safe batches, run the repo's **real** validation gate after each +batch, revert a failing batch, and summarize. **Only when accepted**, the addon +installs a `/lib-upgrade` delegator into the repo's `.agents/commands/`. After +applying, run the addon's validation step (SPEC §9). If declined, skip it — the +repo stays baseline-conformant and no command is installed. + ## Phase 8 — Self-check / validation (mandatory) See the dedicated section below. diff --git a/skills/deepworkplan/onboard/command-templates/agent-create.md b/skills/deepworkplan/onboard/command-templates/agent-create.md new file mode 100644 index 0000000..20589ed --- /dev/null +++ b/skills/deepworkplan/onboard/command-templates/agent-create.md @@ -0,0 +1,20 @@ +--- +description: Author or update a specialized agent in this repo (provided by the installed `deepworkplan` skill) +--- + +# /agent-create — provided by the `deepworkplan` skill + +> Thin alias. The flow lives in the installed `deepworkplan` skill — this file +> only routes to it, so there is a single source of truth and no drift. + +## What to do + +Route this invocation to the **author** sub-skill of the installed `deepworkplan` +skill and follow its **Create an agent** flow: read +`/deepworkplan/author/SKILL.md` and execute it, passing along any +arguments as the agent name/role. Choose a model tier with justification and keep +this repo's `.agents/docs/` catalog in sync. + +> Other agents: invoke the skill's `deepworkplan-author` sub-skill directly +> (`/deepworkplan-author` in Claude Code, `#deepworkplan-author` elsewhere). This +> `agent-create` file is the shorter, conventional alias. diff --git a/skills/deepworkplan/onboard/command-templates/skill-create.md b/skills/deepworkplan/onboard/command-templates/skill-create.md new file mode 100644 index 0000000..c91fe01 --- /dev/null +++ b/skills/deepworkplan/onboard/command-templates/skill-create.md @@ -0,0 +1,20 @@ +--- +description: Author or update a reusable skill in this repo (provided by the installed `deepworkplan` skill) +--- + +# /skill-create — provided by the `deepworkplan` skill + +> Thin alias. The flow lives in the installed `deepworkplan` skill — this file +> only routes to it, so there is a single source of truth and no drift. + +## What to do + +Route this invocation to the **author** sub-skill of the installed `deepworkplan` +skill and follow its **Create a skill** flow: read +`/deepworkplan/author/SKILL.md` and execute it, passing along any +arguments as the skill name/intent. Keep any new command thin and keep this +repo's `.agents/docs/` catalog in sync. + +> Other agents: invoke the skill's `deepworkplan-author` sub-skill directly +> (`/deepworkplan-author` in Claude Code, `#deepworkplan-author` elsewhere). This +> `skill-create` file is the shorter, conventional alias.