Agent catalog: self-bootstrapping agent packs with manifest schema, resolution stack, file-tracked teardown, and CLI

[Copilot]

Adding a new agent today requires changes to 10+ files across 5 languages. This PR introduces the foundational agent pack infrastructure that replaces the monolithic AGENT_CONFIG + case/switch architecture with self-contained, declarative agent packs — while preserving full backward compatibility during migration.

Agent pack module (src/specify_cli/agent_pack.py)

• AgentManifest — parsed/validated speckit-agent.yml with schema version enforcement
• AgentBootstrap — abstract base with setup() → List[Path] / teardown(force, files) / finalize_setup(agent_files, extension_files) lifecycle contract
• 4-level resolution stack: user (~/.specify/agents/) → project (.specify/agents/) → catalog cache → embedded in wheel
• load_bootstrap() dynamically imports pack's bootstrap module and discovers the AgentBootstrap subclass
• validate_pack(), export_pack(), list_embedded_agents(), list_all_agents()

setup() owns scaffolding and returns actual installed files

Each bootstrap's setup() calls _scaffold_project(), a base-class helper that invokes scaffold_from_core_pack, snapshots the project directory before and after, and returns every new file created. This means setup() is the single entry point for agent installation — it runs the shared scaffolding and reports what it created.

• _scaffold_project(project_path, script_type) — calls scaffold_from_core_pack, diffs before/after snapshots, returns List[Path] of all new files
• collect_installed_files(project_path) — scans the agent's directory tree and returns all files found
• finalize_setup(agent_files, extension_files) — filters agent_files to only track files under the agent's own directory tree (shared .specify/ infrastructure is not tracked per-agent), scans for additional files from later pipeline steps (skills, extensions), and writes .specify/agent-manifest-<agent_id>.json

Installed-file tracking with SHA-256 hashes

• finalize_setup(agent_files, extension_files) accepts categorised file lists from the CLI and records them in .specify/agent-manifest-<agent_id>.json with separate agent_files and extension_files sections
• get_tracked_files() returns an (agent_files, extension_files) tuple so the CLI can retrieve and split the tracked sets
• check_modified_files() compares current file hashes against the recorded manifest to detect user modifications across both categories
• remove_tracked_files(force, files) deletes only individual tracked files — directories are never deleted. Accepts an explicit files dict so the CLI can feed tracked file lists directly into teardown. Raises AgentFileModifiedError if any tracked file was modified since installation and force is False
• _reregister_extension_commands() returns List[Path] of files created by extension registration, which are passed to finalize_setup() as extension_files

CLI-level modification check before teardown

specify agent switch checks for modified files before calling teardown and prompts the user for confirmation. The CLI retrieves the tracked file lists via get_tracked_files(), checks for modifications, lists any changed files, and only proceeds with teardown after the user confirms (or if --force is passed). The file lists are then fed directly into teardown().

--agent flag on specify init

specify init --agent claude opts into the pack-based init flow. The --agent flag:

• Resolves the agent through the pack system (same 4-level priority stack)
• Validates the pack exists and can be loaded
• Routes scaffolding through setup() — the bootstrap owns the scaffolding process, always using bundled assets
• After all files are created (skills, presets, extensions), calls finalize_setup(agent_files=setup_files) to record every installed file in .specify/agent-manifest-<id>.json
• Records "agent_pack": true in init-options.json

--agent and --ai are mutually exclusive. --agent accepts the same agent IDs as --ai but additionally enables file tracking for clean teardown when switching agents.

specify init my-project --agent claude
specify init --here --agent gemini --ai-skills

25 embedded agent packs (src/specify_cli/core_pack/agents/<id>/)

Each pack contains speckit-agent.yml and bootstrap.py. Manifests carry command registration metadata (commands_dir, format, arg_placeholder, file_extension) sufficient for CommandRegistrar to render extension commands without importing the bootstrap module.

Bundled in the wheel via pyproject.toml force-include.

specify agent CLI subcommands

list, info, validate, export, switch, search, add, remove — following the same typer.Typer() + app.add_typer() pattern as specify extension and specify preset.

switch checks for modified files and prompts before teardown, tears down the old agent (file-by-file using the tracked file lists), sets up the new one, re-registers extension commands, then calls finalize_setup() with both agent and extension files to record the new install manifest. Updates init-options.json accordingly.

$ specify agent info claude
  Agent: Claude Code (claude)
  Source: embedded (bundled in specify-cli wheel)
  Commands Dir: .claude/commands
  Format: markdown

$ specify agent search --tag skills
  codex   Codex CLI   cli, openai, codex, skills   embedded
  kimi    Kimi Code   cli, moonshot, kimi, skills   embedded

Backward compatibility

AGENT_CONFIG and all existing code paths are untouched. The pack system is purely additive — specify init --ai <agent> continues to resolve through AGENT_CONFIG. Pack-based resolution is available via specify init --agent <agent> and specify agent commands and will become the default after validation.

Tests

452 new tests in test_agent_pack.py covering:

• Manifest validation — schema errors, optional defaults, field parsing
• Bootstrap contract — setup returns files, teardown with explicit files, dynamic loading
• Resolution order — embedded, project-level override, user-level override, catalog override
• Discovery and export — list_embedded_agents, list_all_agents, export_pack
• Consistency — embedded packs match both AGENT_CONFIG and CommandRegistrar.AGENT_CONFIGS
• File tracking — record/check unmodified, detect modification, refuse modified without force, allow modified with force, directory preservation, deleted-file handling, SHA-256 consistency, categorised manifest structure, get_tracked_files split, explicit-file teardown, extension file modification detection
• setup() returns actual files (TestSetupReturnsFiles, 100 tests) — every agent's setup() returns non-empty list of existing absolute paths, including files under the agent's directory tree
• End-to-end init parity (TestInitFlowParity, 300 tests) — uses typer.testing.CliRunner to invoke the real specify init command for both --ai and --agent flows across all 25 agents, comparing file sets, file contents, directory structure, tracking manifests, commands_dir alignment, and CommandRegistrar metadata byte-for-byte
• Full lifecycle — setup → scaffold → finalize → teardown for all 25 agents verifies clean removal of every tracked file

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[mnriem]

@copilot The setup should store a list of installed files with their hash in the .specify directory so we can track what was installed by the agent. At teardown time that file needs to be used to determine if ANY of the installed files was updated and if so the remove should require a --force. Note you will NOT delete any directories but rather just the individual files.

[Copilot]

@copilot The setup should store a list of installed files with their hash in the .specify directory so we can track what was installed by the agent. At teardown time that file needs to be used to dete...

Implemented in b5a5e3f (file tracking) and a63c248 (finalize_setup fix):

• setup() creates directories; finalize_setup() (base class method) scans the agent's commands_dir and writes .specify/agent-manifest-<agent_id>.json with SHA-256 hashes of all installed files
• teardown(force=False) reads the manifest and removes only individual tracked files — directories are never deleted
• If any tracked file was modified since installation, teardown raises AgentFileModifiedError unless --force is passed
• specify agent switch now accepts --force to pass through to teardown
• 11 new tests cover: record/check unmodified, detect modification, refuse without force, allow with force, directory preservation, deleted-file handling, manifest JSON structure

[mnriem]

@copilot the agent setup should report the files it installed as the cli needs to record both what was installed by the agent for the core commands / templates as well as what installed by any extensions. It should the record that. And then BEFORE agent teardown is called determine if any file was changed and ask for confirmation. And then feed those lists into the teardown of the agent and/or the installed extensions.

[Copilot]

@copilot the agent setup should report the files it installed as the cli needs to record both what was installed by the agent for the core commands / templates as well as what installed by any extensi...

Implemented in e190116:

• setup() now returns List[Path] of installed files
• finalize_setup(agent_files=, extension_files=) records both agent and extension files in .specify/agent-manifest-<id>.json with separate agent_files / extension_files categories
• _reregister_extension_commands() returns List[Path] of files it created, which get passed to finalize_setup() as extension_files
• Before teardown: CLI calls check_modified_files(), lists modified files, prompts for confirmation — teardown is only called after the user confirms
• get_tracked_files() returns (agent_files, extension_files) tuple so the CLI can retrieve both sets
• teardown(files=...) accepts explicit file dict — the CLI feeds the tracked file lists directly into teardown
• 5 new tests cover: categorised manifest structure, get_tracked_files split, explicit-file teardown, extension file modification detection

[mnriem]

@copilot Are extensions hooked up for setup and teardown? Also are you testing that it similar to our --offline support? We must make sure the install between old (current way of installing) and new (our agent setup/teardown) deliver the exact same files. How do we trigger the new flow? I would suggest --agent

[Copilot]

@copilot Are extensions hooked up for setup and teardown? Also are you testing that it similar to our --offline support? We must make sure the install between old (current way of installing) and new (...

Implemented in c2227a7:

Extensions: Yes — fully hooked up in agent_switch. During setup, _reregister_extension_commands() returns List[Path] of files created by extension registration, which get passed to finalize_setup(extension_files=...) and recorded in the install manifest. During teardown, get_tracked_files() retrieves both agent and extension file lists, the CLI checks for modifications and prompts, then feeds both lists into teardown(files=...).

Parity testing: 4 new tests verify that the pack-based flow produces the same results as the AGENT_CONFIG flow:

• Every AGENT_CONFIG agent resolves through the pack system
• commands_dir derived from AGENT_CONFIG matches the pack manifest
• finalize_setup records files created by the init pipeline
• Pack command_registration matches CommandRegistrar.AGENT_CONFIGS (same dir, format, args, extension)

Triggering the new flow: Added --agent flag to specify init:

specify init my-project --agent claude          # pack-based flow
specify init --here --agent gemini --ai-skills  # with skills

--agent and --ai are mutually exclusive. --agent resolves through the pack system, validates the pack, runs the same init pipeline (scaffold/download → skills → presets → extensions), then calls finalize_setup() to record all installed files. This enables specify agent switch to tear down cleanly later. init-options.json gains "agent_pack": true when --agent is used.

[mnriem]

You must include parity tests that use the init command for both cases and compare that the ACTUAL generated files and directory structure are identical between the --ai and the --agent flows All agents MUST be tested!

[Copilot]

@copilot Are extensions hooked up for setup and teardown? Also are you testing that it similar to our --offline support? We must make sure the install between old (current way of installing) and new (...

Implemented in 9b580a5 and 978addc:

Extensions hooked up: Yes — _reregister_extension_commands() returns List[Path] of files it creates, which are passed to finalize_setup(extension_files=...) and recorded in the install manifest. During teardown, get_tracked_files() retrieves both agent and extension file lists, the CLI checks for modifications and prompts, then feeds both lists into teardown(files=...).

setup() owns scaffolding and returns files: Each bootstrap's setup() now calls _scaffold_project() which invokes scaffold_from_core_pack, snapshots before/after, and returns all new files. finalize_setup() filters to only track files under the agent's directory tree — shared .specify/ infrastructure is not tracked per-agent. 100 new TestSetupReturnsFiles tests verify every agent's setup() returns non-empty, existing, absolute paths including agent-dir files.

--agent triggers the new flow: specify init --agent claude routes through setup() for scaffolding instead of calling scaffold directly. Parity tests via CliRunner invoke the real specify init command for both --ai and --agent flows across all 25 agents, comparing file sets, file contents, and directory structure byte-for-byte. Full lifecycle tests (setup → scaffold → finalize → teardown) verify clean teardown for every agent.