Rewrite AGENTS.md for integration subpackage architecture

[mnriem]

Summary

Rewrite AGENTS.md to reflect the integration subpackage architecture shipped in #1924. The current content describes the old AGENT_CONFIG dict-based process and references removed artifacts (release ZIPs, case-statement scripts, --ai-skills flags).

Problem

AGENTS.md is consumed by AI coding agents working on the codebase. Stale instructions cause agents to follow the old 7-step process (edit AGENT_CONFIG, update help text, modify release scripts, add case statements, etc.) instead of the current approach.

What to keep

• About Spec Kit and Specify — still accurate
• Command File Formats (Markdown, TOML) — still accurate, compact reference
• Argument Patterns — still accurate, rarely changes
• Devcontainer section — still valid

What to remove

• Supported Agents table — redundant with integration class definitions (config, registrar_config); creates maintenance drift. specify integration list (Add specify integration subcommand for post-init integration management #2065) will provide this programmatically.
• Step-by-step guide (all 7 steps) — references AGENT_CONFIG, release scripts, case statements, --ai-skills flag — all removed
• Important Design Decisions / Cursor Lesson — principle still valid but needs new framing (integration key, not dict key)
• Agent Categories lists — redundant with requires_cli field in each integration class
• Directory Conventions — derivable from registrar_config.dir in each integration

What to write

The new guide should cover:

1. Architecture overview

Brief description of the integration subpackage structure: integrations/<key>/

2. Decision tree: which base class?

Need	Subclass
Standard markdown commands	MarkdownIntegration
TOML format	TomlIntegration
Skill directories (speckit-<name>/SKILL.md)	SkillsIntegration
Fully custom (companion files, settings merge, etc.)	IntegrationBase directly

3. Configure it (4 required fields)

• key — matches actual CLI tool name
• config — name, folder, commands_subdir, install_url, requires_cli
• registrar_config — dir, format, args, extension
• context_file — path to agent context file (optional)

4. Register it

One import + one _register() call in _register_builtins()

5. Add scripts

scripts/update-context.sh and scripts/update-context.ps1 (~5 lines each)

6. Test it

specify init --integration <key> + install/uninstall round-trip

7. Optional overrides

• command_filename() for custom output patterns
• options() for integration-specific CLI flags
• setup() for custom install logic

Depends on

• From Agents to Integrations #1924 (integration architecture — merged)

[dhilipkumars]

nice improvements to --ai-skills , feel free to tag or assign issues to me if you need another pair of hands.

[mnriem]

@dhilipkumars You could take the linked PR #2068 all the way?

[dhilipkumars]

Awesome yeah will do.

[dhilipkumars]

@mnriem FYI , ive started and i took the commits into a new PR , as i dont have push access to this repo yet. #2119

hope thats okay with you.

[mnriem]

Closing this in favor of #2119