Rewrite AGENTS.md for integration architecture (#2119)

* Rewrite AGENTS.md for integration subpackage architecture

Replaces the old AGENT_CONFIG dict-based 7-step process with documentation
reflecting the integration subpackage architecture shipped in #1924.

Removed: Supported Agents table, old step-by-step guide referencing
AGENT_CONFIG/release scripts/case statements, Agent Categories lists,
Directory Conventions section, Important Design Decisions section.

Kept: About Spec Kit and Specify, Command File Formats, Argument Patterns,
Devcontainer section.

Added: Architecture overview, decision tree for base class selection,
configure/register/scripts/test/override steps with real code examples
from existing integrations (Windsurf, Gemini, Codex, Copilot).

Agent-Logs-Url: https://github.com/github/spec-kit/sessions/71b25c53-7d0c-492a-9503-f40a437d5ece

Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com>

* Fix JSONC comment syntax in devcontainer example

Agent-Logs-Url: https://github.com/github/spec-kit/sessions/71b25c53-7d0c-492a-9503-f40a437d5ece

Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com>

* docs(AGENTS.md): address Copilot PR review comments

- Clarify that integrations are registered by _register_builtins() in
  __init__.py, not self-registered at import time
- Scope the key-must-match-executable rule to CLI-based integrations
  (requires_cli: True); IDE-based integrations use canonical identifiers
- Replace <commands_dir> placeholder in test snippet with a concrete
  example path (.windsurf/workflows/)
- Document that hyphens in keys become underscores in test filenames
  (e.g. cursor-agent -> test_integration_cursor_agent.py)
- Note that the argument placeholder is integration-specific
  (registrar_config["args"]); add Forge's {{parameters}} as an example
- Apply consistency fixes to Required fields table, Key design rule
  callout, and Common Pitfalls #1

* docs(AGENTS.md): clarify scripts path uses Python-safe package_dir not key

The scripts step previously referenced src/specify_cli/integrations/<key>/scripts/
but for hyphenated keys the actual directory is underscored (e.g. kiro-cli -> kiro_cli/).
Rename the placeholder to <package_dir> and add a note explaining:
- <package_dir> matches <key> for non-hyphenated keys
- <package_dir> uses underscores for hyphenated keys (e.g. kiro-cli -> kiro_cli/)
- IntegrationBase.key always retains the original hyphenated value

Addresses: https://github.com/github/spec-kit/pull/2119#discussion_r3054946896

* docs(AGENTS.md): use <key_with_underscores> in pytest example command

The pytest command previously used <key> as a placeholder, but test
filenames always use underscores even for hyphenated keys. This was
internally inconsistent since the preceding sentence already explained
the hyphen→underscore mapping. Switch to <key_with_underscores> to
match the actual filename on disk.

Addresses: https://github.com/github/spec-kit/pull/2119#discussion_r3054962863

* docs(AGENTS.md): use <package_dir> in step 2 subpackage path

The path src/specify_cli/integrations/<key>/__init__.py was inaccurate
for hyphenated keys (e.g. kiro-cli lives in kiro_cli/, not kiro-cli/).
Rename the placeholder to <package_dir>, define it inline (hyphens
become underscores), and note that IntegrationBase.key always retains
the original hyphenated value.

Addresses: https://github.com/github/spec-kit/pull/2119#discussion_r3058050583

* docs(AGENTS.md): qualify 'single source of truth' to Python metadata only

The registry is only authoritative for Python integration metadata.
Context-update dispatcher scripts (bash + PowerShell) still require
explicit per-agent cases and maintain their own supported-agent lists
until they are migrated to registry-based dispatch. Tighten the claim
to avoid misleading contributors into skipping the script updates.

Addresses: https://github.com/github/spec-kit/pull/2119#pullrequestreview-4083090261

* docs(AGENTS.md): mention ValidateSet update in PowerShell dispatcher step

The update-agent-context.ps1 script has a [ValidateSet(...)] on the
AgentType parameter. Without adding the new key to that list, the script
rejects the argument before reaching Update-SpecificAgent. Add this as
an explicit step alongside the switch case and Update-AllExistingAgents.

Addresses: https://github.com/github/spec-kit/pull/2119#pullrequestreview-4083217694

* fix(integrations): sort codebuddy before codex in _register_builtins()

Both the import list and the _register() call list had codex before
codebuddy, violating the alphabetical ordering that AGENTS.md documents.
Swap them so the file matches the documented convention.

Addresses: https://github.com/github/spec-kit/pull/2119#pullrequestreview-4083341590

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com>

src/specify_cli/integrations/__init__.py

@@ -51,8 +51,8 @@ def _register_builtins() -> None:
     from .auggie import AuggieIntegration
     from .bob import BobIntegration
     from .claude import ClaudeIntegration
-    from .codex import CodexIntegration
     from .codebuddy import CodebuddyIntegration
+    from .codex import CodexIntegration
     from .copilot import CopilotIntegration
     from .cursor_agent import CursorAgentIntegration
     from .forge import ForgeIntegration
@@ -80,8 +80,8 @@ def _register_builtins() -> None:
     _register(AuggieIntegration())
     _register(BobIntegration())
     _register(ClaudeIntegration())
-    _register(CodexIntegration())
     _register(CodebuddyIntegration())
+    _register(CodexIntegration())
     _register(CopilotIntegration())
     _register(CursorAgentIntegration())
     _register(ForgeIntegration())