{"record":{"id":"fcf5a622631f9a64","repo":"github/spec-kit","slug":"unsupported-agent-agent-name-fcf5a6","errorCode":null,"errorMessage":"Unsupported agent: {agent_name}","messagePattern":"Unsupported agent: (.+?)","errorType":"exception","errorClass":"ExtensionError","httpStatus":null,"severity":"error","filePath":"src/specify_cli/extensions/__init__.py","lineNumber":3530,"sourceCode":"    def _render_toml_command(self, frontmatter, body, ext_id):\n        # Preserve extension-specific context comments for backward compatibility\n        base = self._registrar.render_toml_command(frontmatter, body, ext_id)\n        context_lines = (\n            f\"# Extension: {ext_id}\\n# Config: .specify/extensions/{ext_id}/\\n\"\n        )\n        return base.rstrip(\"\\n\") + \"\\n\" + context_lines\n\n    def register_commands_for_agent(\n        self,\n        agent_name: str,\n        manifest: ExtensionManifest,\n        extension_dir: Path,\n        project_root: Path,\n        link_outputs: bool = False,\n    ) -> List[str]:\n        \"\"\"Register extension commands for a specific agent.\"\"\"\n        if agent_name not in self.AGENT_CONFIGS:\n            raise ExtensionError(f\"Unsupported agent: {agent_name}\")\n        context_note = f\"\\n<!-- Extension: {manifest.id} -->\\n<!-- Config: .specify/extensions/{manifest.id}/ -->\\n\"\n        return self._registrar.register_commands(\n            agent_name,\n            manifest.commands,\n            manifest.id,\n            extension_dir,\n            project_root,\n            context_note=context_note,\n            link_outputs=link_outputs,\n            extension_id=manifest.id,\n        )\n\n    def register_commands_for_all_agents(\n        self,\n        manifest: ExtensionManifest,\n        extension_dir: Path,\n        project_root: Path,\n        link_outputs: bool = False,","sourceCodeStart":3512,"sourceCodeEnd":3548,"githubUrl":"https://github.com/github/spec-kit/blob/bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c/src/specify_cli/extensions/__init__.py#L3512-L3548","documentation":"ExtensionManager.register_commands_for_agent refuses to install an extension's commands for an agent name that is not a key in the class-level AGENT_CONFIGS mapping. The mapping is the closed set of agents the extension command registrar knows how to write command files for.","triggerScenarios":"Calling register_commands_for_agent(agent_name, ...) with a name absent from ExtensionManager.AGENT_CONFIGS — e.g. a typo ('claude-code' vs 'claude'), a newly added integration key that was never added to AGENT_CONFIGS, or a removed/renamed agent key.","commonSituations":"Adding a new integration to the CLI registry but forgetting the extensions layer's AGENT_CONFIGS; scripts passing a user-supplied agent name straight through; version skew between a tool that lists integrations and the installed specify_cli version.","solutions":["Print the supported set and use one of those keys: `python -c \"from specify_cli.extensions import ExtensionManager; print(ExtensionManager.AGENT_CONFIGS.keys())\"`","Fix typos/casing: keys are exact identifiers like 'claude', 'gemini', 'copilot', not display names","If you added a new integration, add its key to AGENT_CONFIGS alongside the registrar config","Upgrade specify_cli if the agent is supported in a newer release"],"exampleFix":"# before\nmanager.register_commands_for_agent(\"Claude Code\", manifest, ext_dir, project_root)\n\n# after\nmanager.register_commands_for_agent(\"claude\", manifest, ext_dir, project_root)","handlingStrategy":"type-guard","validationCode":"from specify_cli.extensions import ExtensionManager\n\ndef is_supported_agent(name: str) -> bool:\n    return name in ExtensionManager.AGENT_CONFIGS\n\nagent = \"claude\"\nassert is_supported_agent(agent)","typeGuard":"from specify_cli.extensions import ExtensionManager\n\ndef assert_supported_agent(name: str) -> None:\n    \"\"\"Type-guard: raise early with the valid key set on unknown agents.\"\"\"\n    if name not in ExtensionManager.AGENT_CONFIGS:\n        raise ValueError(\n            f\"Unsupported agent {name!r}; \"\n            f\"expected one of {sorted(ExtensionManager.AGENT_CONFIGS)}\"\n        )","tryCatchPattern":null,"preventionTips":["Always source agent names from ExtensionManager.AGENT_CONFIGS keys, never free-form user input","When adding integrations, update AGENT_CONFIGS in the same change"],"tags":["extensions","agent-integration","validation"],"backgroundTag":null,"analyzedSha":"bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c","analyzedAt":"2026-08-14T19:43:37.150Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}