Address review comments. Update docs

Author: Eric Engstfeld

docs/reference/integrations.md

@@ -6,6 +6,7 @@ The Specify CLI supports a wide range of AI coding agents. When you run `specify
 
 | Agent                                                                                | Key              | Notes                                                                                                                                     |
 | ------------------------------------------------------------------------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| [Alquimia AI](https://docs.alquimia.ai)                                              | `alquimia`       | Skills-based integration; installs skills into `.alquimia/skills` and invokes them as `/speckit-<command>`                                |
 | [Amp](https://ampcode.com/)                                                          | `amp`            |                                                                                                                                           |
 | [Antigravity (agy)](https://antigravity.google/)                                     | `agy`            | Skills-based integration; skills are installed automatically                                                                               |
 | [Auggie CLI](https://docs.augmentcode.com/cli/overview)                              | `auggie`         |                                                                                                                                           |
@@ -260,6 +261,7 @@ The currently declared multi-install safe integrations are:
 
 | Key | Isolation |
 | --- | --------- |
+| `alquimia` | `.alquimia/skills` |
 | `auggie` | `.augment/commands`, `.augment/rules/specify-rules.md` |
 | `claude` | `.claude/skills`, `CLAUDE.md` |
 | `cline` | `.clinerules/workflows`, `.clinerules/specify-rules.md` |

integrations/catalog.json

@@ -1,6 +1,6 @@
 {
   "schema_version": "1.0",
-  "updated_at": "2026-07-15T00:00:00Z",
+  "updated_at": "2026-07-27T00:00:00Z",
   "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/integrations/catalog.json",
   "integrations": {
     "alquimia": {

src/specify_cli/integrations/alquimia/__init__.py

@@ -2,12 +2,10 @@
 
 from __future__ import annotations
 
-from pathlib import Path
 from typing import Any
 
 from ..._utils import dump_frontmatter
 from ..base import SkillsIntegration
-from ..manifest import IntegrationManifest
 
 # Mapping of command template stem → argument-hint text shown inline
 # when a user invokes the slash command in Alquimia AI.
@@ -165,45 +163,3 @@ def post_process_skill_content(self, content: str) -> str:
                     updated = self.inject_argument_hint(updated, hint)
                 break
         return updated
-
-    def setup(
-        self,
-        project_root: Path,
-        manifest: IntegrationManifest,
-        parsed_options: dict[str, Any] | None = None,
-        **opts: Any,
-    ) -> list[Path]:
-        """Install Alquimia skills, then inject Alquimia-specific flags and argument-hints."""
-        created = super().setup(project_root, manifest, parsed_options, **opts)
-
-        # Post-process generated skill files
-        skills_dir = self.skills_dest(project_root).resolve()
-
-        for path in created:
-            # Only touch SKILL.md files under the skills directory
-            try:
-                path.resolve().relative_to(skills_dir)
-            except ValueError:
-                continue
-            if path.name != "SKILL.md":
-                continue
-
-            content_bytes = path.read_bytes()
-            content = content_bytes.decode("utf-8")
-
-            updated = content
-
-            # Inject argument-hint if available for this skill
-            skill_dir_name = path.parent.name  # e.g. "speckit-plan"
-            stem = skill_dir_name
-            if stem.startswith("speckit-"):
-                stem = stem[len("speckit-") :]
-            hint = ARGUMENT_HINTS.get(stem, "")
-            if hint:
-                updated = self.inject_argument_hint(updated, hint)
-
-            if updated != content:
-                path.write_bytes(updated.encode("utf-8"))
-                self.record_file_in_manifest(path, project_root, manifest)
-
-        return created

tests/integrations/test_integration_alquimia.py

@@ -32,6 +32,29 @@ def test_registrar_config_uses_skill_layout(self):
         assert integration.registrar_config["args"] == "$ARGUMENTS"
         assert integration.registrar_config["extension"] == "/SKILL.md"
 
+    def test_requires_cli_is_true(self):
+        integration = get_integration("alquimia")
+        assert integration.config["requires_cli"] is True
+        assert integration.multi_install_safe is True
+
+    def test_build_exec_args_uses_headless_prompt_flag(self):
+        """Workflow dispatch relies on the inherited
+        ``SkillsIntegration.build_exec_args()`` — pin its argv shape so a
+        future change to the base class or this integration's config is
+        caught here rather than surfacing as a silent workflow failure."""
+        integration = get_integration("alquimia")
+        args = integration.build_exec_args(
+            "hello", model="alquimia-default", output_json=True
+        )
+        assert args is not None
+        assert args[0] == "alquimia" or args[0].endswith("/alquimia")
+        assert "-p" in args
+        assert "hello" in args
+        assert "--model" in args
+        assert "alquimia-default" in args
+        assert "--output-format" in args
+        assert "json" in args
+
     def test_setup_creates_skill_files(self, tmp_path):
         integration = get_integration("alquimia")
         manifest = IntegrationManifest("alquimia", tmp_path)