diff --git a/.agents/docs/skills_agents_catalog.md b/.agents/docs/skills_agents_catalog.md index be8ccec..cf0abe9 100644 --- a/.agents/docs/skills_agents_catalog.md +++ b/.agents/docs/skills_agents_catalog.md @@ -356,6 +356,7 @@ All skills and agents are adapted for this Astro repository: - [DeepWorkPlan skill (dwp-* flows)](../skills/deepworkplan/SKILL.md) — backs `/dwp-create`, `/dwp-execute`, `/dwp-refine`, `/dwp-resume`, `/dwp-status` - [Dependency-upgrade add-on](../skills/deepworkplan/addons/dependency-upgrade/SKILL.md) — opt-in maintenance add-on shipped with the `deepworkplan` skill; backs `/lib-upgrade` (package-manager agnostic, validated revertible batches) - [Design-system add-on](../skills/deepworkplan/addons/design-system/SKILL.md) — opt-in, frontend-scoped add-on shipped with the `deepworkplan` skill; generates a `docs/DESIGN.md` (indexed from `AGENTS.md`) from the repo's real design tokens so agents produce on-brand UI; default-on when a design system is detected. This repo dogfoods it: see [docs/DESIGN.md](../../docs/DESIGN.md) -- [Dailybot add-on](../skills/deepworkplan/addons/dailybot/SKILL.md) — opt-in team-visibility add-on shipped with the `deepworkplan` skill; this repo dogfoods it: the official `dailybot` skill ([DailybotHQ/agent-skill](https://github.com/DailybotHQ/agent-skill)) is installed alongside `deepworkplan` under `.agents/skills/` (gitignored), and DWP work emits lifecycle agent updates (kickoff / significant task / blocked / completion milestone) per the addon SPEC — best-effort, never blocking (see AGENTS.md §Shared Agent Coordination) +- [Dailybot add-on](../skills/deepworkplan/addons/dailybot/SKILL.md) — opt-in team-visibility add-on shipped with the `deepworkplan` skill; this repo dogfoods it: the official `dailybot` skill ([DailybotHQ/agent-skill](https://github.com/DailybotHQ/agent-skill)) is vendored under `.agents/skills/dailybot/` (auto-refreshed on website release), and DWP work emits lifecycle agent updates (kickoff / significant task / blocked / completion milestone) per the addon SPEC — best-effort, never blocking (see AGENTS.md §Shared Agent Coordination) +- [AI Diff Reviewer add-on](../skills/deepworkplan/addons/ai-diff-reviewer/SKILL.md) — opt-in structured-review add-on; this repo dogfoods **Flow B** (local skill + CI Action): vendored `.agents/skills/ai-diff-reviewer/` (auto-refreshed on website release), `.review/extension.md`, and [`.github/workflows/pr-review.yml`](../../.github/workflows/pr-review.yml). Augments the mandatory Security Review when both the skill and an extension file are present (see AGENTS.md §PR review workflow) - [AGENTS.md](../../AGENTS.md) - Main AI agent guidance - [docs/STANDARDS.md](../../docs/STANDARDS.md) - Coding standards diff --git a/.github/docs/WORKFLOWS.md b/.github/docs/WORKFLOWS.md index e26eadc..daf8937 100644 --- a/.github/docs/WORKFLOWS.md +++ b/.github/docs/WORKFLOWS.md @@ -144,7 +144,7 @@ Extracts the PR's size label and maps to emoji for the workflow summary. |------|------|-------------| | 0-0a | Cache | pnpm store, keyed on `pnpm-lock.yaml` | | 1 | Setup GitHub Config | Git config | -| 1a | **Dogfood — refresh vendored agent skills** | Resolves the latest tag of `DailybotHQ/deepworkplan-skill`, `DailybotHQ/agent-skill`, and `DailybotHQ/ai-diff-reviewer` via `gh release view`, and if any is newer than the vendored copy under `.agents/skills/`, runs `npx --yes skills add @ --skill --force -y`, asserts the version invariant, and commits `chore: dogfood vendored skills to (…)`. **Runs before Step 2** so the dogfood commit lands in the release notes. See "Dogfood step" below for details. | +| 1a | **Dogfood — refresh addon skills** | Resolves the latest tag of `DailybotHQ/agent-skill` and `DailybotHQ/ai-diff-reviewer` via `gh release view`, and if either is newer than the vendored copy under `.agents/skills/`, runs `npx --yes skills add @ --skill --force -y`, asserts the version invariant, and commits `chore: dogfood vendored skills to (…)`. **Does not touch `deepworkplan`** (repo-adapted). **Runs before Step 2** so the dogfood commit lands in the release notes. See "Dogfood step" below for details. | | 2 | Release notes | Runs `scripts/get_github_release_log.sh` — includes the dogfood commit from Step 1a if it exists | | 3 | Prepare release | `corepack pnpm install --frozen-lockfile && corepack pnpm run release` + push tags to main (pushes the dogfood commit alongside the version-bump commit + tag in one atomic push) | | 4 | Get release tag | Extract latest tag | @@ -159,27 +159,29 @@ Extracts the PR's size label and maps to emoji for the workflow summary. #### Dogfood step (Step 1a) -**Purpose.** Every website release should ship with a current snapshot of the three agent skills it documents. Rather than a scheduled/autonomous refresh, the update happens **exactly when the maintainer decides to cut a release** — no background cron, no drift between "when a skill dropped" and "when someone releases the site". +**Purpose.** Every website release should ship with a current snapshot of the **addon** skills (`dailybot`, `ai-diff-reviewer`). Rather than a scheduled/autonomous refresh, the update happens **exactly when the maintainer decides to cut a release** — no background cron. + +**Intentional exclusion — `deepworkplan`.** The DWP skill under `.agents/skills/deepworkplan/` is **repo-adapted** and is **not** auto-refreshed. A blind `skills add --force` would overwrite local adaptation. Update it only via an explicit, reviewed change that re-adapts it to this repository (see AGENTS.md → Vendored agent skills). **What runs.** -1. `gh release view --repo --json tagName -q .tagName` for each of `DailybotHQ/deepworkplan-skill`, `DailybotHQ/agent-skill`, and `DailybotHQ/ai-diff-reviewer` to resolve the latest tag. -2. Reads the currently vendored versions from `.agents/skills/{deepworkplan,dailybot,ai-diff-reviewer}/SKILL.md` frontmatter. -3. Per-skill "moved" flag → only installs the skills that actually changed. Commits and PR titles list only the moved skills (no misleading "dogfood to deepworkplan vX, dailybot vY, ai-diff-reviewer vZ" when only one moved). +1. `gh release view --repo --json tagName -q .tagName` for `DailybotHQ/agent-skill` and `DailybotHQ/ai-diff-reviewer` to resolve the latest tag. +2. Reads the currently vendored versions from `.agents/skills/{dailybot,ai-diff-reviewer}/SKILL.md` frontmatter (and reports the pinned `deepworkplan` version in the step summary for visibility only). +3. Per-skill "moved" flag → only installs the addon skills that actually changed. Commit subjects list only the moved skills. 4. `npx --yes skills add @ --skill --force -y` — exact same command any downstream consumer would run. Serves as a live smoke test that the upstream release is installable. Both `--yes` AND `-y` are required — the former covers npm's own proceed prompt, the latter covers the `skills` CLI's agent-picker prompt; dropping either hangs the workflow in a non-TTY runner. 5. Version invariant: the installed `SKILL.md` frontmatter `version:` MUST equal the requested tag. Fails the release if not — refuses to publish a website tag that misrepresents its vendored skills. -6. If any files changed, commits `chore: dogfood vendored skills to ` locally. Step 3's `git push --follow-tags` sends this commit alongside the version-bump commit and the tag in a single atomic push. +6. If any files changed, commits `chore: dogfood vendored skills to ` locally. Step 3's `git push --follow-tags` sends this commit alongside the version-bump commit and the tag in a single atomic push. Staging paths are limited to `.agents/skills/dailybot`, `.agents/skills/ai-diff-reviewer`, and `skills-lock.json`. **Failure semantics.** | Failure | Behavior | |---------|----------| -| `gh release view` fails for one upstream repo (rate limit, transient outage) | Warns; skips that skill. The other two skills (and the release) proceed. | +| `gh release view` fails for one upstream repo (rate limit, transient outage) | Warns; skips that skill. The other auto-refreshed skill (and the release) proceed. | | `npx skills add` fails | **Fails the release** — real upstream breakage, must be surfaced. | | Version invariant mismatch after install | **Fails the release** — refuses to commit a misrepresented dogfood snapshot. | -| All three skills already at latest | Clean no-op — no dogfood commit, release proceeds. | +| Both auto-refreshed addon skills already at latest | Clean no-op — no dogfood commit, release proceeds. | -**Manual refresh outside of a release.** Not supported by design. If a maintainer needs to bump a vendored skill without cutting a full release, do it locally (`npx skills add @`) on a PR branch and merge it as a normal `chore:` change — that will trigger a release naturally. +**Manual refresh outside of a release.** For addons: do it locally (`npx skills add @`) on a PR branch and merge as a normal `chore:` change — that will trigger a release naturally. For `deepworkplan`: never rely on release dogfood; re-adapt deliberately on a reviewed PR. ### Job 3: `cleanup_caches` (depends on: Job 2) diff --git a/.github/workflows/release_and_publish.yml b/.github/workflows/release_and_publish.yml index 249a3c0..3c926fd 100644 --- a/.github/workflows/release_and_publish.yml +++ b/.github/workflows/release_and_publish.yml @@ -97,14 +97,17 @@ jobs: git config user.name "deepworkplan-bot" git config user.email "bot@deepworkplan.com" git config advice.skippedCherryPicks false - - name: Step 1a - 🐕 Dogfood — refresh vendored agent skills to latest upstream - # Before every website release, bring the three vendored skills under - # `.agents/skills/` up to their latest published upstream tags — + - name: Step 1a - 🐕 Dogfood — refresh addon skills to latest upstream + # Before every website release, bring the two *addon* vendored skills + # under `.agents/skills/` up to their latest published upstream tags — # so `vX.Y.Z` of this site always ships with a current snapshot of - # `deepworkplan`, `dailybot`, and `ai-diff-reviewer`. Mirrors the - # "Dogfood" step in DailybotHQ/deepworkplan-skill's own - # `auto-release.yml`, adapted to install third-party upstream tags - # instead of this repo's own. + # `dailybot` and `ai-diff-reviewer`. + # + # INTENTIONAL EXCLUSION: `deepworkplan` is NOT refreshed here. The + # DWP skill in this repo is repo-adapted (onboarded kit + local + # wiring); a blind `skills add --force` would overwrite that + # adaptation. Update `.agents/skills/deepworkplan/` only via an + # explicit, reviewed change that re-adapts it to this repository. # # This step runs BEFORE Step 2 on purpose: `get_github_release_log.sh` # in Step 2 collects commit subjects from the previous release @@ -119,7 +122,7 @@ jobs: # * `npx skills add` failure OR version-invariant mismatch → # FAIL the release (we should not publish a website tag that # misrepresents which skill versions it vendors). - # * All three skills already at latest → clean no-op, release + # * Both addon skills already at latest → clean no-op, release # proceeds normally without a dogfood commit. env: GH_TOKEN: ${{ secrets.AUTOMATION_GITHUB_TOKEN }} @@ -169,7 +172,6 @@ jobs: fi } - DWP_TAG=$(resolve DailybotHQ/deepworkplan-skill deepworkplan) DB_TAG=$(resolve DailybotHQ/agent-skill dailybot) AIDR_TAG=$(resolve DailybotHQ/ai-diff-reviewer ai-diff-reviewer) @@ -180,36 +182,33 @@ jobs: # Only install skills that would actually change — no wasted work # and no misleading dogfood commit when one skill is at latest # and another is not. - DWP_MOVED=false DB_MOVED=false AIDR_MOVED=false - [ -n "$DWP_TAG" ] && [ "$DWP_CUR" != "${DWP_TAG#v}" ] && DWP_MOVED=true [ -n "$DB_TAG" ] && [ "$DB_CUR" != "${DB_TAG#v}" ] && DB_MOVED=true [ -n "$AIDR_TAG" ] && [ "$AIDR_CUR" != "${AIDR_TAG#v}" ] && AIDR_MOVED=true - [ "$DWP_MOVED" = "true" ] && install_and_verify DailybotHQ/deepworkplan-skill deepworkplan .agents/skills/deepworkplan "$DWP_TAG" [ "$DB_MOVED" = "true" ] && install_and_verify DailybotHQ/agent-skill dailybot .agents/skills/dailybot "$DB_TAG" [ "$AIDR_MOVED" = "true" ] && install_and_verify DailybotHQ/ai-diff-reviewer ai-diff-reviewer .agents/skills/ai-diff-reviewer "$AIDR_TAG" # Stage only the paths the installer is allowed to touch. + # deepworkplan is intentionally omitted — see step comment above. git add \ - .agents/skills/deepworkplan \ .agents/skills/dailybot \ .agents/skills/ai-diff-reviewer \ skills-lock.json 2>/dev/null || true if git diff --cached --quiet; then - echo "Vendored skills already at latest — no dogfood commit needed." + echo "Addon skills already at latest — no dogfood commit needed." { echo "## Vendored skills" echo "" - echo "| Skill | Vendored | Latest upstream | Moved? |" - echo "| --- | --- | --- | --- |" - echo "| deepworkplan | v${DWP_CUR} | ${DWP_TAG:-_(unresolved)_} | ${DWP_MOVED} |" - echo "| dailybot | v${DB_CUR} | ${DB_TAG:-_(unresolved)_} | ${DB_MOVED} |" - echo "| ai-diff-reviewer | v${AIDR_CUR} | ${AIDR_TAG:-_(unresolved)_} | ${AIDR_MOVED} |" + echo "| Skill | Vendored | Latest upstream | Auto-refreshed? | Moved? |" + echo "| --- | --- | --- | --- | --- |" + echo "| deepworkplan | v${DWP_CUR} | _(manual — repo-adapted)_ | no | — |" + echo "| dailybot | v${DB_CUR} | ${DB_TAG:-_(unresolved)_} | yes | ${DB_MOVED} |" + echo "| ai-diff-reviewer | v${AIDR_CUR} | ${AIDR_TAG:-_(unresolved)_} | yes | ${AIDR_MOVED} |" echo "" - echo "**No dogfood commit** — vendored copies already match the latest upstream releases." + echo "**No dogfood commit** — auto-refreshed addon copies already match the latest upstream releases." } >> "$GITHUB_STEP_SUMMARY" exit 0 fi @@ -219,7 +218,6 @@ jobs: # so build the joined string by hand to preserve "a, b" (with the # space). parts=() - [ "$DWP_MOVED" = "true" ] && parts+=("deepworkplan ${DWP_TAG}") [ "$DB_MOVED" = "true" ] && parts+=("dailybot ${DB_TAG}") [ "$AIDR_MOVED" = "true" ] && parts+=("ai-diff-reviewer ${AIDR_TAG}") MSG="" @@ -239,11 +237,11 @@ jobs: { echo "## Vendored skills" echo "" - echo "| Skill | Vendored | Latest upstream | Moved? |" - echo "| --- | --- | --- | --- |" - echo "| deepworkplan | v${DWP_CUR} | ${DWP_TAG:-_(unresolved)_} | ${DWP_MOVED} |" - echo "| dailybot | v${DB_CUR} | ${DB_TAG:-_(unresolved)_} | ${DB_MOVED} |" - echo "| ai-diff-reviewer | v${AIDR_CUR} | ${AIDR_TAG:-_(unresolved)_} | ${AIDR_MOVED} |" + echo "| Skill | Vendored | Latest upstream | Auto-refreshed? | Moved? |" + echo "| --- | --- | --- | --- | --- |" + echo "| deepworkplan | v${DWP_CUR} | _(manual — repo-adapted)_ | no | — |" + echo "| dailybot | v${DB_CUR} | ${DB_TAG:-_(unresolved)_} | yes | ${DB_MOVED} |" + echo "| ai-diff-reviewer | v${AIDR_CUR} | ${AIDR_TAG:-_(unresolved)_} | yes | ${AIDR_MOVED} |" echo "" echo "**Dogfood commit:** \`chore: dogfood vendored skills to ${MSG}\`" echo "" diff --git a/AGENTS.md b/AGENTS.md index 1da36df..aa2feef 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -257,30 +257,38 @@ Multiple AI agents collaborate on this codebase. When updating agent guidance, m ### Optional — Dailybot reporting (best-effort, never blocks) -This repo has the DWP **Dailybot addon** wired: the `dailybot` skill is installed alongside `deepworkplan` under `.agents/skills/` (both gitignored installs). When the Dailybot CLI is present and authenticated, DWP work emits standup-style agent updates at four lifecycle points — **kickoff** (a plan is approved: what is being built), **significant task** (a feature/fix ships mid-plan), **blocked** (a run halts; `state.json.blocked` says what it needs), and **completion** (the only **milestone**: what was built) — routed through the dailybot `report` sub-skill, with `--json-data` derived from the plan's `state.json`. If Dailybot is absent, unauthenticated, or unreachable — or `.dailybot/disabled` exists — skip silently and continue: **reporting never blocks any work.** Describe outcomes for the team, never plan IDs, task numbers, file paths, or git stats. +This repo has the DWP **Dailybot addon** wired: the `dailybot` skill is installed alongside `deepworkplan` under `.agents/skills/` (vendored, tracked in git). When the Dailybot CLI is present and authenticated, DWP work emits standup-style agent updates at four lifecycle points — **kickoff** (a plan is approved: what is being built), **significant task** (a feature/fix ships mid-plan), **blocked** (a run halts; `state.json.blocked` says what it needs), and **completion** (the only **milestone**: what was built) — routed through the dailybot `report` sub-skill, with `--json-data` derived from the plan's `state.json`. If Dailybot is absent, unauthenticated, or unreachable — or `.dailybot/disabled` exists — skip silently and continue: **reporting never blocks any work.** Describe outcomes for the team, never plan IDs, task numbers, file paths, or git stats. **Deterministic hook enforcement (Claude Code):** `.agents/settings.json` wires the Dailybot lifecycle hooks (`dailybot hook session-start | activity | stop`, CLI >= 1.12.0) so the harness itself detects unreported work and reminds the agent at end of turn — no reliance on the model remembering. When a reminder fires: send a report if a meaningful unit of work is done, or run `dailybot hook dismiss` if not — never ignore it silently, and never let reporting block work. The hooks are local-only, always exit 0, and respect `.dailybot/disabled`. -### Vendored agent skills — refreshed on every website release +### Vendored agent skills — addons auto-refresh; deepworkplan is repo-adapted -`.agents/skills/deepworkplan/`, `.agents/skills/dailybot/`, and `.agents/skills/ai-diff-reviewer/` are **vendored copies** of the upstream skill repos (`DailybotHQ/deepworkplan-skill`, `DailybotHQ/agent-skill`, and `DailybotHQ/ai-diff-reviewer`), tracked in git and pinned via `skills-lock.json`. All three are refreshed **automatically as part of every website release**, so `vX.Y.Z` of the site always ships with a current snapshot of the full skill set. +`.agents/skills/deepworkplan/`, `.agents/skills/dailybot/`, and `.agents/skills/ai-diff-reviewer/` are **vendored copies** tracked in git and pinned via `skills-lock.json`. They are managed differently on purpose: -**How it works.** [`release_and_publish.yml`](.github/workflows/release_and_publish.yml) (which fires on every merge to `main`) has a dogfood step (Step 1a) that runs **before** the version bump: +| Skill | Upstream | Release auto-refresh | Why | +|-------|----------|----------------------|-----| +| `deepworkplan` | `DailybotHQ/deepworkplan-skill` | **No** | Repo-adapted DWP kit — blind reinstall would overwrite local adaptation. Update only via an explicit, reviewed change that re-adapts the skill to this repository. | +| `dailybot` | `DailybotHQ/agent-skill` | **Yes** | Addon — safe to pin to latest upstream on every website release. | +| `ai-diff-reviewer` | `DailybotHQ/ai-diff-reviewer` | **Yes** | Addon — safe to pin to latest upstream on every website release. | -1. Resolves the latest tag of each upstream skill via `gh release view --repo `. +**How addon refresh works.** [`release_and_publish.yml`](.github/workflows/release_and_publish.yml) (which fires on every merge to `main`) has a dogfood step (Step 1a) that runs **before** the version bump and refreshes **only** `dailybot` and `ai-diff-reviewer`: + +1. Resolves the latest tag of each auto-refreshed upstream skill via `gh release view --repo `. 2. Compares against the vendored `SKILL.md` `version:` field. Only installs skills that actually moved. 3. Runs `npx --yes skills add @ --skill --force -y` — the exact command any downstream consumer would run, so this doubles as a live smoke test. Both `--yes` (npm's proceed prompt) AND `-y` (the skills CLI's agent-picker prompt) are required in a non-TTY runner — dropping either hangs the workflow indefinitely. 4. Asserts the invariant: installed `SKILL.md` version equals the requested tag. Refuses to proceed with the release if not. -5. If any files changed, commits `chore: dogfood vendored skills to (…)` locally with a selective subject that names ONLY the skills that moved (e.g., `chore: dogfood vendored skills to deepworkplan v2.16.4, ai-diff-reviewer v2.0.0`). Step 3's `git push --follow-tags` sends this commit alongside the version-bump commit and the tag in a single atomic push, and the dogfood commit appears in the auto-generated GitHub Release notes. +5. If any files changed, commits `chore: dogfood vendored skills to (…)` locally with a selective subject that names ONLY the skills that moved (e.g., `chore: dogfood vendored skills to dailybot v3.10.3, ai-diff-reviewer v2.0.0`). Step 3's `git push --follow-tags` sends this commit alongside the version-bump commit and the tag in a single atomic push, and the dogfood commit appears in the auto-generated GitHub Release notes. -**Semantics.** Skill refresh is **release-driven**, not autonomous — no scheduled/cron refresh runs in the background. The vendored copies advance only when a maintainer merges a PR to `main`, which is the same moment `release_and_publish.yml` cuts a new website release. The intent is that the maintainer controls exactly when the site adopts a new skill version. +**Semantics.** Addon skill refresh is **release-driven**, not autonomous — no scheduled/cron refresh runs in the background. The auto-refreshed vendored copies advance only when a maintainer merges a PR to `main`, which is the same moment `release_and_publish.yml` cuts a new website release. **Failure semantics.** - `npx skills add` failure OR version-invariant mismatch → **fails the release** (a broken upstream tag must never quietly ship inside a website version). - Transient `gh release view` blip (rate limit, temporary outage) → skips only that skill for this release; the release itself proceeds. -- All three skills already at latest → clean no-op, no dogfood commit, release proceeds normally. +- Both auto-refreshed addon skills already at latest → clean no-op, no dogfood commit, release proceeds normally. -**Do not edit files under `.agents/skills/deepworkplan/`, `.agents/skills/dailybot/`, or `.agents/skills/ai-diff-reviewer/` by hand** — the next release will overwrite hand edits. Contribute upstream, then merge any PR to trigger a website release that picks up the new upstream tag. +**Editing policy.** +- **Do not** hand-edit `.agents/skills/dailybot/` or `.agents/skills/ai-diff-reviewer/` — the next release will overwrite those edits. Contribute upstream, then merge any PR to trigger a website release that picks up the new upstream tag. +- **Do** treat `.agents/skills/deepworkplan/` as repo-adapted: changes there must be intentional and reviewed. Prefer contributing reusable improvements upstream in `DailybotHQ/deepworkplan-skill`, then re-adapting this copy deliberately — never rely on the release dogfood step to pull it in. ### PR review workflow — Cursor-based, `ready`-label gated (Action `@v2`) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 4b33202..662ffb3 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -757,8 +757,9 @@ src/content/methodology/ This repository runs on the methodology it documents. -- **Reference install (not vendored).** The official DeepWorkPlan skill is installed under `.agents/skills/deepworkplan/`, which is **gitignored** — the skill source is never committed. A committed `skills-lock.json` pins the reference so the install is reproducible (`npx skills add DailybotHQ/deepworkplan-skill`). -- **Thin command delegators.** The committed `dwp-*` commands (`/dwp-create`, `/dwp-execute`, `/dwp-refine`, `/dwp-resume`, `/dwp-status`) are ~20-line delegators that read the installed skill's sub-skills and follow them — no embedded logic, so updates propagate from the skill. +- **Vendored, repo-adapted `deepworkplan` skill.** The official DeepWorkPlan skill lives under `.agents/skills/deepworkplan/` and is **tracked in git**. It is adapted to this repository (kit wiring, onboarded conventions) and is **not** overwritten by the release dogfood step — update it only via an explicit, reviewed change that re-adapts it. A committed `skills-lock.json` records the install provenance. +- **Auto-refreshed addon skills.** `.agents/skills/dailybot/` and `.agents/skills/ai-diff-reviewer/` are also vendored and tracked. [`release_and_publish.yml`](../.github/workflows/release_and_publish.yml) Step 1a refreshes **only those two** to their latest upstream tags on every website release. See [AGENTS.md → Vendored agent skills](../AGENTS.md). +- **Thin command delegators.** The committed `dwp-*` commands (`/dwp-create`, `/dwp-execute`, `/dwp-refine`, `/dwp-resume`, `/dwp-status`) are ~20-line delegators that read the installed skill's sub-skills and follow them — no embedded logic in the command files themselves. - **The author sub-skill.** `/skill-create` and `/agent-create` are thin delegators to the skill's **author** sub-skill, which grows the repository's own skills, agents, and commands and keeps the `.agents/docs/` catalog in sync. - **The dependency-upgrade add-on.** `/lib-upgrade` delegates to the opt-in **dependency-upgrade** add-on, which reasons about the actual package manager (pnpm here) and upgrades in validated, revertible batches. - **`.dwp/` output.** All Deep Work Plan working state (plans, drafts) lives in the gitignored `.dwp/` directory (`.dwp/plans/`, `.dwp/drafts/`). The legacy homegrown command engine has been retired in favor of the installed skill. diff --git a/docs/PRODUCT_SPEC.md b/docs/PRODUCT_SPEC.md index 4696a0d..25db698 100644 --- a/docs/PRODUCT_SPEC.md +++ b/docs/PRODUCT_SPEC.md @@ -13,7 +13,7 @@ Beyond turning a repository AI-first, DWP lets that repository **evolve its own ### This repository dogfoods DWP -The website repository practices the methodology it documents. The official DeepWorkPlan skill is installed under `.agents/skills/deepworkplan/` using a **reference-install model**: the skill source is gitignored (not vendored), and a committed `skills-lock.json` pins the reference. What is committed is the thin `dwp-*` command delegators (`/dwp-create`, `/dwp-execute`, `/dwp-refine`, `/dwp-resume`, `/dwp-status`), the `/skill-create` and `/agent-create` delegators that route to the author sub-skill, the `/lib-upgrade` delegator for the dependency-upgrade add-on, the `/init` adoption flow, and the docs. All Deep Work Plan output lives in the gitignored `.dwp/` directory (`.dwp/plans/`, `.dwp/drafts/`). The legacy homegrown command engine has been retired in favor of this install. See [Architecture → Dogfooding DWP](ARCHITECTURE.md#dogfooding-dwp) for the install and `.dwp/` details. +The website repository practices the methodology it documents. The official DeepWorkPlan skill is **vendored and repo-adapted** under `.agents/skills/deepworkplan/` (tracked in git; not auto-overwritten on release). Addon skills (`dailybot`, `ai-diff-reviewer`) are also vendored and **are** refreshed to latest upstream on every website release. A committed `skills-lock.json` pins install provenance. Also committed: the thin `dwp-*` command delegators (`/dwp-create`, `/dwp-execute`, `/dwp-refine`, `/dwp-resume`, `/dwp-status`), the `/skill-create` and `/agent-create` delegators that route to the author sub-skill, the `/lib-upgrade` delegator for the dependency-upgrade add-on, the `/init` adoption flow, and the docs. All Deep Work Plan output lives in the gitignored `.dwp/` directory (`.dwp/plans/`, `.dwp/drafts/`). See [Architecture → Dogfooding DWP](ARCHITECTURE.md#dogfooding-dwp) and [AGENTS.md → Vendored agent skills](../AGENTS.md) for details. ## Positioning