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:

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

1. Detect. From the target repo root:

   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.

4. Validate.

   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.

   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:

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