den-refresh

Files (4)

• SKILL.md
• error-recovery.md · references/
• refresh.py · scripts/
• skill_usage.py · scripts/

SKILL.md (first lines)

# den-refresh

Pulls framework updates from the ai-badger catalog into a project that was
already scaffolded. **The script does all mechanical work; you (the agent)
present the report and help the user review the diff.**

This is the update direction of the framework: framework → project (update).
For initial setup use `welcome-ai-badger`; to contribute back use `feed-badger`.

## Responsibility split

- **Script (mechanical):** `refresh.py` validates prerequisites (config.json,
  manifest.json), runs drift detection, re-scaffolds with the existing config,
  and emits a JSON report. Skills with extensions (e.g., `task` with
  `github`/`hermes` extensions) are re-scaffolded and their extensions
  re-embedded automatically.
- **You (creative only):** present the report, help the user review what
  changed, and offer to commit or discard. There is no config authoring, no
  stack detection, no plugin scope prompt — those belong to `welcome-ai-badger`.

## Prerequisites

- Project has `.ai-badger/config.json` and `.ai-badger/manifest.json` (it was
  scaffolded by `welcome-ai-badger`)
- An ai-badger framework checkout is accessible (`$AI_BADGER`)

## Flow

1. **Run refresh.** From the target repo root:
   ```bash
   python3 "$AI_BADGER/features/common/skills/den-refresh/scripts/refresh.py" --target . --root "$AI_BADGER"
   ```
   Add `--prune-cache` or `--prune-namespaces` only when the user has asked for it (steps 3
   and 3c) — both delete from the user's home directory. Add `--force` only
   as recovery (see Error Recovery) — it re-scaffolds unconditionally, bypassing every drift
   signal.
   This:
   - Validates that config.json and manifest.json exist
   - Reads the manifest to extract scaffolded skill names
   - Runs drift detection against the framework's current content
   - If drift is found, re-scaffolds using the existing config.json
   - Outputs a JSON report with drift details and scaffold notes

   Exit codes: 0 = success (up to date or changes applied), 2 = error (missing
   config/manifest, invalid config).

2. **Review the report.** The JSON output includes:
   - `frameworkVersion` — the version in config.json vs. the framework's, plus the version
     that actually wrote `manifest.json`. config.json advances only when a re-scaffold ran
   - `drift.changed` — framework sources that have moved ahead of what this project holds
   - `drift.removed` — scaffolded files whose framework source no longer exists
   - `drift.orphaned` — entries whose stack this project no longer lists in `config.stacks`.
     The framework still ships them; this project stopped asking. The re-scaffold prunes them,
     leaving anything edited in place with a note
   - `drift.versionChanged` — the version alone moved; it is stamped into manifest.json and
     every generated agent file, so those are stale even when no content changed
   - `drift.locallyModified` — skills this project edited in place. Not framework drift, but
     a re-scaffold overwrites them; move anything worth keeping into `project-local.md`
   - `drift.skipped` — directory entries from a manifest written before source hashing
     existed. Nothing records what the framework looked like, so they cannot be compared;
     a re-scaffold makes them comparable
   - `drift.newItems` — catalog items the project has never scaffolded, including ones
     added to the framework's always-on `common` stack after this project was set up
   - `drift.configChanged` — `null` unless config.json itself no longer matches what the
     last scaffold was built from (an `exclude`, `commands`, `stacks`, `agents` or
     `personaRouting` edit). Present as `{"recorded": ..., "current": ...}`; `recorded: null`
     means this manifest predates the field and self-heals on this one re-scaffold
   - `drift.proseReview` — the config's free-form prose (`project.summary`, `project.domain`),
     re-rendered verbatim into the managed agent files on every scaffold and checked by no
     fingerprint, so it goes stale silently. Each entry names the `configKey`, the template
     `slot` it fills, the `value` as written, and carries the note "human-written — review
     for staleness". Present them to the operator for review; never treat them as drift —
     a re-scaffold cannot freshen prose, only re-render it, and config.json is project-owned
   - `newStacks` — stacks detectable in the target but missing from config. Advisory only:
     it never triggers a re-scaffold, so non-empty `newStacks` alongside `reScaffolded: false`
     is the expected shape, not a contradiction
   - `reScaffolded` — whether a re-scaffold was performed
   - `projectIdWarning` — present only when the project-id step warned: ai-raccoon's id lookup
     or registration failed, several bank projects share this repo's name, or the reply was
     unusable. The id file is still minted or kept; the warning names the command to rerun
     after a human resolves it (ai-raccoon 1.57.0's `project id` verbs; ADR-0036)
   - `note` — present only when config.json and the framework disagree on the version and no
     re-scaffold ran; the generated files were not rewritten, so say so rather than reporting green
   - `scaffold` — if re-scaffolded: entry count, refreshed skill names, notes
   - `frameworkCopies` — present only when more than one tree on the machine claims to be
     ai-badger, or when `~/.ai-badger/framework` exists. `competing` names the path, version
     and owner of each; `cache` reports what happened to `~/.ai-badger/framework`
     (`reported` by default, `removed` with `--prune-cache`, `refused` with the reason)
   - `skillUsage` — which delivered skills this project was observed using, so unused ones can
     be pruned from the listing budget (see step 3b). `used` / `unused` / `cannotTell`, plus the
     `window` the claim rests on, the `channels` that answered, and the `limits` of both
   - `hermesNamespaces` — present only when every ai-badger symlink in a
     `~/.hermes/skills/<project>/` directory is dangling: that project's `.ai-badger/skills/`
     tree is gone. Every project's namespace is swept, not just this one (see step 3c). Each
     entry carries `path`, `links` (dead links ai-badger placed), `kept` (entries it did not —
     a non-zero `kept` means the directory itself survives the prune), the `target` that no
     longer exists, and `status` (`reported` by default, `removed` with `--prune-namespaces`,
     `failed` with the reason)

3. **Surface competing copies.** When the report carries `frameworkCopies`, tell the user which
   trees exist and at what versions — a drift notice fires once per tree, so two contradictory
   notices mean two installs, not a framework bug. `~/.ai-badger/framework` is ai-badger's own
   fallback clone and nothing updates it in place; offer to re-run with `--prune-cache` to
   remove it. **Never offer to delete `~/.claude/plugins/cache/`** — Claude Code owns that path
   and ai-badger only reads it.

3b. **Offer the prune candidates — never prune them.** `skillUsage.unused` names skills this
   project holds and nobody invoked over `skillUsage.window`. The payoff is the listing budget:
   a host allots a fixed slice of context to skill descriptions and drops the least-invoked ones
   first, so an unused skill crowds one somebody does use. Tell the user the candidates and how
   to decline them — `exclude.skills` in `config.json`, which is self-executing on the next
   refresh (`drift.configChanged`) — and stop there. **`config.json` is project-owned; never
   edit it as part of a refresh.**

   Report the rest of the section with the candidates, not instead of them:
   - `used` carries `evidence` — `invocation` (someone ran it) or `hook` (nobody ran it, but a
     hook it ships fired, so it is doing work every session). Both mean leave it alone
   - `cannotTell` is the honest bucket, and it is not a weaker `unused`: a skill listed there
     was never observable. Never propose pruning one

From Arasz/ai-badger, MIT.

More from Arasz/ai-badger