Welcome Ai Badger

---
name: welcome-ai-badger
description: >-
  Use when a repository should be set up with ai-badger — "welcome-ai-badger", "scaffold this
  project", "add agent instructions here", "onboard this repo" — whether it is new or already has
  agent files. Detects stacks, writes .ai-badger/, and generates each configured agent's
  discovery file.
version: 1.0.0
author: ai-badger
license: MIT
platforms: [linux, macos, windows]
scope: default
metadata:
  hermes:
    tags: [scaffolding, onboarding, setup, detection]
    related_skills: [den-refresh, feed-badger]
---

# welcome-ai-badger

Scaffolds a target repository with a project-tailored selection of ai-badger framework
features. **The scripts do all mechanical work; you (the agent) only author `config.json` — the
one creative artifact — and answer/ask a few questions.**

## Responsibility split (do not blur it)

- **Scripts (mechanical, deterministic):** `detect.py` proposes a config; `validate.py` checks
  it; `scaffold.py` builds `.ai-badger/`, assembles `CLAUDE.md`, copies agent files, records
  provenance in `manifest.json`.
- **You (creative only):** turn the proposed config into a good `config.json` — write
  `project.summary`/`domain`, choose/confirm stacks, define `personaRouting`, resolve any
  detection ambiguity by asking the user. Then hand it back to `validate.py`.

## Prerequisites

Framework scripts need `jsonschema`:
```bash
python3 -m pip install -r "$AI_BADGER/engine/requirements.txt"
```
`$AI_BADGER` = this framework's root (the dir containing `index.json`, `schemas/`, `common/`).
If `index.json` is missing or stale, run `python3 "$AI_BADGER/tooling/index_build.py"` first.

## Flow

0. **Is this a collection?** Look at the target's direct subdirectories: a directory that
   carries a `.git` entry is a repository. When the target holds more than one of them, the
   operator may want one shared scope over all of them — run the discovery command and ask:
   ```bash
   python3 "$AI_BADGER/features/common/skills/welcome-ai-badger/scripts/shared_scope.py" discover \
     --target . --root "$AI_BADGER"
   ```
   It prints one `dir:stacks` line per repository and the union of their stacks, and writes
   nothing. With the operator's go-ahead, the parent-side path takes over: run
   `shared_scope.py init --target . --root "$AI_BADGER"` (add `--dry-run` first to show the
   members, the union and every identity decision without writing) and skip the steps below.
   With one repository — or when the operator wants them separate — continue as usual.

1. **Detect.** From the target repo root:
   ```bash
   python3 "$AI_BADGER/features/common/skills/welcome-ai-badger/scripts/detect.py" --target . --root "$AI_BADGER" > /tmp/proposed-config.json
   ```
   This proposes stacks (with `requires` expanded), detected coding agents
   (claude/copilot/hermes/pi/codex, detected from repo or user-scope traces), source control,
   and build/test/lint/run commands.

2. **Author `config.json`.** Read the proposal. Fill in `project.summary` and `project.domain`
   (the domain is the *business* purpose, never a stack). Confirm the stack list against
   `index.json` (`stacks` must be known stacks). Add `personaRouting` mapping kinds of work to
   the personas that will be scaffolded (base roles: `architect`, `test-engineer`,
   `code-reviewer`, plus each selected stack's engineer persona). **Ask the user only when a
   choice is genuinely ambiguous** (e.g. detection found both a frontend and a backend and you
   can't tell the project's focus).

3. **Ask plugin scope.** Ask the user: **default** (honor each plugin entry's declared scope) or
   **local-only** (force every plugin install to project scope). Set `skillScope` accordingly.
   (There is deliberately no "user-only" option.)

   If the user declines a skill, persona, invariant or instruction, name it in `exclude`
   (`{"skills": ["mcp-index"]}`) — deleting the scaffolded file is undone by the next refresh
   (Why — see Gotchas.).
   The declined item is not delivered and its discovery symlinks are removed; the copy already
   under `.ai-badger/skills/` stays on disk for the user to delete.

   Catalog tools (`features/<stack>/tools/`) are never proposed by detection. Add one only
   when the user asks for it: `{"tools": {"<tool>": {"hooks": ["claude", "copilot"]}}}`
   names the agents whose hooks route through it. For Claude the hook is ai-badger's guard, which
   leaves a command a `permissions.ask` rule names unrewritten. The tool binary is checked, and installed only
   under `--execute`. Removing the entry makes the next scaffold delete the hook files it
   wrote; for pi it prints the `<tool> init --agent pi --uninstall` command instead.

4. **Validate.**
   ```bash
   python3 "$AI_BADGER/tooling/validate.py" --kind config /tmp/proposed-config.json
   ```
   Fix any reported error in the config and re-run until it passes.

5. **Scaffold.**
   ```bash
   python3 "$AI_BADGER/features/common/skills/welcome-ai-badger/scripts/scaffold.py" \
     --config /tmp/proposed-config.json --target . --root "$AI_BADGER" \
     --generated-at "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
   ```
   Produces `.ai-badger/` (config.json, manifest.json, CLAUDE.md, agents/, instructions/,
   invariants/, skills/, agent-instructions/, state.json) and agent-discovery copies for each
   detected agent (`CLAUDE.md`, `.github/copilot-instructions.md`, `HERMES.md`,
   `AGENTS.override.md`, `AGENTS.md`). Codex receives `.agents/skills/` symlinks and
   `.codex/agents/*.toml`, project MCP configuration and the supported native hook subset.
   Review project and hook trust in Codex before expecting hooks to run; scaffolding does not
   grant trust. A root pi `AGENTS.override.md` wins over `AGENTS.md`, so check its guidance
   when both agents share a repository. Note the
   printed plugin-setup commands and run them per the chosen scope (or hand them to the user).
   **Existing hand-authored discovery files are preserved by default** — see the preserve note
   below; on a mature repo the scaffold will report which files it left untouched.

6. **Verify & report.** Confirm the scaffold matches the stacks (no leakage from unselected
   stacks). Summarize what was written, the plugin commands, and any notes the script emitted.
   When the output ends with a list of trees that "claim to be ai-badger", relay it: a drift
   notice fires once per tree (Why — see Gotchas.), so competing copies explain contradictory
   notices. Scaffolding
   deletes nothing in the home directory — `den-refresh --prune-cache` is the one command that
   removes `~/.ai-badger/framework`, and `~/.claude/plugins/cache/` is Claude Code's to manage.

## Notes

- **Idempotent:** re-running `scaffold.py` refreshes managed files and the manifest. Safe to
  re-run after editing `config.json`.
- **Copy-vs-reference:** essential agent files (CLAUDE.md, HERMES.md, copilot-instructions)
  are *copied* to their conventional locations with a header pointing at `.ai-badger/` as the
  source of truth, because agent CLIs discover them by convention. A thin-proxy (symlink)
  alternative was considered and dropped: symlinks break on Windows, and Copilot does not
  follow references.
- **Preserve-by-default (mature repos):** a discovery file that already exists and does *not* carry
  the ai-badger managed header is treated as hand-authored and left untouched — its `.ai-badger/`
  source copy is still written, and the scaffold emits a `preserved …` note. Framework-written
  copies (which carry the header) and brand-new files are written/refreshed normally, so
  idempotent re-scaffolding still works. Pass `--overwrite-agent-files` to force the old
  copy-over behavior on every discovery file.
- **Preserved regions (per-block):** content between `<!-- ai-badger:keep-start -->` and
  `<!-- ai-badger:keep-end -->` is carried verbatim into the regenerated file, in order, at the
  end. This applies to every managed agent file *and* its `.ai-badger/` source-of-truth copy, so
  a project block added to `.ai-badger/CLAUDE.md` survives a re-scaffold. Unbalanced or nested
  markers leave the file untouched and emit a note — a marker typo never loses content (Why — see
  Gotchas.). Tell the
  user about this whenever they ask where to put project-authored content in a managed file.
- **Extensions:** config-gated skill extensions (e.g. the GitHub PR/issue extension of `task`)
  are embedded automatically iff `config.json` supplies their required data.

## Gotchas

- **Deleting a scaffolded file does not decline the item.** The next refresh brings it back —
  decline a skill, persona, invariant or instruction by naming it in `exclude` in `config.json`,
  not by deleting the delivered copy.
- **A keep-marker typo never loses content.** Unbalanced or nested
  `<!-- ai-badger:keep-start -->`/`<!-- ai-badger:keep-end -->` markers leave the file untouched
  and emit a note rather than mangling it.
- **A drift notice fires once per tree.** Competing ai-badger copies each claim the repo, so a
  relayed tree list explains contradictory notices — it is not a bug to fix.
- **Never remediate a scaffold-freshness-guard failure with `--skills ''`.** The empty value
  recovers the skill list *from the manifest being audited* (#129), so on a narrowed manifest
  it regenerates the same narrowed set and the guard goes green over the very defect it
  reported. The guard's printed remediation carries the full config-derived skill list — run
  that verbatim. And every regenerated mirror (`.ai-badger/skills/**`, agent files,
  `.ai-badger/manifest.json`) rides **in the same commit as the source edit that made it
  stale** — a mirror committed alone is the guard catching up to something that already
  shipped.

## Updating an already-scaffolded project

The initial scaffold is a one-time setup. For ongoing updates when the framework
releases new features or fixes, use **`den-refresh`** instead of re-running welcome:

```bash
python3 "$AI_BADGER/features/common/skills/den-refresh/scripts/refresh.py" --target . --root "$AI_BADGER"
```

`den-refresh` checks what changed upstream, re-scaffolds with your existing
config.json (no re-detection, no questions), and reports the result. Seed-once
files (state.json, markers-context.json, model.json) are preserved. Review the
diff before committing.

## Error Recovery

When any script in the welcome flow (`detect.py`, `validate.py`, `scaffold.py`)
exits non-zero or emits an error, attempt recovery before surfacing the failure.

1. **Parse the error.** Scripts emit structured JSON with an `error` field and
   sometimes `validationErrors`. Read both to classify the failure.

2. **Attempt automatic recovery.** Try the applicable fix, then re-run the
   failed step.

   | Error | Fix |
   |---|---|
   | `jsonschema` import error | `python3 -m pip install -r "$AI_BADGER/engine/requirements.txt"` |
   | `index.json` missing or stale | `python3 "$AI_BADGER/tooling/index_build.py"` |
   | `validate.py` reports config errors | Read errors, patch config JSON, re-validate |
   | `scaffold.py` file-permission / encoding error | Fix the file/permission, retry once |
   | `detect.py` found no stacks | Check that `$AI_BADGER` points at a valid framework checkout (has `index.json`) |
   | Agent file write failed (read-only discovery file) | Pass `--overwrite-agent-files` or remove the conflicting file |

   After applying a fix, **re-run the failed step** and continue the flow. If it
   succeeds, report what was fixed.

3. **Recovery failed — offer to create a GitHub issue.** Follow
   `.ai-badger/skills/welcome-ai-badger/references/reporting-a-framework-bug.md` **when a fix
   does not recover the failure**: ask
   permission first, gate on `gh` being installed and authenticated, sanitize the config
   before including it. **Never create the issue without explicit user approval** — that rule
   holds even if the reference file is not present.

## Verification Checklist

- [ ] `validate.py --kind config` passed on the authored config
- [ ] Scaffold output covers exactly the selected stacks — no leakage from unselected stacks
- [ ] `.ai-badger/` holds config.json, manifest.json, CLAUDE.md, agents/, instructions/, invariants/, skills/, agent-instructions/, state.json
- [ ] Plugin-setup commands relayed per the chosen scope (default or local-only)
- [ ] Preserved hand-authored discovery files reported, not overwritten
- [ ] Any "competing copies" tree list relayed, and nothing outside the target deleted

## Shared parent collections

For a collection with explicit child repositories, use the existing renderer through:

```bash
python3 "$AI_BADGER/features/common/skills/welcome-ai-badger/scripts/shared_scope.py" collect \
  --target /path/to/collection --repo python-app --repo dotnet-app --root "$AI_BADGER"
```

To start from the parent instead — a directory of repositories you did not pick by hand —
use the discovery and initialization commands:

```bash
python3 "$AI_BADGER/features/common/skills/welcome-ai-badger/scripts/shared_scope.py" discover \
  --target /path/to/source --root "$AI_BADGER"
python3 "$AI_BADGER/features/common/skills/welcome-ai-badger/scripts/shared_scope.py" init \
  --target /path/to/source --root "$AI_BADGER"
```

`discover` is read-only: it lists the direct subdirectories that carry a `.git` entry, one
`dir:stacks` line each, plus the union of their stacks. `init` enrolls every repository it
finds, one level deep: it decides every identity and every member's own settings before it
writes anything, scaffolds the parent with the union of the stacks, and materializes every
member from it. A member with no ai-badger yet is scaffolded; a member that already has one
is converted, keeping its own project id, its own stacks and its own settings. `--dry-run`
reports the plan and writes nothing.

Supply `--config /path/to/parent-config.json` to author parent defaults. Collect uses only
these members, computes their stack union, and materializes every selected child with that
union. Each child keeps its identity and state. Its private `.ai-badger/shared-scope.json`
records original local stacks and authored overrides; edit those overrides for persistent
local settings. Objects merge and lists replace parent values.

To refresh one child with its own stacks, run `shared_scope.py sync --target CHILD --source
COLLECTION/.ai-badger --root FRAMEWORK`. Ordinary scaffold and den-refresh refuse shared
children and print the command that restores them — `collect` for a child that carries the
union, `sync` for one that carries its own stacks.

To remove a member from the collection, run `shared_scope.py prune --target COLLECTION --repo
CHILD --root FRAMEWORK`: the member keeps its own identity and its shared files as private
copies, the parent's union shrinks to the remaining members, and the pruned repository
rejoins the ordinary scaffold and refresh flow. A collection keeps at least one member, so
the last one cannot be pruned.

A member with no identity of its own is resolved through the canonical ai-raccoon lookup:
the bank's id for that name is reused, a name the bank does not know gets a local id, and
an uncertain answer refuses the enrollment before anything is written. Nothing is
registered with the bank unless `--register` is passed. Verify child instruction and skill discovery,
then confirm the child's project ID remains its own. Do not replace `.ai-badger` directories
with symlinks; only the recorded immutable files may share parent copies.