feat(cli): emit antigravity agents as portable .agents/agents/<name>/agent.md - #960

🎯 What & why

aidd setup --ai antigravity now installs AIDD's agents where agy discovers them. Phase 4 of #511, stacked on #958.

🛠️ How it works

• Path. build.ts writes each plugin agent to .agents/agents/<plugin>-<agent>/agent.md. That nested layout is the one agy documents; AIDD never writes <name>.md. Body links are resolved from the nested directory.

• Frontmatter rebuilt, not copied. portable-agent.ts is meant to be reused by feat(cli): emit portable Markdown agents under .agents/agents #916 for Codex flat and Kimi. It keeps:

  • name;
  • the source description (a blank one throws InvalidAgentFrontmatterError, naming the agent);
  • model: inherit;
  • tools as a YAML list, only when the source declares tools.

  Every other key is dropped.

• Why rebuild. Measured on agy 1.2.17 with /agents: an agent with model: opus and one with tools: view_file, grep_search are both absent from the list, without any error. An agent with no tools, or with Claude tool names in a YAML list, is listed.

• No AgentsCapability. That capability would also enable the raw fallback route (flatSectionFile), which copies Claude frontmatter to .agents/agents/<plugin>/<file>.md, a file agy would drop. setup takes the built-tree route, which reads this artifact. The plan is updated to match.

• Bundle budget 766 → 771 KB. Measured with tsup on the stack:

  Branch	Bundle	Budget
  next (stack base)	755.6 KB	756 KB
  feat(cli): add Antigravity CLI as a flat host for skills #957	757.9 KB	766 KB
  feat(cli): merge plugin hooks into antigravity's .agents/hooks.json #958	762.4 KB	766 KB
  this PR	764.2 KB	771 KB

  This PR adds 1.8 KB; check-bundle-size.mjs records each branch's own figure.

• Bracketed values are quoted. serializeFrontmatter writes a value raw only when it parses as a JSON array, so a description like [WIP] foo [x] stays a string and Cursor's globs keep their inline array.

🧪 How to verify

• cd cli && pnpm test: 7093 passed, 1 skipped. CI cli / Smoke green.
• Golden: only antigravity:flat moves, with 4 fixture agents at .agents/agents/<name>/agent.md.
• Live, 2026-10-05, agy 1.2.17, fresh git repo:
  1. aidd setup --source local --path <framework> --ai antigravity --plugins recommended --yes writes .agents/agents/aidd-dev-{checker,executor}/agent.md, recorded in .aidd/manifest.json.
  2. agy --add-dir <repo> --output-format json -p "/agents" exits 0 with "agents":["aidd-dev-checker","aidd-dev-executor"]. The invented name aidd-dev-ghost is absent.
  3. aidd clean --force removes them, and .agents/ is gone.

⚠️ Heads-up

• Discovery is proven, execution is not. feat(cli): emit portable Markdown agents under .agents/agents #916's AIDD_PORTABLE_AGENT_OK execution marker is left to feat(cli): emit portable Markdown agents under .agents/agents #916.
• Mutations run before commit: setting model back to the source value fails the model test; computing links from a non-nested path fails the body test.
• Not in this PR (feat(cli): emit portable Markdown agents under .agents/agents #916's scope): rejecting a duplicate name at another path.

🔗 Linked issue

Refs #511, #916

✅ I certify

• I DO CERTIFY I READ EACH LINE OF THE PULL REQUEST BECAUSE I AM A SOFTWARE ENGINEER, NOT A AI PUPPY.

🤖 Generated with Claude Code