AI Agents Generation And Release

ai-agents Generation and Release

Runbook for the build, generation, mirroring, versioning, and release machinery of this repo. Every command below was executed or read from source on 2026-07-02/03 and re-verified against the working tree on 2026-07-29; re-verify with the one-liners in Provenance before trusting a volatile number.

Jargon, defined once:

• Generator: a Python function or script that reads a canonical tree and writes a derived (generated) tree.
• Drift: the generated tree no longer matches what the generators would produce from the canonical tree.
• Canonical: the tree you are allowed to edit. Generated trees are outputs; you never hand-edit them.
• Semver: semantic version string MAJOR.MINOR.PATCH. The plugin manifests carry no version at all (ADR-092); the npm package still does.

Triggers

• regenerate the mirrors
• run the drift checks
• why is the plugin version gate red
• release the npm cli
• why is the drift gate red

When NOT to Use This Skill

Process

Phase 1: Know the Seam Before You Edit

The generation seam is ASYMMETRIC (ADR-072 is PROPOSED and refines this; the running system is what follows). Find your file in this table BEFORE editing. Editing a generated tree is the classic failure (see Anti-Patterns).

Generator inventory inside build/scripts/build_all.py (the GENERATORS list; order is load-bearing per the Order matters comment above it):

Facts that prevent confusion:

• build_all.py enforces a no-write invariant on .claude/ (REQ-003-010): if any generator writes there, the run exits 2 with REQ-003-010 VIOLATION. .claude/ is input only.
• Generated-tree ownership is exactly OWNED_PREFIXES = ("src/", ".github/instructions/", "docs/agent-catalog.md", ".agents/architecture/README.md"), four entries, in the OWNED_PREFIXES tuple. --check only flags staleness inside those prefixes, and the adr-index generator is why the last one is there.
• The hooks generator maps Stop, SubagentStop, PermissionRequest, and PreCompact to their PascalCase compatibility names. Stop and SubagentStop remain direct host registrations because their structured decisions require host-level merging. A reported drop needs an identified source registration; never assume it is normal.
• Every run overwrites the generation audit log in the gitignored build audit directory. Read it to see what each generator did.

Phase 2: Regenerate After Editing a Canonical Surface

Always commit the canonical edit and the regenerated output TOGETHER, in the same commit set, or the drift gates go red.

Interpreter note: build/generate_agents.py and build/scripts/build_all.py both import PyYAML through build/scripts/yaml_loader.py. Run them as uv run python <script> locally so the project venv supplies it. CI can invoke bare python3 because .github/actions/setup-code-env installs the locked dependencies system-wide first.

Useful flags, verified against source:

• build/generate_agents.py: --validate (CI compare mode), --what-if (dry run, writes nothing), --templates-path, --output-root. Exit codes: 0 ok, 1 logic error or drift, 2 config error (docstring, generate_agents.py:13-16).
• build/scripts/build_all.py: --check (staleness gate; snapshots and restores owned trees), --clean, --audit-format json, --platform copilot-cli. Exit codes: 0 ok, 1 generator error, 2 config error or staleness or (under --check) a path under OWNED_PREFIXES that cannot be read or redirects (symlink or junction) or holds a nested git repository, or a generator write under .claude/ (REQ-003-010), 3 audit blocklist violation or (under --check) unreadable git state (the EXIT CODES block in this script's module docstring). Only the staleness producer of exit 2 is cleared by regenerating and committing; the REQ-003-010 producer is a generator policy violation, so regenerating reproduces it. Git is external, so every git-read failure (launch, timeout, nonzero exit) is 3 per the AGENTS.md contract, which keeps "you are missing git" out of the same code as "your tree is stale" (issue #4632).
• scripts/sync_plugin_lib.py: no flag syncs, --check is the CI dry run (exit 1 when out of sync). It also rewrites from scripts.x import to relative imports; do not "fix" those imports in .claude/lib/ by hand.

Phase 3: Run the Drift Gates Locally Before Pushing

Drift-gate matrix (all local commands verified runnable, all green on 2026-07-29):

When a drift gate is red, the output shows the DIFFERENCE, not the DIRECTION. Ask "which side is canonical?" using the Phase 1 table before touching anything. The 2025-12-15 incident (retro: .agents/retrospective/2025-12-15-drift-detection-disaster.md) happened because an agent edited the SOURCE to match the GENERATED tree; the commit was reverted. Fix is always: edit canonical, rerun generator, commit both.

An emergency bypass marker for the drift gate exists but requires a reason and approval; see ai-agents-config-catalog. Route the decision through ai-agents-change-control.

Run the installed Copilot hook E2E in an isolated home. This executes the marketplace layout and generated hook scripts without changing live plugin state:

E2E_HOME="$(mktemp -d)"
HOME="$E2E_HOME" COPILOT_HOME="$E2E_HOME/.copilot" \
  copilot plugin marketplace add "$PWD"
HOME="$E2E_HOME" COPILOT_HOME="$E2E_HOME/.copilot" \
  copilot plugin install project-toolkit@ai-agents
HOME="$E2E_HOME" COPILOT_HOME="$E2E_HOME/.copilot" \
  RUN_INSTALLED_PLUGIN_HOOK_E2E=1 uv run pytest \
  tests/e2e/test_installed_plugin_hook_e2e.py -q

Do not run this setup in the live Copilot home. Copilot CLI 1.0.72-1 was observed removing the marketplace registration for copilot plugin uninstall project-toolkit while leaving the _direct/project-toolkit cache. The active session then lost its hook scripts and denied matching tools until the marketplace plugin was reinstalled.

Phase 4: Plugin Manifests Carry No Version

Three plugin manifests exist (verify: find . -name plugin.json -path "*claude-plugin*"):

The rule (docstring of build/scripts/validate_plugin_version_bump.py): none of those manifests may carry a version field, and neither may an entry in either marketplace.json. Claude Code then resolves freshness from the git commit SHA, which moves on every merge. ADR-092 records the reversal of ADR-079's hand-bumped rule after issue #4080 measured 14 of 22 conflicting PRs conflicting on that one line.

Practical consequences:

• Any .claude/ content edit regenerates src/copilot-cli/ too, but neither manifest changes: both are version-free, and check_plugin_manifest_parity.py now checks description component counts only.
• src/claude/ is the same: no version to move.
• .github/instructions/ and src/vs-code-agents/ carry no plugin.json at all.
• Marketplace: .claude-plugin/marketplace.json lists two plugins (claude-agents from ./src/claude, project-toolkit from ./.claude). The old marketplace count validator and its YAML config were retired, so treat description-count validation as currently unenforced and keep counts honest by hand.

Phase 5: npm Release Path

The npm surface is packages/ai-agents-cli (package @rjmurillo/ai-agents; read package.json for the current version). It vendors the Claude kit into consumer repos. Release procedure (source: RELEASING.md, repo root):

1. Bump packages/ai-agents-cli/package.json version. Tag/version mismatch is a listed failure mode.
2. Local sanity: cd packages/ai-agents-cli && bun run build (runs bun build src/cli.ts --outdir dist --target node), bun test, tsc --noEmit via bun run typecheck. As of 2026-07-29 bun run typecheck exits 1 on this package with 38 errors (36 TS2591, 2 TS2503). @types/node 26.0.0 is installed, but the package tsconfig.json sets no types field, and TypeScript 7.0.2 no longer auto-includes it the way 5.9.3 does, so Node builtins are absent from the compilation. Issue #3865 tracks the fix: add "types": ["node"] and a CI job that runs typecheck and bun test. Before blaming your change for a red typecheck, check whether that fix landed: grep -q '"types"' packages/ai-agents-cli/tsconfig.json.
3. Commit to main via normal PR flow (branch discipline still applies; see ai-agents-change-control).
4. git tag vX.Y.Z then git push origin main --tags.
5. .github/workflows/publish.yml fires on v* tags: validates package metadata, publishes with OIDC provenance (id-token: write; NPM_TOKEN is fallback only). workflow_dispatch offers a dry-run input defaulting to true.
6. Verify: registry version, provenance badge on npmjs.com, clean-environment install (commands in RELEASING.md Verification section).

Rollback is roll-FORWARD: npm unpublish is restricted; fix, bump patch, retag (RELEASING.md Rollback procedures).

Anti-Patterns

Verification

Run this checklist before pushing any change that touched a canonical or generated surface:

• uv run python build/generate_agents.py --validate exits 0
• uv run python build/scripts/build_all.py --check exits 0 (if it returns 2, read stderr first: regenerate only for staleness, not for an owned path that is unreadable, redirecting, or a nested repository, and not for a REQ-003-010 generator write)
• python3 scripts/sync_plugin_lib.py --check exits 0 (only relevant if scripts/ packages changed)
• python3 build/scripts/check_plugin_manifest_parity.py exits 0
• python3 build/scripts/validate_plugin_version_bump.py exits 0 (no manifest or marketplace entry carries a version)
• Canonical edit and regenerated output are staged in the same commit set
• For an npm release: tag matches packages/ai-agents-cli/package.json version exactly

Provenance and Maintenance

Verified 2026-07-29 against the working tree (re-verification pass; the 2026-07-03 pass had rotted for build/scripts/build_all.py, build/generate_agents.py, pyproject.toml, scripts/sync_plugin_lib.py, .github/workflows/publish.yml, and .github/workflows/validate-generated-agents.yml). Volatile facts and how to re-check them:

Maintenance: when a generator is added or removed from GENERATORS, when a fourth plugin.json appears, or if a marketplace count validator is reintroduced to replace the retired one, update Phase 1/4 tables and re-run every re-verify command above.