Stage 1: Integration foundation — base classes, manifest system, and registry

[Copilot]

Stage 1 of #1924 — ships the base classes and manifest system for the integration architecture. Purely additive — no behavior changes to existing code.

What's in this PR

src/specify_cli/integrations/__init__.py — Integration registry

• INTEGRATION_REGISTRY dict (empty — populated in later stages)
• _register() and get_integration() helpers

src/specify_cli/integrations/base.py — Base classes

• IntegrationOption — frozen dataclass declaring CLI options an integration accepts
• IntegrationBase ABC — key, config, registrar_config, context_file, setup(), teardown(), install(), uninstall(), templates_dir(), options()
• MarkdownIntegration(IntegrationBase) — concrete base for ~20 standard markdown agents (subclass, set three attrs, done)

src/specify_cli/integrations/manifest.py — Hash-tracked file management

• IntegrationManifest with record_file(), record_existing(), check_modified(), save()/load() persistence
• uninstall() — only removes files whose SHA-256 still matches; modified files are skipped and reported
• Empty parent directory cleanup on uninstall

tests/test_integrations.py — 34 tests

• IntegrationOption (4), IntegrationBase/MarkdownIntegration (7), manifest record/hash (3), modified detection (3), uninstall (7), persistence (5), registry (3)
• 98% code coverage on the new modules

What stays unchanged

Everything. This stage is purely additive — no existing files modified, all 929 existing tests pass.

[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]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

src/specify_cli/integrations/manifest.py:179

• uninstall() deletes the manifest file unconditionally, even when some files are skipped due to modification. This makes it impossible to re-run uninstall in a later CLI invocation with force=True (or after reverting changes) because the manifest state is gone. A safer pattern is to only remove the manifest when all tracked files were removed (or force=True), or to rewrite the manifest to contain only the remaining/skipped entries.

        # Remove the manifest file itself
        manifest = root / ".specify" / "integrations" / f"{self.key}.manifest.json"
        if manifest.exists():
            manifest.unlink()
            parent = manifest.parent
            while parent != root:
                try:
                    parent.rmdir()
                except OSError:
                    break
                parent = parent.parent

        return removed, skipped

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.