feat(agents): Add subagent runtime support

[dcramer]

Add [[subagents]] so a repo can declare reusable coding-agent subagents once, install them into .agents/agents/, and generate runtime-native files for Claude, Cursor, Codex, and OpenCode.

Typical Project Usage

A project can point at a shared agent pack and let dotagents generate files for every configured runtime that supports subagents:

version = 1
agents = ["claude", "cursor", "codex", "opencode"]

[[subagents]]
name = "code-reviewer"
source = "getsentry/agent-pack"

If the upstream repo contains agents/code-reviewer.md, dotagents install writes the canonical installed file plus runtime outputs:

.agents/agents/code-reviewer.md
.claude/agents/code-reviewer.md
.cursor/agents/code-reviewer.md
.codex/agents/code-reviewer.toml
.opencode/agents/code-reviewer.md

Native Sources Stay Native

Teams can also publish native agent files directly. For example, a Codex-first source can keep Codex-specific fields in .codex/agents/code-reviewer.toml:

name = "code_reviewer"
description = "Review code for correctness and missing tests."
developer_instructions = "Review the current diff and return actionable findings."
sandbox_mode = "read-only"

When installing to Codex, dotagents preserves that TOML as the Codex output and only adds the managed-file marker. When installing to Claude, Cursor, or OpenCode, it generates Markdown from the portable name, description, and instructions instead of trying to standardize Codex-only behavior.

Explicit File Selection

Conventional directories such as agents/, .agents/agents/, .claude/agents/, .cursor/agents/, .codex/agents/, and .opencode/agents/ are discovered automatically. Root-level Markdown files require an explicit path so unrelated docs do not get imported by accident:

[[subagents]]
name = "release-notes"
source = "getsentry/agent-pack"
path = "release-notes.md"

Install and sync both understand the generated files. install --frozen validates declared subagents against agents.lock, sync repairs or prunes managed subagent files without network access, and doctor --fix preserves lockfile subagent ignore entries until stale files are pruned.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
dotagents	Ready	Preview, Comment	Jun 12, 2026 5:10am

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit ff95532. Configure here.}

[sentry]

Bug: The regex in parseMarkdownFrontmatterContent for extracting frontmatter is non-greedy and will terminate prematurely if a YAML block scalar's content contains a line with just ---.
_{Severity: MEDIUM}

Suggested Fix

Replace the regular expression-based frontmatter extraction with a more robust parsing mechanism that correctly handles YAML document separators and does not fail on content that coincidentally contains separator-like sequences.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: packages/dotagents/src/agents/definitions/helpers.ts#L189-L192

Potential issue: The function `parseMarkdownFrontmatterContent` uses a non-greedy
regular expression to extract YAML frontmatter from markdown files. This regex will
terminate at the first occurrence of a line containing `---`. If a native subagent's
content, which is stored inside a YAML block scalar, contains a `---` sequence on its
own line (e.g., as a separator in TOML comments), the regex will incorrectly truncate
the frontmatter. This will cause the subsequent YAML parsing to fail with a
`SkillLoadError`, preventing the subagent from being loaded and presenting a potentially
confusing error to the user.