feat(init): add shared agents skills target

[solanab]

Summary

• Adds agents as a first-class skills-backed tool target in AI_TOOLS, writing OpenSpec skills to .agents/skills/openspec-*/SKILL.md.
• Covers init, update, tool detection, and the deprecated experimental --tool agents alias through the existing shared skillsDir code paths.
• Documents the new agents tool ID and .agents/skills path, while keeping .pi / .codex migration behavior out of scope.

Related

• Closes Add generic .agents installer option for agentic tools #1104
• Related to fix(antigravity): update skill and workflow paths from .agent to .agents #830 and feat(codex): migrate .codex skills to .agents #1157, but intentionally scoped to adding the generic installer target rather than migrating existing vendor-specific roots.

Scope Notes

This PR does not add .pi -> .agents or .codex -> .agents migration logic.
Those migrations can remain separate follow-up work and should not block the vendor-neutral init target.

Test Plan

• pnpm run build
• pnpm exec tsc --noEmit
• pnpm lint (passes with existing warning in src/core/references.ts)
• Focused regression suite: pnpm exec vitest run test/core/init.test.ts test/core/available-tools.test.ts test/core/shared/tool-detection.test.ts test/core/update.test.ts test/commands/artifact-workflow.test.ts test/cli-e2e/basic.test.ts → 217 passed
• git diff --check

Local Full-Suite Note

pnpm test mostly passes locally but one environment-sensitive workset test fails on this machine because the real claude CLI is installed and returns its own --print error instead of the expected OpenSpec launch-failure wrapper:

• test/commands/workset.test.ts → a launch failure carries a pasteable alternative and the manual route

A separate timeout in test/cli-e2e/capstone-journeys.test.ts passed when rerun directly.

Summary by CodeRabbit

• New Features

  • Added support for an AGENTS-compatible tool target in initialization and update workflows.
  • The shared skills directory can now be created and detected as a valid tool location.

• Bug Fixes

  • Improved tool detection so the AGENTS-compatible target is recognized instead of being ignored.
  • openspec init now creates the expected shared skills path for selected tools.

• Documentation

  • Updated CLI and supported-tools docs to include the new tool option and generated directory structure.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: f27bc8e7-521d-4a08-b9b8-75777ddb756a

📥 Commits

Reviewing files that changed from the base of the PR and between 65a7233 and f247b43.

📒 Files selected for processing (14)

• docs/cli.md
• docs/supported-tools.md
• openspec/changes/add-init-agents-target/.openspec.yaml
• openspec/changes/add-init-agents-target/proposal.md
• openspec/changes/add-init-agents-target/specs/ai-tool-paths/spec.md
• openspec/changes/add-init-agents-target/specs/cli-init/spec.md
• openspec/changes/add-init-agents-target/tasks.md
• src/core/config.ts
• test/cli-e2e/basic.test.ts
• test/commands/artifact-workflow.test.ts
• test/core/available-tools.test.ts
• test/core/init.test.ts
• test/core/shared/tool-detection.test.ts
• test/core/update.test.ts

---

📝 Walkthrough

Walkthrough

This PR enables agents as a first-class, adapterless openspec init/update skills target rooted at .agents, adding a proposal/spec change set, config flag flip, documentation updates, and test coverage across init, update, detection, and deprecated alias flows.

Changes

Generic agents installer target

Layer / File(s)	Summary
Enable agents in config src/core/config.ts	Flips available from false to true for the AGENTS.md tool entry, enabling agents as a selectable skills-only target.
Proposal and spec documents openspec/changes/add-init-agents-target/.openspec.yaml, .../proposal.md, .../tasks.md, .../specs/ai-tool-paths/spec.md, .../specs/cli-init/spec.md	Adds proposal, task checklist, and spec requirements defining agents as a vendor-neutral shared skills target at .agents/skills/openspec-*/SKILL.md, with detection logic and preserved .pi/.codex migration behavior.
CLI documentation updates docs/cli.md, docs/supported-tools.md	Documents agents as a supported --tools ID, its .agents/skills/ output path, and that no command adapter is generated.
Test coverage for init/update/detection/alias test/cli-e2e/basic.test.ts, test/commands/artifact-workflow.test.ts, test/core/available-tools.test.ts, test/core/init.test.ts, test/core/shared/tool-detection.test.ts, test/core/update.test.ts	Adds/updates tests verifying agents skill file creation via init, deprecated experimental --tool agents alias, tool detection inclusion, update of existing agents skills, and test environment isolation via XDG config temp dirs.

Estimated code review effort: 2 (Simple) | ~15 minutes

Possibly related PRs

• Fission-AI/OpenSpec#1003: Adds a similar adapterless skills-only tool entry (kimi) in src/core/config.ts and extends the same InitCommand tests pattern.

Suggested reviewers: TabishB, alfred-openspec

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	Clearly summarizes the main change: adding a shared agents skills target for init.
Linked Issues check	✅ Passed	The PR satisfies #1104 by adding .agents support to init/update, enabling non-interactive selection, and documenting the generic target.
Out of Scope Changes check	✅ Passed	The code, docs, and tests all align with the .agents installer target; no unrelated feature work is evident.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}