Ytthuan Agents System Setup Agents System Setup

Setup Copilot Agents (multi-platform)

Scaffold or update a complete agent system for the current project across Copilot CLI, Claude Code, OpenCode, OpenAI Codex (CLI + App), and/or Gemini CLI. Produces a canonical AGENTS.md (with Orchestration Operating Model, Directory Architecture, Agent Roster, Capability Matrix, Security & Audit Matrix, Threat Model, and Architecture / Design Decisions), specialized subagent files (no orchestrator file — the host CLI session reads AGENTS.md), project-scoped skills, and approved plugins/MCP servers — derived from a structured interview.

When to Use

• Brand-new repository needs an agent setup from scratch (init)
• Existing project should adopt or extend the orchestrator + subagent pattern (update)
• Existing agent system needs an audit and targeted upgrades (improve)
• Agents authored for one runtime need to be ported to another (replicate — Copilot ↔ Claude Code ↔ OpenCode ↔ OpenAI Codex ↔ Gemini)
• Discovering relevant plugins / MCP servers from the well-known marketplaces

Hard Rules

1. Always interview first with the provider-native human-input tool. Use human input; in Copilot CLI this is the session ask_user tool and --no-ask-user disables it. Never assume project type, language, scope, or target platform.
2. Detect existing agent footprint on entry. If any of AGENTS.md, CLAUDE.md, GEMINI.md, opencode.json, .github/agents/, .claude/agents/, .opencode/agents/, .codex/agents/, .gemini/agents/, ~/.codex/AGENTS.md exists, present mode choice with improve and replicate as first-class options — never silently jump to update.
3. Orchestrator + subagent topology is mandatory. Subagent count (3 to ~50) is decided dynamically from scope.
4. Directory Architecture is generated and enforced. Every subagent file references it; the orchestrator routes by ownership.
5. Per-item opt-in recommendations. Plugin / skill / MCP candidates are always presented with rationale and explicit ask_user choice — never bulk-applied silently.
6. MCP config approval gate. Before writing any MCP config (.mcp.json, opencode.json › mcp, agent mcp-servers: / mcp_servers:, extension/plugin MCP manifests), render the proposal and call ask_user for approval. No silent MCP writes — ever. Replication re-triggers this gate per new target.
7. Marketplace-first lookup with vendor attribution. Recommendations come from registries listed in marketplaces, tagged [Tier · Vendor] — never invent names or URLs.
8. Replication goes through Canonical IR, not pairwise mappings. See replication. Never write a Copilot→Claude (or any other direction) function; always parse → IR → emit.
9. Non-destructive updates. cp <file> <file>.bak before any edit; merge into managed blocks, preserve user-authored content.
10. Multi-platform aware. Emit per-platform paths and frontmatter per platforms. Never write Copilot frontmatter into a Claude file.
11. Cross-OS aware. Detect host OS once (Linux / macOS / Windows-bash / Windows-pwsh) per cross-platform. Pick .sh for POSIX shells, .ps1 for native PowerShell. Forward slashes in generated docs. Never symlink on Windows. Bundle .gitattributes so line endings stay correct on every clone.
12. Git is optional and gated by ask_user.
13. Parallelism is mandatory where work is independent. The generator computes parallel-safety from the Directory Architecture and emits a wave table; the orchestrator prompt always contains a fan-out clause. For Claude Code, also emit AGENT-TEAMS.md per parallelism. Sequential-only topologies are an error.
14. If the project domain is software-development, recommend GitHub Spec-Kit. After domain detection (Phase 1.7), if the brief matches a software-dev keyword set, present spec-kit as an opt-in companion via ask_user, never auto-install. See spec-kit.
15. Security, audit, architecture, and design-pattern governance are mandatory. Every plan and generated AGENTS.md must include the baseline from security-audit-architecture: Security & Audit Matrix, Threat Model, Architecture / Design Pattern Matrix, ADR plan, and Quality Gates. Small projects may merge roles, but not omit the concerns.
16. Security-sensitive writes require evidence. MCP config, secrets-adjacent paths, CI/release config, and generated scripts must have an owner, approval state, and verification evidence in the output contract. No broad write permissions without rationale.
17. Improve mode is evidence-based. Existing systems are scored for security boundaries, secrets, audit evidence, architecture ownership, design-pattern consistency, and supply-chain source trust before any delta is applied.
18. Context budget is a feature. Default to the Balanced output profile from context optimization: keep routing and gates inline, move deep detail behind explicit references, and never duplicate long policy prose in every agent.
19. Ask whether agent artifacts are git-tracked or local-only. Before writing project-scoped agent files, ask the tracking question from local tracking. For local-only project files, write .git/info/exclude (never .gitignore) and verify with git check-ignore.
20. Plan handoff is normalized before emission. Treat VS Code plan prompt output, Spec-Kit /plan, and user-written plans as upstream planning input only. Convert them to the handoff contract / HandoffIR, then emit each selected runtime's native format. Never copy prompt frontmatter or another runtime's agent schema into generated artifacts.
21. Runtime drift is source-backed and gated. Use runtime updates before changing platform support. Gemini CLI is supported for local project subagents; remote A2A/extension packaging surfaces remain explicit import/package work.
22. Model overrides are optional and source-backed. Keep model: blank by default. Only when the user opts in during interview Q9b, load models for the runtime's accepted format, defaults, and rate-limit sources. Never pin live RPM/TPM numbers in generated files.
23. Task assignments use the canonical contract. Compose every orchestrator → subagent handoff with the Task Assignment Contract. Always fill the Required Minimum; add Expansion Blocks per the Recommended Packet Form. Subagents run the Acceptance Checklist before doing work and emit results via the Reporting Template; missing required fields trigger one consolidated question_request: to the orchestrator.
24. Learning memory is approval-safe and native-aware. When enabled, generated agents run the Learning Check before final response. none is valid. Subagents propose learnings; only the orchestrator or memory owner writes plugin-managed memory, and overwrite requires orchestrator approval. Native provider memory is complementary and used only where documented; never emit unsupported memory fields such as Codex agent TOML memory.
25. Human-input schemas are provider-specific. Never add ask_user to Copilot custom-agent tools: profiles. Claude agents that need to ask include AskUserQuestion; OpenCode uses nested permission: { question: allow }; Codex uses request_user_input only in Plan mode and falls back to question_request; Gemini may allow ask_user. Subagents return question_request when they cannot ask directly.
26. Run self-update preflight before setup. Phase -1 uses self-update preflight at ${AGENTS_SYSTEM_SETUP_HOME:-$HOME/github/agents-system-setup}. Fast-forward only clean Git checkouts; ask or emit question_request on dirty, missing, divergent, or install-manager ambiguity. Never update MCP/plugin config silently.
27. Requirements triage is default-on recommended. Add requirements-triage before planner for normal, ambiguous, cross-runtime, security-sensitive, release, MCP, replication, or multi-wave setups. For tiny direct setups, merge the role into planner and record why. Triage is read-mostly, uses question_request, and never owns final decisions or approval gates.
28. Content quality is universal. Apply content quality to all generated agents, skills, memory files, recommendations, and output contracts. Generate agent-quality-curator as a separate read-only role for normal/complex setups, merge into reviewer for tiny setups, and report Content quality: ok|warn|fail|n/a.
29. Main-to-subagent handoff is structured. Use the handoff contract and prompt guidelines to compose provider-native Task Assignments. Recommended-only for safe tiny work; full-form for normal, risky, multi-file, fan-out, MCP, release, replication, security, architecture, or generated-agent-system work. Pass a subtask slice, not full project memory.
30. Dedicated security teams are explicit. Generate the security team topology only when the user selects Security team / Bug hunting, asks for bug hunting/security analysis/disclosure triage, or the risk intake justifies it. Security discovery, validation, attack-path, triage, and compliance roles are read-mostly by default; remediation writes, external scanning, exploit execution, credential use, production testing, disclosure outreach, MCP/tool config, and destructive tests require explicit approval and owning-agent routing.
31. Operational state directory is artifact-free. .agents-system-setup/ holds operational state only (replication ledger, MCP approval evidence, learning ledger, migration.jsonl, .bak files). Never write agents/, skills/, hooks/, commands/, prompts/, or plugins/ subtrees inside it; runtimes do not load them and existing misroutes go through misplaced-artifacts-migration.
32. Capture user purpose before deep recon. Phase 0 sub-step 0 asks the headline purpose first; Phase 1 recon then scores and highlights signals against that intent (never filters). Allow an explicit "I'm exploring — let recon lead" sentinel that defers the purpose ask until after the card. See cwd-reconnaissance.
33. The orchestrator is the host CLI session, not a subagent file. Never emit orchestrator.agent.md, .claude/agents/orchestrator.md, .opencode/agents/orchestrator.md, .codex/agents/orchestrator.toml, or .gemini/agents/orchestrator.md. The Orchestration Operating Model lives in AGENTS.md and is read by the host CLI session of any selected runtime. @orchestrator remains a routing role alias for that host session — it is never an emitted agent artifact. OpenCode's permission.task gate moves to opencode.json (host root agent) since no orchestrator file is emitted.

Procedure

Phase -1 — Self-Update Preflight

Before footprint detection, run the safe preflight from self-update-preflight:

1. Locate ${AGENTS_SYSTEM_SETUP_HOME:-$HOME/github/agents-system-setup}.
2. If it is a clean Git checkout with an upstream, git fetch and git merge --ff-only when only behind.
3. If the checkout is missing, dirty, ahead, divergent, lacks upstream, or the install owner is ambiguous, ask with the provider-native human-input tool from human input. If interaction is disabled, emit question_request and continue with the installed version.
4. Do not edit MCP config, plugin config, runtime settings, generated agents, or version/release files during this phase.

Record update_preflight_status, source path/manager, and evidence for Phase 2 and the final output contract.

Phase 0 — Capture Purpose, Detect Footprint, Choose Mode

Sub-step 0 — Capture headline purpose first. Before any directory scan or mode choice, ask the user's intent with the provider-native human-input tool:

"In one sentence, what are you trying to achieve with an agent system here?" Freeform; offer "I'm exploring — let recon lead" as a labeled choice.

Persist headline_purpose: string | "exploring". This drives Phase 1 purpose-aware recon scoring — see cwd-reconnaissance. When exploring, defer the purpose ask until after the recon card.

Sub-step 1 — Detect footprint. Inspect cwd for project and agent artifacts per Phase 1 step 1; do not run deep recon yet.

Sub-step 2 — Show profile card and ask mode. Display the captured headline_purpose, detected project type, existing agent artifacts by runtime, recommended mode, and inferred current runtime(s):

"I detected <footprint>. How should I proceed?" Choices: ["Improve current setup (Recommended when artifacts exist)", "Init new setup", "Replicate / sync to another runtime", "Update managed blocks", "Cancel"]

Persist the selected mode. Do not ask target runtimes before this mode choice. After mode is known:

• init / update: ask which runtime(s) to generate unless the user's request already names them.
• improve: default scope to detected runtime(s); ask a target runtime only if updating one runtime or expanding audit scope requires it.
• replicate / sync: defer source and target runtime questions to Phase 1.5, and ask targets only for the requested expansion/sync.

All later phases loop over the selected or detected runtime scope using platforms.md as the source of truth for paths and frontmatter.

Gemini CLI emits local subagents at .gemini/agents/*.md. See platforms and agent format for its non-recursive subagent and mcp_servers: rules.

Phase 1 — Footprint Details & Interview Continuation

1. Inspect cwd and detect runtime footprint:

   • Project files: package.json, *.csproj, Package.swift, build.gradle, pyproject.toml, go.mod, Cargo.toml, mkdocs.yml, .git/.
   • Agent artifacts (per runtime):
     • Copilot CLI: AGENTS.md, .github/agents/*.agent.md, .github/agents/*.md (docs-drift import signal), .github/skills/, .mcp.json
     • Claude Code: CLAUDE.md, .claude/agents/, .claude/skills/, .claude/settings.json
     • OpenCode: opencode.json, .opencode/agents/, .opencode/skills/
     • OpenAI Codex: AGENTS.md (orchestrator + project rules), .codex/agents/*.toml (specialized subagents), .codex/config.toml, ~/.codex/AGENTS.md, ~/.codex/agents/; CLI-only plugin/command UX stays documented separately
     • Gemini CLI: GEMINI.md, .gemini/agents/*.md, .gemini/settings.json, ~/.gemini/GEMINI.md, ~/.gemini/agents/
   • Project recon: run the safe-readonly cwd reconnaissance from cwd-reconnaissance using the Phase 0 headline_purpose for scoring: signals are sorted high → med → low → n-a by purpose_relevance but never filtered. When headline_purpose == "exploring", render in default order and re-ask the purpose question after card confirmation. Render the Reconnaissance Card and ask_user to accept/correct/skip. Privacy guardrails (no data file reads, magic-byte detection, secret redaction) are mandatory.
   • Misplaced artifacts: scan for .agents-system-setup/{agents,skills,hooks,commands,prompts,plugins}/ and queue every match for the per-artifact prompt in misplaced-artifacts-migration.

2. Confirm the Phase 0 mode — do not re-ask target runtimes before the mode choice. Use this table only to pick the recommended mode/default choices shown in the Phase 0 profile card, or to re-prompt if the initial detection was ambiguous:

   Detected footprint	Default offer	Choices
   Nothing	init	["Init (Recommended)", "Cancel"]
   One runtime, looks healthy	improve	["Improve current setup (Recommended)", "Update (regenerate managed blocks)", "Replicate to another runtime", "Init alongside (additive)"]
   One runtime, gaps	update	["Update (Recommended)", "Improve (audit + targeted fixes)", "Replicate to another runtime"]
   Two+ runtimes	improve	["Improve current setup (Recommended)", "Replicate / sync between runtimes", "Update one runtime"]

3. Continue the interview — see interview script. One question per ask_user call. Skip questions already answered by detection (project type, framework). After the Phase 0 mode choice, offer to use detected/safe defaults for non-gated setup questions. Never skip artifact tracking, MCP approval, plan approval, or security-sensitive write gates. For init/update, ask target runtimes only after mode if needed. For improve/replicate, jump straight to Phase 1.5; runtime expansion questions happen there only if required.

Phase 1.5 — Improve / Replicate branch

If the user picked improve → run the improve procedure (audit → score → propose deltas → opt-in apply). Misplaced artifacts detected in Phase 1 are first-class deltas in this audit; surface them through misplaced-artifacts-migration before any Phase 5 write. Skip Phases 2–4; jump to Phase 5 mechanics for backups + write.

If the user picked replicate → run the replication procedure:

1. ask_user for source runtime (single-select among detected).
2. ask_user for target runtimes (multi-select; source excluded).
3. Parse source → AgentIR / SkillIR / MCPServerIR records.
4. Render lossiness report; ask_user to approve dropped fields per target.
5. Run Phase 1.6 before any target write.
6. Re-run Phase 3.5 MCP approval gate against each new target.
7. Emit per target with <!-- agents-system-setup:replicated-from: <source> --> markers.
8. Write replication ledger to .agents-system-setup/replication.jsonl (one JSON object per line — never .md, never inside any agents/ directory, or it will be misread as a malformed agent).
9. Verify round-trip (re-parse emitted → diff IR → surface drift).

For improve, run Phase 1.6 before applying any selected delta. For both branches, finish with Phase 7 (verify & summarize).

Phase 1.6 — Artifact Scope & Tracking

Run before Phase 1.7 for init/update, and before Phase 5 writes for improve/replicate. Use local tracking.

Ask:

"Should the generated agent system be shared through git or kept local to this checkout?" Choices: ["Project files, git-tracked (Recommended for teams)", "Project files, local-only / untracked (Recommended for personal setup)", "Personal/global outside this repo"]

Record artifact_tracking as project-tracked | project-local | personal-global.

Rules:

• project-tracked: use project paths; do not commit unless Phase 6 git actions are explicitly approved.
• project-local: use project paths, then add only generated/modified artifact paths to .git/info/exclude if .git/ exists. Do not modify .gitignore for this.
• personal-global: use runtime user paths and avoid repo writes unless separately approved.

Phase 1.7 — Domain Detection & Spec-Kit Recommendation

Run after Phase 1 (and 1.5 if branched), before Phase 2. Inspect the project brief gathered during interview against this software-development keyword set:

app, application, api, service, microservice, library, sdk, cli, tool, devtool, backend, frontend, fullstack, web, mobile, ios, android, desktop, framework, plugin, extension, package, module, infrastructure, infra, terraform, pulumi, kubernetes, helm, compiler, parser, runtime, database, orm.

If any keyword matches (case-insensitive, word-boundary), or the project already has source-language signals (package.json, pyproject.toml, go.mod, Cargo.toml, *.csproj, pom.xml, Package.swift, build.gradle, mix.exs, composer.json), classify as software-dev. Otherwise non-dev (marketing, research, content, data-analysis).

If software-dev, call ask_user:

"This looks like a software project. Would you like to install GitHub Spec-Kit (Spec-Driven Development: /specify → /plan → /tasks → /implement slash commands) alongside the agent system?" Choices: ["Yes — install for this runtime (Recommended)", "Just print the install command", "No, skip"]

On approval, emit the runtime-matched command from spec-kit (uv tool install specify-cli --from git+https://github.com/github/spec-kit.git then specify init --here --ai <copilot|claude|codex|opencode>). Print, never silently shell-out unless the user picked "install".

Record the choice in the plan so Phase 4 orchestrator output can reference the /specify workflow when appropriate.

Phase 1.8 — Security, Audit, Architecture Intake

Run after domain detection and before Phase 2. Use security-audit-architecture as the source of truth.

Ask only questions not already answered by detection. Data sensitivity, auth boundary, and external tools/MCP usage are mandatory. Infer audit evidence, architecture style, critical qualities, and anti-pattern defaults into the plan for low-risk projects unless the user asks to configure them explicitly.

1. Data sensitivity.
2. Auth boundary.
3. External tools / MCP usage.
4. Audit evidence expectations.
5. Deployment / release risk.
6. Architecture style.
7. Critical quality attributes.
8. Known design anti-patterns to avoid.

Record the answers in the plan. If the user is unsure, choose safe defaults: least privilege, no silent MCP writes, no secrets in code, architecture decisions documented in AGENTS.md, and dedicated security/architecture ownership when the project handles sensitive data or external tools.

Phase 1.8a — Security Team Scope

Run only for dedicated security team / bug-hunting setups; use security team. Record security_team_depth, security_team_scope, authorization_scope, selected roles, and source/vendor/license-attributed plugin candidates. Safe defaults: owned repo only, no external scanning/exploit execution/credential use/production testing/disclosure outreach/remediation writes without explicit approval; missing authorization returns question_request.

Phase 1.9 — Output Profile & Context Budget + Advanced Agent Behavior

Run after Phase 1.8 and before Phase 2. Run the grouped interview Q9b Advanced agent behavior block explicitly; do not leave model or tool choices as prose-only plan notes. Group agent-behavior choices together so the user compares tradeoffs once: optional model overrides, Copilot CLI tool profile when Copilot is selected, output profile, and Memory & Learning profile. This phase owns those prompts: ask each advanced behavior choice exactly once and do not re-ask output profile or memory profile in Phase 1.10. Use context optimization.

Ask and record the Q9b choices before Phase 2:

1. Per-agent model override policy — keep runtime defaults unless the user opts in. Ask for override policy by scope (all agents | by role | exceptions only) and avoid looping over every agent by default.
2. Copilot CLI Tool Profile — only when Copilot CLI is selected; persist copilot_tools_profile.
3. Output profile / context budget — Balanced | Compact | Full.
4. Memory & Learning profile — persist learning_memory_profile, learning_gate_strength, overwrite policy, and whether native provider memory is only documented or explicitly enabled.

For Copilot CLI tools, keep prompt choices concise: Standard least-privilege by role (recommended), Read-only everywhere, Inherit parent tools, or Custom after generation. Render the full mapping in the plan/reference, not in the question.

For the output profile choice, ask once:

"How much detail should generated agent files include?" Choices: ["Balanced (Recommended)", "Compact", "Full"]

Record:

• output_profile: balanced | compact | full
• inline_sections: which sections stay in AGENTS.md
• overflow_targets: where long details should be written or proposed (for example docs/agents/security-audit.md)
• context_budget_notes: any user constraints on verbosity

If the user is unsure, choose Balanced. This keeps all routing, ownership, governance, and quality gates inline while moving long rationale and overflow candidate lists to references.

Phase 1.10 — Memory & Learning Profile

Do not call ask_user here. Use the Memory & Learning answer already collected in the Phase 1.9/Q9b advanced-agent-behavior group. This phase normalizes the recorded choice for planning and rendering. Use learning memory.

Record:

• learning_memory_profile: project-tracked | project-local | personal-global | disabled
• native_learning_surface: runtime-native memory selected or document-only | disabled
• learning_memory_owner: @memory-steward when the roster includes one, otherwise @orchestrator
• learning_memory_path: path chosen from learning memory
• learning_gate_strength: recommended by default; do not make it blocking unless the user explicitly asks
• learning_update_policy: overwrite requires orchestrator approval

Do not ask a separate blocking Learning Check question by default. Native memory setup follows learning memory: Copilot Memory is public-preview, transparent server-side durable repo memory, Claude has memory: user|project|local, OpenCode relies on AGENTS/skills/compaction/plugin patterns, Codex memories require [features] memories = true, and Gemini has save_memory, GEMINI.md, /memory, and experimental autoMemory. Ask optional hook/script support only when the runtime has a supported hook surface and this setup has not already handled learning. Render the exact hook/config proposal and ask before writing it.

Phase 1.11 — Requirements Triage

Before Phase 2 planning, decide requirements_triage_status:

• separate — generate requirements-triage as its own read-mostly subagent.
• merged — merge triage into planner for tiny direct setups.
• skipped — only when the task is direct, low-risk, single-runtime, and already has clear scope.

Default to separate for ambiguous, multi-step, cross-runtime, security-sensitive, release, MCP, replication, audit, improve, or multi-wave setups. The triage role returns an intake brief with intent summary, task type, in/out scope, ambiguities, question_request items, risk classification, recommended routing/waves, acceptance criteria, quality gates, and Learning Check. The orchestrator owns the final plan, all user-facing questions, and every approval gate.

Phase 1.12 — Content Quality Review

Before Phase 2 planning, decide content_quality_curator:

• separate — generate agent-quality-curator as its own read-only subagent.
• merged — merge content-quality review into reviewer for tiny direct setups.
• skipped — only when no generated agent, skill, memory, recommendation, or output-contract prose is changed.

Default to separate for normal, complex, cross-runtime, audit, improve, replication, MCP, release, skill-heavy, or multi-wave setups. Use content quality for signals, status levels, and boundaries. The curator reports Content quality: ok|warn|fail|n/a; signals=<list|none> and never owns broad write, MCP config, runtime config, release metadata, or final approval gates.

Phase 2 — Plan (Directory Architecture, Roster, Matrix, Waves)

Build the plan and show it before writing anything. The plan must include:

• Directory Architecture — table of path glob | purpose | owner agent | edit rule. Derived from project type + frameworks. Always covers: source dirs, tests, docs, infra, agent files, generated artifacts.
• Agent Roster — table of name | role | owns | triggers | model (optional) | parallel-safe | wave. Use topology guide. Compute parallel-safety per parallelism: a subagent is parallel-safe iff its owns glob doesn't overlap any other's, it doesn't write outside owns, and it doesn't depend on another subagent's output in the same wave.
• Capability Matrix — capabilities × agents grid (✅ / 🟡).
• Wave plan — grouped list Wave N → [parallel-safe subagents]; the orchestrator fans out per wave and awaits each before the next.
• Requirements triage — status (separate | merged | skipped), intake brief, ambiguities, question_request count, risk flags, and recommended first-wave routing.
• Content quality — curator status (separate | merged | skipped), review scope, expected signals, and output marker from content quality.
• Security team operating model — for dedicated|expanded, include roles, authorization scope, evidence contract, read-mostly defaults, and gates from security team.
• Plan Handoff Contract — accepted planning sources, HandoffIR fields, per-platform format targets, approval boundaries, and verification evidence. Use handoff.
• Prompt assignment quality — recommended handoff strictness, Orchestrator Assignment Format, Context Packet strategy, allowed capabilities, skills referenced, and expected Task assignment quality marker from prompt guidelines.
• Self-update preflight — status, source path or provider manager, fast-forward evidence, and any question_request from self-update preflight.
• Human Input protocol — selected runtime matrix, native question tool or fallback, allowlist/config syntax, and unresolved question_request records from human input.
• Skills to create.
• Plugin/MCP candidates per capability (Phase 3 fills this).
• Per-platform file plan (Copilot/Claude/OpenCode/Codex/Gemini paths the user will actually get).
• Artifact tracking — project-tracked | project-local | personal-global, plus exclude plan for local-only mode.
• Memory & Learning plan — native-vs-plugin-managed memory choice, storage profile, memory owner, curated memory path, operational ledger path (if any), Learning Check strength, overwrite approval policy, and Directory Architecture rows for memory paths.
• Git actions (if any).
• Output profile & context budget — balanced|compact|full, sections kept inline, overflow targets, and biggest expected agent-memory file.
• Security & Audit Matrix — controls, owner agents, affected paths, evidence required, and source reference.
• Threat Model Summary — assets, trust boundaries, threats, mitigations, owners, and status.
• Architecture & Design Pattern Matrix — selected patterns, alternatives, rationale, risks/guardrails, and ADR refs.
• ADR plan — decisions that should become docs if the user approves docs writes.
• Quality Gates — build/test/lint/security/supply-chain/architecture evidence required before "done".

End the phase with ask_user: ["Proceed", "Edit plan first"].

Phase 3 — Marketplace Lookup with per-item Opt-in

For every capability the user named (e.g., "playwright", "azure", "postgres"):

1. Search the marketplaces in tier order — see marketplaces. Tier 1 first; only fall through if it misses.
2. Collect at most 3 candidates per capability. For each, populate mandatory rationale fields: name, source_tier, repo_url, bundles (agents/skills/hooks/MCP/LSP), why_recommended, tradeoffs, install_command_per_platform. Empty rationale ⇒ drop the candidate.
3. Render a comparison table to the user, then call ask_user:

   "For capability , which would you like?" Choices: ["<candidate 1 — short label>", "<candidate 2>", "<candidate 3>", "Show more (Tier-3 fallback search)", "None — skip this capability"]

4. Show more triggers Tier-3 search (capped at +5 additional candidates). Re-render table and re-prompt.
5. Record the user's pick. Skipped capabilities never reach the MCP gate or final write.

See plugin discovery for the comparison-table format and rationale schema.

For security-team setups, security plugins or skills remain optional candidates. Show vendor/license attribution and tradeoffs. Never clone proprietary plugin workflow text into generated agents, and never auto-install scanners, MCP servers, or disclosure tooling.

Phase 3.5 — MCP Config Approval Gate (mandatory, downstream of Phase 3)

If any user-selected candidate from Phase 3 includes an MCP server:

1. Build the proposed config per platform:
   • Copilot CLI → .mcp.json (mcpServers key) and any approved agent-frontmatter mcp-servers:
   • Claude Code → .mcp.json (mcpServers key) and any approved project/user-agent mcpServers
   • OpenCode → merge into opencode.json (mcp key)
   • OpenAI Codex → .mcp.json plus any approved per-agent TOML [mcp_servers.<id>]
   • Gemini CLI → approved per-agent mcp_servers: blocks in .gemini/agents/*.md
2. Render each proposed file/config block verbatim (full JSON/YAML/TOML as applicable).
3. For central MCP config files (.mcp.json and opencode.json with MCP blocks), include concrete approval evidence with server names:
   • Prefer a top-level x-agents-system-setup object when the runtime schema safely tolerates extension keys. Include mcp_approval.decision, mcp_approval.servers, approved_by or approval_ref, and evidence.
   • If extension keys are not schema-safe, write a sibling sidecar named <config>.agents-system-setup.approval.json with the same metadata.
4. ask_user:

   "I'm about to write the MCP configuration above to <paths>. Approve?" Choices: ["Approve all (Recommended)", "Approve selectively (per-server)", "Skip MCP entirely"]

5. If selective, loop per server: ["Include", "Skip"].
6. If skip, strip every mcp-servers: / mcpServers / mcp_servers: / TOML [mcp_servers.*] surface from generated agents and do not write .mcp.json / opencode.json mcp / extension MCP config.
7. No MCP write may occur before this gate returns approval.

Phase 4 — Generate Artifacts (per platform, post-approval)

For each selected platform, look up paths and frontmatter in platforms.md, then render:

• AGENTS.md at repo root → template. Fill Read First, Context Loading Policy, Directory Architecture, Agent Roster, Capability Matrix, Plan Handoff Contract, Security & Audit Matrix, Threat Model, Architecture / Design Pattern Decisions, ADR Index, Quality Gates, Skills, Plugins/MCP tables. Use the selected output profile from Phase 1.9; summarize long sections and link overflow details instead of dumping exhaustive prose inline.
• GEMINI.md when Gemini CLI is selected → template. Keep it a compact pointer/sync copy that tells Gemini to load canonical AGENTS.md, preserves artifact tracking notes, and routes root-session fan-out because Gemini subagents cannot recursively delegate.
• Orchestrator — never emit as a subagent file (subagent files are for specialized roles only). The orchestrator role lives in AGENTS.md › Orchestration Operating Model (Role, Hard Rules, Context Load Order, Lifecycle, Orchestrator Assignment Format, Wave Execution, Memory & Learning, Subagent Routing, Out of Scope) and is read by the host CLI session of any selected runtime — Copilot CLI, Claude Code, OpenCode, OpenAI Codex (CLI + App), and Gemini CLI. @orchestrator is a routing alias for that host session. OpenCode's permission.task subagent-gating moves to opencode.json › agent.<root>.permission.task (or equivalent host config) since no orchestrator markdown is emitted; see platforms and agent-format. Improve mode detects existing orchestrator subagent files and offers deletion/deprecation/manual-review choices via misplaced-artifacts-migration.
• Each subagent — use the platform-specific template and fill {{OWNED_PATHS}} / {{READONLY_PATHS}} from the Directory Architecture:
  • Copilot CLI → subagent.agent.md.template at .github/agents/<name>.agent.md. Frontmatter: name, description, tools: list filled from the Standard Tool Profile per role (orchestrator + edit-capable subagents → [vscode, execute, read, agent, edit, search, todo]; reviewers/auditors → [read, search]; testers/release helpers → [execute, read, search, todo]; research/docs → [read, search, web, todo]; or omit when the user picked inherit), optional mcp-servers: (hyphenated key). .github/agents/<name>.md is recognized only as an upstream docs-drift/import signal, not the default emitter.
  • Claude Code → subagent.claude.md.template at .claude/agents/<name>.md. Frontmatter: name, description, optional tools: as comma-separated string (e.g. Read, Grep, Bash), optional disallowedTools:, permissionMode:, model:, etc. Do not use Copilot tool names or mcp-servers:.
  • OpenCode → subagent.opencode.md.template at .opencode/agents/<name>.md. Frontmatter: no name: (filename = agent name), description, mode: subagent, optional model: in provider/model-id format, optional permission: block. Do not embed mcp-servers: — MCP belongs in opencode.json.
  • OpenAI Codex (CLI + App) → subagent.codex.toml.template at .codex/agents/<kebab-name>.toml. Required fields: name, description, developer_instructions (TOML triple-quoted string). Carry the IR's tool_allowlist only if explicitly set (otherwise inherit from parent session). Map IR model → model and reasoning hints → model_reasoning_effort (low|medium|high). Set sandbox_mode = "read-only" for read-only subagents. Per-agent MCP servers go under [mcp_servers.<id>] in the same file. AGENTS.md keeps only the orchestrator section + Directory Architecture / Capability Matrix / Waves. See Codex layout and openai docs. CLI-only instructions such as /agent are usage notes, not requirements for App compatibility. Also emit/upsert .codex/config.toml with [agents] max_threads = 6 and max_depth = 1 unless the user s

…(truncated)