Skip to main content

add Mode Steps

Add one agent to an existing setup without re-running the full interview.

Step 1 — Ask​

What role should the new agent have?
  (e.g. "data-pipeline", "ml", "security", "release" — or describe what it should own)

Then:

What files/directories does it own?
What is explicitly off-limits for it?
What triggers a handoff to it from the coordinator?

Step 2 — Find coordinator and read context​

# Look in all five output targets — not just Copilot/Cursor
COORD=$(ls .github/agents/coordinator.agent.md \
           .cursor/rules/coordinator.mdc 2>/dev/null | head -1)

# No per-agent files: the openai.yaml roster metadata holds every agent — read it whole
[ -z "$COORD" ] && [ -f agents/openai.yaml ] && COORD=agents/openai.yaml

# Claude Code only: Agent Context table in CLAUDE.md
[ -z "$COORD" ] && grep -q "## Agent Context" CLAUDE.md 2>/dev/null && COORD=CLAUDE.md

[ -n "$COORD" ] && cat "$COORD"
cat AGENTS.md 2>/dev/null

Note: when COORD is agents/openai.yaml or CLAUDE.md, the file contains all agents — read it for full roster context, not just the coordinator entry.

Step 3 — Generate new agent​

Use 3-section format from references/setup-agents-prompts.md. Apply the managed-file marker in the correct comment syntax for the target format — see references/setup-agents-schemas.md → "Managed-file marker".

Overwrite guard — before writing any file that already exists:

managed() { head -3 "$1" 2>/dev/null | grep -q 'generated by platform-skills'; }
# if [ -f "$target" ] && ! managed "$target"; then warn and skip fi

head -3 is required, not cosmetic — .agent.md and .mdc carry the marker on line 2, inside the frontmatter. See references/setup-agents-schemas.md → "Managed-file marker".

Include in ## Boundaries:

**Always read `AGENTS.md` first** before acting on any request.

Active staleness guard: verify every path referenced in ## How to work here exists before writing.

Step 3b — Model selection​

Use the default suggestion for the role (see generate mode Step 6b role table). Ask the developer to confirm or change:

Suggested model for <role>: <tier-default>
Accept or change?

Write model: only in targets that support it (Copilot .agent.md, Codex agents/openai.yaml). Omit for Cursor .mdc and Claude Code CLAUDE.md.

Step 4 — Patch coordinator​

Add handoff entry for the new agent to coordinator's ## Boundaries section.

Step 5 — Update AGENTS.md​

  • Managed (marker present): add row to Agent roster table
  • Hand-authored: append new row at the bottom of the roster section only

Step 6 — Update metadata block​

Append to the <!-- setup-agents metadata --> block in AGENTS.md:

additions:
  - date: YYYY-MM-DD
    agent: <role>
    reason: |
      <why this agent was added>

Step 7 — Update .platform-skills/manifest​

If .platform-skills/manifest exists, append the new tool target(s) for this agent. This keeps scripts/verify-agents.sh aware of the new output:

# Example: adding the first Cursor agent to a Copilot-only repo
echo "cursor" >> .platform-skills/manifest

Valid manifest tokens: copilot-vscode, copilot-cloud, copilot-app, cursor, claude, codex, windsurf, vscode-mcp. One token per line. Lines starting with # are comments. Do not add duplicate tokens — check first:

grep -qx "cursor" .platform-skills/manifest 2>/dev/null || echo "cursor" >> .platform-skills/manifest

If .platform-skills/manifest does not exist (setup pre-dates manifest support), create it and populate from the agents that are currently present:

ls .github/agents/*.agent.md 2>/dev/null && echo "copilot-vscode" >> .platform-skills/manifest
ls .cursor/rules/*.mdc 2>/dev/null && echo "cursor" >> .platform-skills/manifest
grep -q '## Agent Context' CLAUDE.md 2>/dev/null && echo "claude" >> .platform-skills/manifest
test -f agents/openai.yaml && echo "codex" >> .platform-skills/manifest