diff --git a/.github/docs/WORKFLOWS.md b/.github/docs/WORKFLOWS.md index f252acf..86d1260 100644 --- a/.github/docs/WORKFLOWS.md +++ b/.github/docs/WORKFLOWS.md @@ -7,7 +7,7 @@ piloting this repo) can reason about why a job did or didn't run. | Workflow | File | Purpose | |----------|------|---------| -| Auto-release | [`auto-release.yml`](../workflows/auto-release.yml) | Conventional-commit-driven release + three-way vendored-skill dogfood | +| Auto-release | [`auto-release.yml`](../workflows/auto-release.yml) | Conventional-commit-driven release + temp install smoke + addon dogfood | | CI | [`ci.yml`](../workflows/ci.yml) | Frontmatter validation, shellcheck, bats tests, `setup.sh`/`context.sh` smoke, markdown link check | | PR review | [`pr-review.yml`](../workflows/pr-review.yml) | AI-driven pull request code review via Cursor, `ready`-label gated | @@ -35,18 +35,19 @@ Sequenced steps (a-i below), all in one long-running job on `ubuntu-latest`: | d. Prepend CHANGELOG.md section | Merged commits since last tag become bullets | | e. Commit `chore(release): X.Y.Z [skip ci]` | The `[skip ci]` marker prevents CI from re-running on the release commit | | f. Tag `vX.Y.Z` and push | With `--follow-tags` so commit + tag land atomically | -| g. **Dogfood — self (`deepworkplan`)** | Fetches the just-published tag via `npx --yes skills add DailybotHQ/deepworkplan-skill@vX.Y.Z --skill deepworkplan --force -y` into `.agents/skills/deepworkplan/`. Verifies `SKILL.md` `version:` equals the requested tag. Commits any diff as `chore(release): dogfood vendored deepworkplan to vX.Y.Z [skip release]`. Doubles as a live smoke test — if the release doesn't install cleanly for consumers, this step fails | -| h. **Dogfood — dailybot** | Same pattern for `DailybotHQ/agent-skill` → `.agents/skills/dailybot/`. Only runs if the upstream tag moved. Non-interactive contract (`--yes` + `-y`) is mandatory — dropping either flag hangs the workflow indefinitely on the CLI's agent-picker prompt | -| i. **Dogfood — ai-diff-reviewer** | Same pattern for `DailybotHQ/ai-diff-reviewer` → `.agents/skills/ai-diff-reviewer/`. Same non-interactive contract | -| j. Create GitHub Release | Uses `gh release create` with auto-generated notes; the release notes include the dogfood commits, so downstream consumers see exactly which skills refreshed with this release | +| g. **Smoke — published tag installs (temp dir)** | Runs `npx --yes skills add DailybotHQ/deepworkplan-skill@vX.Y.Z --skill deepworkplan --force -y` into an isolated temp directory and asserts `version:` matches. Does **not** overwrite `.agents/skills/deepworkplan/` (that copy is repo-adapted; sync via `scripts/refresh-dogfood-skill.sh`) | +| h. **Dogfood — dailybot** | `DailybotHQ/agent-skill` → `.agents/skills/dailybot/`. Only commits if the upstream tag moved. Non-interactive contract (`--yes` + `-y`) is mandatory — dropping either flag hangs the workflow indefinitely on the CLI's agent-picker prompt | +| i. **Dogfood — ai-diff-reviewer** | `DailybotHQ/ai-diff-reviewer` → `.agents/skills/ai-diff-reviewer/`. Same non-interactive contract | +| j. Create GitHub Release | Uses `gh release create` with auto-generated notes; the release notes include the addon dogfood commits when those skills moved | ### Failure semantics | Failure | Behavior | |---------|----------| | Version bump script cannot read current version | **Fails** — a corrupt router SKILL.md must be fixed before any release | -| Any `npx skills add` fails during dogfood | **Fails** — a broken upstream tag must never quietly ship inside a release | -| Version-invariant mismatch after install (installed `SKILL.md` `version:` != requested tag) | **Fails** — refuses to commit a misrepresented dogfood snapshot | +| Temp-dir smoke `npx skills add` fails, or installed version ≠ tag | **Fails** — the just-published tag must install cleanly for consumers | +| Any `npx skills add` fails during addon dogfood | **Fails** — a broken upstream tag must never quietly ship inside a release | +| Version-invariant mismatch after addon install (installed `SKILL.md` `version:` != requested tag) | **Fails** — refuses to commit a misrepresented dogfood snapshot | | Upstream `gh release view` fails for one of the two external skills (rate limit, transient outage) | **Fails** — refuses to cut a release whose dogfood snapshot cannot resolve upstream | | Head commit already `chore(release):` OR carries `[skip release]` | Whole workflow skips (loop guard) | @@ -56,8 +57,8 @@ Both `npx --yes` (accepts npm's proceed-with-install prompt) AND `-y` (accepts the `skills` CLI's own "which agent picker?" prompt) are required in the non-TTY GitHub Actions runner. Historically an upstream `ai-diff-reviewer` bug (fixed in v1.7.0) caused the second prompt to hang indefinitely without a -timeout — dropping either flag will hang this workflow. The three dogfood -steps carry both flags; the pattern is: +timeout — dropping either flag will hang this workflow. The temp smoke step +and both addon dogfood steps carry both flags; the pattern is: ```bash npx --yes skills add @ --skill --force -y @@ -162,8 +163,8 @@ push to main pull_request ▼ ▼ auto-release ci.yml pr-review.yml (release + (validate + (scope → labels-bootstrap - three-way smoke) → review → gate) - dogfood) + temp smoke + smoke) → review → gate) + addon dogfood) │ ▼ GitHub Release (with dogfood commits in the notes) diff --git a/.github/workflows/auto-release.yml b/.github/workflows/auto-release.yml index 06d9bf3..abb0058 100644 --- a/.github/workflows/auto-release.yml +++ b/.github/workflows/auto-release.yml @@ -18,11 +18,15 @@ name: Auto-release on merge to main # 4. Prepends a new section to CHANGELOG.md with the merged commits as bullets # 5. Commits as "Dailybot Automations" with `[skip ci]` to break the loop # 6. Tags `vX.Y.Z` and pushes -# 7. Dogfoods the just-published tag by fetching it via `npx skills add` into -# .agents/skills/deepworkplan/ — doubles as a live smoke test of the -# release AND keeps the in-repo dogfood copy at HEAD equal to the latest -# released tag with no manual refresh commits (see Step "Dogfood"). -# 8. Creates a GitHub Release with auto-generated notes +# 7. Smoke-tests that the just-published tag installs cleanly via +# `npx skills add` into a TEMP directory (does NOT overwrite the +# repo-adapted `.agents/skills/deepworkplan/` dogfood copy — that copy +# is synced from `skills/deepworkplan/` via +# `scripts/refresh-dogfood-skill.sh` when contributors need it). +# 8. Dogfoods the latest upstream tags of the two *addon* skills +# (`dailybot`, `ai-diff-reviewer`) into `.agents/skills/` — those are +# safe to pin blindly; deepworkplan is not. +# 9. Creates a GitHub Release with auto-generated notes on: push: @@ -188,22 +192,15 @@ jobs: git tag -a "$NEW_TAG" -m "Release ${NEW_VERSION}" git push origin "refs/tags/${NEW_TAG}" - - name: Dogfood — refresh vendored deepworkplan from the just-published tag - # This repo dogfoods its own skill: `.agents/skills/deepworkplan/` is a - # vendored copy managed via `skills-lock.json`, fetched exactly the way - # any consumer would install it (`npx skills add`). Refreshing right - # after the tag lands serves three purposes: - # 1. Live smoke test — proves the just-pushed tag actually installs - # cleanly via `npx skills`. If the install script or the tag - # layout is broken, the workflow fails HERE (loudly) instead of a - # consumer discovering it silently. - # 2. Keeps the in-repo dogfood copy at HEAD equal to the latest - # release (rather than the release before the one we just cut), so - # any contributor cloning fresh gets the current skill by default. - # 3. Refreshes `skills-lock.json` with the new content hash so - # restore/verify flows stay accurate. - # The commit message carries `[skip release]` so this push does NOT - # re-trigger this workflow (the `if:` guard on the job catches it). + - name: Smoke — prove the just-published tag installs (temp dir only) + # Live smoke test of the just-cut tag via `npx skills add`, but into + # an isolated temp directory — NEVER into this repo's + # `.agents/skills/deepworkplan/`. That dogfood copy is repo-adapted + # (contributor kit wiring for Dailybot + AI Diff Reviewer addons) + # and is synced from `skills/deepworkplan/` via + # `scripts/refresh-dogfood-skill.sh` when intentionally refreshed. + # Blind reinstall from the published tag would overwrite that + # adaptation. if: steps.version.outputs.skip != 'true' env: NEW_TAG: ${{ steps.version.outputs.new_tag }} @@ -216,61 +213,47 @@ jobs: # instant; the REST/graphql surface occasionally lags a few seconds). sleep 5 - # Pin to the exact tag we just cut instead of letting `skills` - # resolve "the newest matching tag". If the tag isn't visible yet - # (propagation lag, publish failure), `npx skills add @` fails - # loudly here — that's the whole point of the smoke test. A silent - # "already up to date" would let a broken release slip through. - # - # Two separate `-y` / `--yes` flags below — they mean different - # things and both are required in a non-TTY (Actions) environment: + SMOKE_DIR=$(mktemp -d) + cleanup() { rm -rf "$SMOKE_DIR"; } + trap cleanup EXIT + + # Minimal project so `skills` has a place to install into. + git -C "$SMOKE_DIR" init -q + printf '%s\n' '{"name":"dwp-smoke","private":true}' > "$SMOKE_DIR/package.json" + + # Two separate `-y` / `--yes` flags — both required in a non-TTY + # (Actions) environment: # * `npx --yes` — auto-installs the `skills` npm package without # the "Ok to proceed?" download prompt. # * `skills add ... -y` — auto-selects the default install targets # without the interactive agent-picker. - echo "::group::npx skills add DailybotHQ/deepworkplan-skill@${NEW_TAG} --skill deepworkplan --force -y" - npx --yes skills add "DailybotHQ/deepworkplan-skill@${NEW_TAG}" \ - --skill deepworkplan --force -y + echo "::group::smoke: npx skills add DailybotHQ/deepworkplan-skill@${NEW_TAG} (temp dir)" + ( + cd "$SMOKE_DIR" + npx --yes skills add "DailybotHQ/deepworkplan-skill@${NEW_TAG}" \ + --skill deepworkplan --force -y + ) echo "::endgroup::" - # Explicit invariant: the vendored SKILL.md's `version:` field MUST - # equal the tag we just published. If it doesn't, `npx skills` - # accepted the fetch but installed the wrong content — fail hard - # rather than commit a misrepresented "dogfood" state. - VENDORED_VERSION=$( + INSTALLED=$( sed -nE 's/^version:[[:space:]]*"([^"]+)".*/\1/p' \ - .agents/skills/deepworkplan/SKILL.md | head -n1 + "$SMOKE_DIR/.agents/skills/deepworkplan/SKILL.md" | head -n1 ) - if [ "${VENDORED_VERSION}" != "${NEW_VERSION}" ]; then - echo "::error::Vendored SKILL.md version is '${VENDORED_VERSION}'" + if [ "${INSTALLED}" != "${NEW_VERSION}" ]; then + echo "::error::Smoke-install SKILL.md version is '${INSTALLED}'" echo "::error::but the just-published tag is '${NEW_TAG}'" echo "::error::(expected frontmatter '${NEW_VERSION}')." - echo "::error::Refusing to commit a stale dogfood snapshot." exit 1 fi - echo "OK: vendored deepworkplan at ${NEW_TAG} (verified)" - - # Empty diff after `--force` with a matching version assertion means - # the working copy was already at this tag — no commit needed - # (idempotent), but the smoke test PASSED (pinned fetch + version - # check both succeeded). - if git diff --quiet -- .agents/skills/deepworkplan skills-lock.json; then - echo "Vendored deepworkplan already at ${NEW_TAG}; nothing to commit." - exit 0 - fi - - git add .agents/skills/deepworkplan skills-lock.json - git commit -m "chore(release): dogfood vendored deepworkplan to ${NEW_TAG} [skip release]" - git push origin HEAD:main + echo "OK: published tag ${NEW_TAG} installs cleanly (temp smoke; repo dogfood untouched)" - name: Dogfood — refresh vendored dailybot to latest upstream # Keep the vendored `.agents/skills/dailybot/` at the latest published # tag of `DailybotHQ/agent-skill`. Runs on every release we cut so any # consumer cloning this repo at HEAD picks up the current dailybot - # skill alongside deepworkplan. + # skill alongside the repo-adapted deepworkplan dogfood. # - # Mirror of the deepworkplan self-dogfood, adapted to a THIRD-PARTY - # upstream: no `sleep 5` here — those upstream tags are stable and + # Third-party upstream: no `sleep 5` here — those tags are stable and # already propagated through the API layer, so there's no # just-published race to wait out. # diff --git a/.review/extension.md b/.review/extension.md index bcad0b1..a7340ef 100644 --- a/.review/extension.md +++ b/.review/extension.md @@ -101,12 +101,16 @@ silent pass. Addons and CI may change; the core loop must not. `skills/deepworkplan/` — that's what `skills.sh` ships. See AGENTS.md Rule #2 ("The runtime artifact is `skills/deepworkplan/` — keep it pure"). `docs/`, `tests/`, `scripts/`, and `.github/` are dev-time only. -- **Always `critical`:** a hand-edit of `version:` in any `SKILL.md`, - `CHANGELOG.md`, a git tag, or the vendored dogfood copy at - `.agents/skills/deepworkplan/**`. The `auto-release.yml` workflow OWNS - those and re-writes them on every merge to `main`; a manual bump collides - with the next release commit and duplicates changelog sections. See - AGENTS.md Rule #4 ("Versioning is automatic — write good commits"). +- **Always `critical`:** a hand-edit of `version:` in any `SKILL.md` under + `skills/deepworkplan/**`, `CHANGELOG.md`, or a git tag. The + `auto-release.yml` workflow OWNS those and re-writes them on every merge + to `main`; a manual bump collides with the next release commit and + duplicates changelog sections. See AGENTS.md Rule #4 ("Versioning is + automatic — write good commits"). (The dogfood copy at + `.agents/skills/deepworkplan/**` is synced via + `scripts/refresh-dogfood-skill.sh`, not by auto-release — flag + unreviewed drift from `skills/deepworkplan/` as `warning`, not a + versioning critical.) - **Always `critical`:** a sub-skill `SKILL.md` frontmatter `version:` that drifts from the router `skills/deepworkplan/SKILL.md` `version:` on any commit that touches the router. Every in-tree @@ -221,9 +225,11 @@ silent pass. Addons and CI may change; the core loop must not. (see methodology criticals above). - **Always `warning`:** documentation change to `skills/deepworkplan/**` (spec, guide, addon SKILL.md, or router SKILL.md) that is not mirrored - into either the vendored dogfood copy at `.agents/skills/deepworkplan/**` - or explicitly deferred to the next auto-release. Consumers install from - the vendored copy — drift means agents in the wild read stale guidance. + into the vendored dogfood copy at `.agents/skills/deepworkplan/**` via + `scripts/refresh-dogfood-skill.sh` (or explicitly deferred in the PR). + Contributors working in this repo read the dogfood copy — drift means + agents piloting *this* repo see stale guidance. (End users install from + the published `skills/deepworkplan/` pack, not from `.agents/`.) - **Always `warning`:** RFC-2119 keyword usage in `spec/*.md` that isn't uppercase (must / must not / should — should be MUST / MUST NOT / SHOULD). The spec is a normative document; lowercase RFC keywords in @@ -267,12 +273,13 @@ silent pass. Addons and CI may change; the core loop must not. checksum + smoke jobs on `ubuntu-latest` and `macos-latest`. There is no per-SKILL.md unit-test convention; prompt behaviour is verified by running the skill end-to-end. -- Any content inside `.agents/skills/dailybot/**`, - `.agents/skills/ai-diff-reviewer/**`, or `.agents/skills/deepworkplan/**`. - These are vendored copies — updated automatically by `auto-release.yml` - (deepworkplan self-dogfood) and by `npx skills update` (the two addon - skills). Hand-editing them is a bug; the real source is upstream. See - DON'T list in AGENTS.md Rule #10 pillar (B). +- Any content inside `.agents/skills/dailybot/**` or + `.agents/skills/ai-diff-reviewer/**`. These are vendored addon copies — + refreshed by `auto-release.yml` from upstream. Hand-editing them is a + bug; the real source is upstream. See AGENTS.md → Vendored agent skills. + (`.agents/skills/deepworkplan/**` is repo-adapted dogfood synced from + `skills/deepworkplan/` via `scripts/refresh-dogfood-skill.sh` — review + drift as a warning, don't treat auto-release as its owner.) - Content in `.claude/**` or `CLAUDE.md`. Those are symlinks (`.claude → .agents`, `CLAUDE.md → AGENTS.md`); any real edit belongs at the canonical `.agents/**` and `AGENTS.md` target. @@ -340,7 +347,8 @@ task files. commit-type prefix on merges to `main` (`feat!:` MAJOR, `feat:` MINOR, everything else PATCH), bumps every in-tree `skills/deepworkplan/**/SKILL.md` in sync (router + sub-skills + all addons), updates `CHANGELOG.md`, tags - `vX.Y.Z`, and re-vendors the dogfood copy. + `vX.Y.Z`, smoke-tests the published tag in a temp dir, and auto-refreshes + only the addon dogfood copies (`dailybot`, `ai-diff-reviewer`). - **Addons.** Live under `skills/deepworkplan/addons//`. Every addon ships four things: `SPEC.md` (RFC-2119), `templates/*` (reasoning guides), `SKILL.md` (onboarding hook, `user-invocable`), @@ -350,11 +358,11 @@ task files. - **Canonical vs symlinked paths.** `.agents/` is canonical. `.claude/` and `.cursor/` are back-compat symlinks. Write new content to `.agents/`; the symlinks continue to work for legacy tooling. -- **Two DWP dogfoods.** This repo installs its own `deepworkplan` skill - vendored at `.agents/skills/deepworkplan/` (kept in sync by - `auto-release.yml`) AND — after Task 3 of the current AI-Diff-Reviewer - plan — also vendors `dailybot` and `ai-diff-reviewer` under the same - tree. All three are pinned in `skills-lock.json`. +- **Three dogfood copies under `.agents/skills/`.** `deepworkplan` is + repo-adapted and synced from `skills/deepworkplan/` via + `scripts/refresh-dogfood-skill.sh` (not by auto-release). `dailybot` + and `ai-diff-reviewer` are auto-refreshed on every release. All three + are pinned in `skills-lock.json`. - **Branding.** Product name is exactly **DeepWorkPlan** (one word, CamelCase) or **DWP** (abbreviation). Slug is `deepworkplan`. The skill package name on the marketplace is `DailybotHQ/deepworkplan-skill`. Do NOT diff --git a/AGENTS.md b/AGENTS.md index 7471c7f..72f0c06 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -88,7 +88,7 @@ deepworkplan-skill/ ├── CONTRIBUTING.md ← human contributor guide (NOT installed) ├── .vscode_example/ ← shared editor settings template (NOT installed) ├── .github/ -│ ├── workflows/auto-release.yml ← conventional-commit auto-release + three-way dogfood (NOT installed) +│ ├── workflows/auto-release.yml ← conventional-commit auto-release + addon dogfood (NOT installed) │ ├── workflows/ci.yml ← frontmatter + shellcheck + bats + smoke (NOT installed) │ ├── workflows/pr-review.yml ← Cursor-based AI Diff Reviewer, ready-label gated (NOT installed) │ ├── docs/WORKFLOWS.md ← per-workflow reference (Trigger / Jobs / Gate / Failures) (NOT installed) @@ -96,10 +96,10 @@ deepworkplan-skill/ │ ├── ISSUE_TEMPLATE/ ← bug_report + feature_request + config.yml (NOT installed) │ └── markdown-link-check.json ← link-check config (NOT installed) ├── .agents/skills/ ← THREE vendored dogfood copies (NOT installed on end-user machines) -│ ├── deepworkplan/ ← this repo's OWN skill, vendored via auto-release Step 5 -│ ├── dailybot/ ← DailybotHQ/agent-skill vendored copy -│ └── ai-diff-reviewer/ ← DailybotHQ/ai-diff-reviewer vendored copy -├── skills-lock.json ← pinned versions/hashes for the three vendored skills (NOT installed) +│ ├── deepworkplan/ ← repo-adapted copy of this skill (sync via scripts/refresh-dogfood-skill.sh; NOT auto-overwritten on release) +│ ├── 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) @@ -198,8 +198,7 @@ unquoted `version`. ### 4. Versioning is automatic — write good commits -You do **not** edit `version:` fields, `CHANGELOG.md`, git tags, or the -vendored dogfood copy at `.agents/skills/deepworkplan/` by hand. +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` @@ -210,19 +209,23 @@ The `auto-release.yml` workflow runs on every merge to `main` and: - `feat(scope):` → **MINOR** - everything else (`fix:`, `chore:`, no prefix, etc.) → **PATCH** 4. Bumps `version:` in **all** SKILL.md files in sync (router + six sub-skills - + addon), prepends a section to `CHANGELOG.md`, commits as + + addons), prepends a section to `CHANGELOG.md`, commits as `chore(release): X.Y.Z [skip ci]`, tags `vX.Y.Z`, and pushes. -5. **Dogfoods the just-published tag** — fetches - `DailybotHQ/deepworkplan-skill@vX.Y.Z` via `npx skills add` into - `.agents/skills/deepworkplan/`, verifies the vendored `SKILL.md` version - matches, and commits any diff (plus `skills-lock.json`) as - `chore(release): dogfood vendored deepworkplan to vX.Y.Z [skip release]`. - This doubles as a live smoke test — if the release doesn't install - cleanly for consumers, the workflow fails HERE. Contributors never - hand-refresh the vendored copy anymore. -6. Creates a GitHub Release with auto-generated notes and the SHA256SUMS +5. **Smoke-tests the just-published tag** — runs `npx skills add + DailybotHQ/deepworkplan-skill@vX.Y.Z` into a **temp directory** and asserts + the installed `version:` matches. This proves the release installs for + consumers **without** overwriting the repo-adapted dogfood copy at + `.agents/skills/deepworkplan/`. +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). `deepworkplan` is intentionally excluded. +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 — never rely on auto-release to do it. + What this means for you: - Write meaningful commit messages with the right `():` prefix. @@ -347,20 +350,26 @@ Multiple AI agents may work on this repo simultaneously. They all read this ## Vendored agent skills — three dogfood copies under `.agents/skills/` -This repo now vendors **three** agent skills under `.agents/skills/`, all -tracked in git and pinned via [`skills-lock.json`](skills-lock.json). They are -the exact same artifacts a downstream consumer would install via -`npx skills add`, kept in-repo so any AI agent that clones this repo — or that -runs `.agents/`-aware tooling on it — gets the current snapshot of the entire -toolchain the DWP methodology recommends: - -| Vendored skill | Upstream | Purpose in this repo | -|----------------|----------|----------------------| -| `.agents/skills/deepworkplan/` | [`DailybotHQ/deepworkplan-skill`](https://github.com/DailybotHQ/deepworkplan-skill) (this repo) | **Self-dogfood** — proves each release installs cleanly and gives contributors the DWP methodology while working here | -| `.agents/skills/dailybot/` | [`DailybotHQ/agent-skill`](https://github.com/DailybotHQ/agent-skill) | Powers Dailybot standup reporting for plan lifecycle events (see the Dailybot addon) | -| `.agents/skills/ai-diff-reviewer/` | [`DailybotHQ/ai-diff-reviewer`](https://github.com/DailybotHQ/ai-diff-reviewer) | Powers the local pre-push code review AND the `pr-review.yml` CI Action (same `prompt.md`) | - -**How they stay fresh.** [`.github/workflows/auto-release.yml`](.github/workflows/auto-release.yml) +This repo vendors **three** agent skills under `.agents/skills/`, all tracked +in git and pinned via [`skills-lock.json`](skills-lock.json). They give any AI +agent that clones this repo the toolchain the DWP methodology recommends — +but they are managed differently on purpose: + +| Vendored skill | Upstream | Release auto-refresh | Purpose in this repo | +|----------------|----------|----------------------|----------------------| +| `.agents/skills/deepworkplan/` | this repo (`skills/deepworkplan/`) | **No** | Repo-adapted contributor dogfood (DWP + Dailybot + AI Diff Reviewer wiring). Sync with `bash scripts/refresh-dogfood-skill.sh` when intentionally refreshing. | +| `.agents/skills/dailybot/` | [`DailybotHQ/agent-skill`](https://github.com/DailybotHQ/agent-skill) | **Yes** | Powers Dailybot standup reporting for plan lifecycle events (see the Dailybot addon) | +| `.agents/skills/ai-diff-reviewer/` | [`DailybotHQ/ai-diff-reviewer`](https://github.com/DailybotHQ/ai-diff-reviewer) | **Yes** | Powers the local pre-push code review AND the `pr-review.yml` CI Action (same `prompt.md`) | + +**Why deepworkplan is excluded.** Blind `npx skills add --force` of this +repo's own skill into `.agents/skills/deepworkplan/` would overwrite the +repo-adapted dogfood copy. The release workflow still **smoke-tests** that +the published tag installs (into a temp directory); it does not commit that +install back into the tree. When the shipped pack under `skills/deepworkplan/` +changes and the dogfood copy should follow, run +`bash scripts/refresh-dogfood-skill.sh`, review, and commit. + +**How addon refresh works.** [`.github/workflows/auto-release.yml`](.github/workflows/auto-release.yml) runs on every merge to `main` and, after cutting the release for this repo, resolves the latest published tags of `agent-skill` and `ai-diff-reviewer` (via `gh release view`), compares to the vendored `SKILL.md` `version:`, and @@ -378,10 +387,13 @@ If any file changes, the workflow commits `chore(release): dogfood vendored to v [skip release]` and pushes. The `[skip release]` marker prevents an infinite auto-release loop. -**Do not hand-edit files under `.agents/skills/deepworkplan/`, `.agents/skills/dailybot/`, -or `.agents/skills/ai-diff-reviewer/`.** The next release cut will overwrite -your changes. Contribute upstream first, land a release there, then the -`auto-release` job here will refresh the vendored copy on its next run. +**Editing policy.** +- **Do not** hand-edit `.agents/skills/dailybot/` or `.agents/skills/ai-diff-reviewer/` + — the next release will overwrite those. Contribute upstream, land a release + there, then this repo's auto-release picks them up. +- **Do** treat `.agents/skills/deepworkplan/` as repo-adapted: refresh it only + via `scripts/refresh-dogfood-skill.sh` (or an explicit reviewed edit), never + via release dogfood. ## PR review workflow — Cursor-based, `ready`-label gated (Action `@v2`) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 58069ce..c7d00ab 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -220,8 +220,16 @@ Every merge to `main` triggers `auto-release.yml`, which: 4. Syncs the new version into **all** SKILL.md files (router + six sub-skills + addons). 5. Prepends a section to `CHANGELOG.md` listing the merged commits. -6. Commits as `chore(release): X.Y.Z [skip ci]`, tags `vX.Y.Z`, creates a GitHub - Release. +6. Commits as `chore(release): X.Y.Z [skip ci]`, tags `vX.Y.Z`. +7. Smoke-tests that the published tag installs via `npx skills add` into a + **temp directory** (does not overwrite `.agents/skills/deepworkplan/`). +8. Auto-refreshes only the addon dogfood copies (`.agents/skills/dailybot/` + and `.agents/skills/ai-diff-reviewer/`) to their latest upstream tags. +9. Creates a GitHub Release with auto-generated notes. + +To refresh the repo-adapted `deepworkplan` dogfood after changing +`skills/deepworkplan/`, run `bash scripts/refresh-dogfood-skill.sh`, review, +and commit on a PR. So your commit messages directly determine the release version. Use the format documented in [`AGENTS.md`](AGENTS.md) → "Commit Message Format": diff --git a/scripts/refresh-dogfood-skill.sh b/scripts/refresh-dogfood-skill.sh index 9930338..aceebd1 100755 --- a/scripts/refresh-dogfood-skill.sh +++ b/scripts/refresh-dogfood-skill.sh @@ -3,7 +3,18 @@ set -euo pipefail # Sync the shipped skill pack (skills/deepworkplan/) into the dogfood # location (.agents/skills/deepworkplan/) so this repo eats its own -# cooking. Run after any change to files under skills/deepworkplan/. +# cooking. +# +# This is the ONLY supported way to refresh the in-repo deepworkplan +# dogfood copy. auto-release.yml deliberately does NOT overwrite +# `.agents/skills/deepworkplan/` via `npx skills add` — that copy is +# repo-adapted for contributors (Dailybot + AI Diff Reviewer addon +# wiring). Addon skills (`dailybot`, `ai-diff-reviewer`) ARE +# auto-refreshed on release; deepworkplan is not. +# +# Run after any intentional change under skills/deepworkplan/ that +# should also land in the contributor dogfood copy. Review the diff +# before committing. REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)" SRC="$REPO_ROOT/skills/deepworkplan"