setup-agents

/setup-agents

Scaffold a complete multi-agent Claude Code development system for the current project.

This skill runs an 8-step configuration dialogue, then delegates generation to the system-architect agent. Nothing is written until you confirm in Step 8.

Modes

• Fresh install (default): no .claude/ directory in the project. Runs all 8 steps.
• --upgrade: an existing .claude/ directory was generated by an earlier Forgeline version. Preserves the developer's choices and only adds, refreshes, or proposes changes for files that the current Forgeline knows how to improve.

If the developer passes --upgrade (or the skill detects an existing .claude/ and the developer confirms upgrade), follow the Upgrade Mode flow at the end of this file instead of the standard 8 steps.

---

Step 1 — Read the Project

Search the current directory for project files in this order:

Primary (preferred):

• vision.md
• tech-stack.md

Fallback (if primary not found):

• README.md
• package.json, pnpm-lock.yaml, package-lock.json
• Cargo.toml
• pyproject.toml, requirements.txt
• go.mod
• Gemfile
• Root-level *.config.ts, *.config.js

Extract: project name, type, primary languages, frameworks, database/storage, AI/ML components, testing frameworks, CI/CD setup, package manager, team size (if mentioned).

Present a confirmation summary and wait for the user to confirm or correct before proceeding.

---

Step 2 — Development Approach

Based on the project context from Step 1, suggest a development approach. Present all 5 options with a recommended pick:

Signal	Suggested approach
Solo developer, small project	Iterative + Timeboxing
Team project, existing CI/CD	Trunk-Based
Product with deadlines	Shape Up
Greenfield, unclear scope	Iterative + Timeboxing
Library/OSS	TDD-First

Available approaches:

1. Iterative + Timeboxing — Ship working increments every 1-3 days. Each cycle has a tangible deliverable.
2. Shape Up — 6-week build cycles, 2-week cooldown. Appetites, not estimates.
3. TDD-First — Tests before implementation. Coverage is the primary quality signal.
4. Trunk-Based — Single main branch, short-lived branches, feature flags.
5. YAGNI/KISS — Build the minimum. Refactor only on second similar case.
6. Custom — Describe your own methodology in free text.

The developer may select 1 to 3 approaches. When selecting multiple approaches, the first selected is the primary — it sets the overall cadence and phase structure. Additional approaches layer their rules on top.

Conflict matrix — incompatible pairs:

Pair	Reason
Iterative + Shape Up	Cycle cadence conflict: 1-3 days vs 6 weeks

If the developer selects an incompatible pair, warn them and ask to drop one or confirm they understand the conflict. Do not block — the developer has final say.

Custom approach handling: If the developer selects "Custom", ask them to describe their methodology in free text. Delegate the description to the system-architect agent, which will extract structured approach content (philosophy, rules, phase structure) matching the format of the 5 standard approaches. Present the extracted content for developer approval before proceeding. The custom approach is stored under ## Custom in docs/approaches-reference.md.

Save the selection as {{approach}} (primary) and {{secondaryApproaches}} (array, may be empty) in the confirmed configuration. Custom approach uses "Custom" as the name. Both generate "Development Approach" sections in the project's CLAUDE.md — the primary first, then secondary approaches under a "Secondary Approaches" subheading.

If the developer wants to skip approach selection, proceed without it — the approach section will not be generated. The approach can be changed later at any time using /setup-approach without re-running the full setup.

---

Step 3 — Agents

Based on the detected stack, propose specialized agents. Rules:

• opus for safety-critical domains: backend logic, database, AI/ML pipelines, infrastructure, security
• sonnet for high-iteration domains: frontend/UI, testing, CI/CD, documentation
• Assign a color to each agent using semantic conventions: blue/cyan for analysis/review, green for success-oriented, yellow for caution/validation, red for critical/security, magenta for creative/generation
• Each agent must have a clearly defined domain and explicit forbidden zones
• Always include a testing agent
• A dispatch agent is always generated automatically for the orchestration pipeline — do not include it in the proposals
• A reviewer agent is always generated automatically (default-on, fresh-context post-task review for /execute). The developer may opt out, but the default is to keep it. Do not include it in the proposals — show it as a separate confirmation question after the implementer agents are confirmed.
• Minimum 2 agents, maximum 8

Orchestration topology (default: supervisor). Before finalizing the agent roster, ask:

How should agents coordinate?

• Supervisor (recommended default): a dispatch agent owns assignment. One place to inspect, +1 hop latency per task, easy to debug. Works well for coupled features (frontend + backend, refactors, anything that crosses domains).
• Swarm: agents pass work peer-to-peer using a handoff agent. Direct calls, no central hop, but distributed handoff logs and risk of loops/deadlocks. Works well only when implementer agents own truly disjoint domains and the task is decomposable along those boundaries.

If the developer picks swarm, generate templates/agents/handoff.md.hbs instead of templates/agents/dispatch.md.hbs. Also show this warning before final confirmation:

Swarm mode is harder to debug, adds loop/deadlock risk, and tends to perform worse for tightly-coupled work. The audit research (Cognition, Anthropic) explicitly recommends supervisor for coding-style features. Pick swarm only if you understand the trade-off.

Save the choice as {{topology}} in the confirmed configuration. Default is "supervisor".

Single-writer rule (default): every implementer agent must own a distinct domain. If the proposed roster has two implementer agents whose owns lists overlap (e.g. two backend agents that both write API code), show a clear warning to the developer:

Two implementer agents are proposed for overlapping files. Parallel writers cause implicit, conflicting decisions about style and edge cases. Recommended fixes:

• Split the domain (e.g. api-routes vs domain-services) so each has a clean owns list, or
• Demote one agent to review-only (move source out of its owns, into its forbidden list, and add it as a reviewer in /assign).

The warning is advisory, not a block — the developer may override. Reviewer-only and research-only agents are always allowed in any number; the rule applies only to implementers.

Security Agents (opt-in, domain-scoped)

After proposing core domain agents, present a security agent menu. Security agents are scoped per layer — never a single "security" agent for the whole project. Propose only the ones that map to the detected stack:

Candidate	Trigger signals	Model	Color	Primary concerns (review-only)
security-frontend	React, Vue, Svelte, Angular, Next.js, Nuxt, Astro, SvelteKit, any browser-facing UI	sonnet	red	XSS, CSP, clickjacking, CSRF, SRI, client-side auth/session storage, unsafe raw-HTML sinks, open redirects, third-party script supply chain
security-backend	Node/Express/Fastify, NestJS, FastAPI, Django, Rails, Spring, Go HTTP, any server API	opus	red	Injection (SQL/NoSQL/command), input validation, authN/authZ boundaries, rate limiting, SSRF, deserialization, sensitive-data logging, hardcoded secrets, JWT/cookie handling
security-database	Prisma, Drizzle, TypeORM, SQLAlchemy, Alembic, ActiveRecord, raw SQL migrations, PostgreSQL/MySQL/Mongo	opus	red	Parameterized queries, migration safety (non-null, defaults, indexes), least-privilege DB users, PII/encryption-at-rest, row-level security, backup/restore plan, destructive migration guards
security-infra	Terraform, Pulumi, AWS CDK, Docker/Compose, Kubernetes, CI/CD configs, env/secret stores	opus	red	IaC secrets, IAM least privilege, network policies, TLS/mTLS, container hardening, supply chain (pinned images, signed commits), CI secrets, public-access defaults

Menu behavior:

1. Present each candidate security agent as an opt-in checkbox, not a default. Default: unchecked.
2. The developer may select zero, one, or several — they can all coexist.
3. If a domain-specific stack is not detected (e.g., no DB in the project), do not show that security agent at all.
4. A security agent's scope is review, research, and advisory only — it never owns source code. Its owns list must be limited to security-oriented artifacts (e.g., docs/security/, SECURITY.md, threat model files). Its forbidden list must include the source owned by the corresponding build agent.
5. Every security agent must use Context7 before emitting a finding: resolve-library-id → query-docs for the specific framework/version at hand, then cross-check against OWASP guidance. This is a hard requirement baked into its directives by system-architect.

Propose all applicable security agents together with the core agents in a single confirmation block. Wait for the user to add, remove, or rename before proceeding.

---

Step 4 — Skills

Always include the standard set. Add stack-specific skills when relevant tooling is detected.

Standard (always):

• /check — full quality pipeline (lint + typecheck + tests)
• /changelog — session changelog from git diff
• /phase — phase-level feature executor (backward-compat wrapper)
• /deploy-check — pre-deployment audit
• /plan — plan a feature: decompose into tasks with domain assignments
• /assign — assign agents and skills to a plan's tasks
• /execute — execute an approved dispatch plan task by task
• /docs — maintain documentation coverage: audit components, update docs, check status
• /setup-approach — change the development approach without re-running /setup-agents

Default-on (offered as opt-in checkbox, default checked):

• /observability — one-shot configuration of OpenTelemetry export from Claude Code to LangSmith, Langfuse, or any OTLP collector. Generates .env.example entries and docs/observability.md. The skill itself never enables telemetry on a per-session basis — the developer controls that via their local .env.

Stack-specific examples:

• /migrate — if Prisma, Drizzle, Alembic, or similar detected
• /e2e — if Playwright, Cypress, or Puppeteer detected
• /container — if Docker/docker-compose detected
• /infra — if Terraform, Pulumi, or CDK detected

Present the full list with checkboxes and wait for confirmation.

---

Step 5 — Plugins

Context7 is always enabled. Non-negotiable.

Delegate to the system-architect agent: pass it the detected tech stack from Steps 1–4 and ask it to use Context7 (resolve-library-id → query-docs) to verify current best practices and return plugin recommendations. Do not perform Context7 lookups directly from the skill — this is analysis work that belongs to the agent.

Once the agent returns its recommendations, present them to the user. Always include:

• context7 — mandatory for all projects

Default recommendations based on detected stack:

• typescript-lsp — if TypeScript detected
• rust-analyzer-lsp — if Cargo.toml detected
• github — if GitHub remote detected
• playwright — if Playwright in dependencies
• code-simplifier — always recommended

Present with checkboxes and wait for confirmation.

---

Step 6 — Hooks

Detect the primary linter/formatter:

• TypeScript → Biome or ESLint (check config files)
• Rust → Clippy (cargo clippy)
• Python → Ruff or Black
• Go → gofmt

Propose:

PostToolUse (after every file edit): run linter on $CLAUDE_FILE_PATH Stop (end of session): scan for hardcoded secrets and unsafe patterns

Present the proposed commands and wait for the user to modify or add custom hooks.

---

Step 7 — Permissions

Pre-fill based on detected package manager and tools. Always include:

Allow:

• Bash(git:*)
• Bash(gh pr:*)
• Bash(<package-manager>:*) — detected package manager
• Bash(make:*) — if Makefile detected

Deny (secrets protection — always):

• Read(.env)
• Read(.env.*)
• Read(secrets/**)
• Read(~/.ssh/**)
• Write(.env)
• Write(.env.*)

Ask if there are additional commands to allow (docker, terraform, aws, kubectl, etc.) and wait for response.

---

Step 8 — Final Confirmation

Present the complete system summary in a single block covering: selected approach, all agents (including dispatch and docs), all skills (including plan/assign/execute/docs), plugins, hooks, and permissions.

Include a brief description of the development workflow:

After generation, use /plan to start a feature, /assign to assign agents, and /execute to run the plan. All artifacts are saved in docs/plans/.

Ask:

Generate this system into the current repo? [yes / change]

• If yes: delegate to the system-architect agent with the full confirmed configuration (including approach if selected)
• If change: return to the relevant step

Do not write any files until this confirmation is received.

---

Upgrade Mode

Triggered when:

• The developer passes --upgrade, or
• The skill detects an existing .claude/agents/ and the developer confirms Upgrade existing setup instead of Reinstall from scratch.

The goal of upgrade mode is to close the version drift between Forgeline's current templates and what was generated by an older version, without losing the developer's customisations.

Step U1 — Snapshot the current state

Read the existing workspace:

• .claude/agents/*.md — list every agent
• .claude/skills/*/SKILL.md — list every skill
• CLAUDE.md — preserve every developer-edited section
• docs/agentic-system.md — extract the previously selected stack, approach, agents, skills, and (if present) topology
• docs/state/*.md — never modified by upgrade; just confirm they exist

Build the "current snapshot" object: { agents, skills, approach, topology, hasReviewer, hasObservability, hasEval, hasHandoff, ... }.

Step U2 — Build the upgrade plan

Diff the current snapshot against what the current system-architect would generate fresh. For each generated file, classify:

Class	Action
Missing (current version generates it, but it does not exist)	Add — show the developer what it is, then create on confirm
Refreshable (file exists but the template has changed in a way that is safe to re-render)	Refresh — show diff, ask per-file
Customised (file exists with edits the developer made — heuristic: any line not matching the template)	Skip by default, surface a ## Upgrade note inside the file listing what could be refreshed if the developer accepts the loss of customisation
Deprecated (Forgeline used to generate this, no longer does)	Leave it. Never delete files. Show a deprecation note.

Examples of typical upgrade plans (from one Sprint to the next):

• Sprint 1 → 2: missing reviewer.md, missing observability/SKILL.md, refreshable templates/agent.md.hbs to add OODA, refreshable execute/SKILL.md to add step 4h reviewer call
• Sprint 2 → 3: missing eval.md + eval/SKILL.md, refreshable plan/SKILL.md for security trigger detection, optional handoff.md if topology was set to swarm

Step U3 — Present the upgrade plan

Show the developer a table:

| File                                    | Class        | Action          |
|-----------------------------------------|--------------|-----------------|
| .claude/agents/reviewer.md              | Missing      | Add             |
| .claude/skills/observability/SKILL.md   | Missing      | Add             |
| .claude/skills/execute/SKILL.md         | Refreshable  | Refresh (diff)  |
| .claude/agents/backend.md               | Customised   | Skip (note)     |
| CLAUDE.md                               | Customised   | Refresh sections only — Memory protocol + rules 7/8, preserve developer edits |

Ask the developer to confirm globally, or to flip individual rows from Refresh to Skip or vice versa.

Step U4 — Apply

Delegate to system-architect --upgrade with the confirmed plan. The agent:

• Adds new files using the current templates
• For refreshable files, replaces only the auto-generated sections (markers: comments like <!-- forgeline:section:start --> … <!-- forgeline:section:end -->); preserves any content outside markers
• For CLAUDE.md, surgically updates only the architecture rules and Memory protocol sections — never the project-specific Overview or stack rows
• Never deletes files
• Writes an ## Upgrade <YYYY-MM-DD> entry to docs/state/decisions.md listing exactly what changed

Step U5 — Report

Print a summary:

• Added files (count + list)
• Refreshed files (count + list)
• Skipped files (count + list) with one-line reasons
• The docs/state/decisions.md entry that was appended

Suggest: Re-run /plan on a small feature to confirm the new behaviour works end-to-end.

Rules for upgrade mode

• Never delete files. Old artefacts may be referenced elsewhere; deprecation is a separate decision.
• Never overwrite a customised file without explicit per-file approval.
• Preserve docs/state/, docs/plans/, docs/reviews/, docs/security/, and docs/evals/ in their entirety — these are runtime artefacts, not generated templates.
• The upgrade is idempotent — running --upgrade twice in a row with no template changes must result in zero file writes.
• Topology is preserved. If the workspace was generated as swarm, upgrade does not silently switch to supervisor (or vice versa).