expand-team

name	expand-team
description	Add agents and skills to an existing multi-agent configuration. Lists available roles, generates agent files, and updates coordination rules. Also supports evolving the project phase.
argument-hint	[add <role-name> | list | remove <role-name> | evolve <phase> | status]
user-invocable	true
allowed-tools	Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion
model	sonnet

When this skill is invoked, it extends the existing multi-agent team or evolves the project phase.

---

1. Parse Arguments

Parse the argument:

• add <role-name> → add a specific agent
• list → show available agents to add
• remove <role-name> → remove an agent (with confirmation)
• evolve <phase> → transition project to a new phase (prototype/production)
• status → show current team status and config metadata
• No argument → show interactive menu

If no argument, skip to Phase 2 (Interactive Menu).

---

2. Phase 1 — Load Current State

2a: Detect Current Configuration

Glob ".claude/agents/*.md"
Glob ".claude/skills/*/SKILL.md"
Glob ".claude/hooks/*.sh"
Read ".claude/config-meta.json" (if exists)
Read "production/session-state/active.md" (if exists)

Build a list of:

• Existing agents: names extracted from glob results
• Existing skills: names extracted from glob results
• Existing hooks: names extracted from glob results
• Config metadata: profile, phase, generated files

2b: Detect Project Profile

Try to determine which profile was used during /project-init:

1. Check .claude/config-meta.json for "profile" field
2. If not found, check production/session-state/active.md for a "Profile" line
3. If not found, scan for profile match signals (same logic as /project-init Phase 1)
4. If no profile matches, ask the user which profile to use

Read the matching profile file:

Read profiles/{{detected-type}}.md

2c: Build Available List

From the profile's Extended Agents list, subtract agents that already exist. The result is the "available to add" list.

Similarly for Extended Skills.

---

3. Phase 2 — Interactive Menu (if no argument)

If no argument was provided, show an interactive menu:

## Expand Team

**Current team**: {{N}} agents, {{M}} skills, {{H}} hooks
**Profile**: {{type}}
**Phase**: {{current-phase}}
**Collaboration**: {{collaboration-mode}}

### Available Agents to Add
| Agent | Tier | Description | Dependencies |
|-------|------|-------------|--------------|
{{table of available extended agents}}

### Available Skills to Add
| Skill | Description | Required Agents |
|-------|-------------|-----------------|
{{table of available extended skills}}

AskUserQuestion: "What would you like to do?"

• Options: "[A] Add an agent" / "[B] Add a skill" / "[C] Evolve phase" / "[D] Show status" / "[E] Done"

If [A]: ask which agent. If [B]: ask which skill (and check if required agents exist). If [C]: run Evolution flow (Phase 5). If [D]: show status. If [E]: exit.

---

4. Phase 3 — Add Agent

4a: Validate

Check if the requested agent exists in the profile's extended list:

• If not found: "Agent '{{name}}' is not available for {{type}} projects. Available: {{list}}"
• If already exists: "Agent '{{name}}' already exists. Would you like to regenerate it?"
• If has dependencies: check if dependency agents exist. If not: "{{name}} requires {{dependency}}. Add both?"

4b: Read Template

Read the appropriate template:

• If agent tier = director → templates/agent-director.md
• Otherwise → templates/agent-minimal.md

Adapt template for collaboration mode: Read .claude/config-meta.json to check collaboration_mode. Apply the corresponding template adaptation section (Panel/Pipeline/Flat mode).

4c: Generate Agent File

Generate the agent file by filling the template with values from the profile:

Write .claude/agents/{{agent-name}}.md

Fill all template placeholders with real content derived from:

1. Agent's description and tier from the profile
2. Project's detected language/framework
3. The agent's position in the hierarchy (reports to, coordinates with)

4d: Update Coordination Rules

Read .claude/docs/coordination-rules.md. Add the new agent to the hierarchy and delegation rules.

Edit .claude/docs/coordination-rules.md

4e: Update Coordination Map

Read .claude/docs/agent-coordination-map.md. Add the new agent to the hierarchy diagram and delegation table.

Edit .claude/docs/agent-coordination-map.md

4f: Update Config Metadata

Read .claude/config-meta.json. Add the new agent to the files.agents array and increment generation_count.

Edit .claude/config-meta.json

4g: Check for Unlockable Skills

Some skills require specific agents. After adding the agent, check if any previously unavailable skills are now unlockable:

From the profile's Extended Skills table, find skills whose Requires column includes the just-added agent AND whose other required agents all exist.

If unlockable skills found:

Adding {{agent-name}} unlocks these skills:
- {{skill-1}}: {{description}}
- {{skill-2}}: {{description}}

Would you like to add them?

4h: Present Result

## Agent Added: {{agent-name}}

**Tier**: {{tier}}
**Model**: {{model}}
**Reports to**: {{parent}}
**Coordinates with**: {{siblings}}

{{If skills were unlocked:}}
**Unlocked skills**: {{list}}

---

5. Phase 4 — Add Skill

5a: Validate

Check if the requested skill exists in the profile's extended list:

• If not found: list available skills
• If already exists: "Skill '{{name}}' already exists. Regenerate?"
• If has required agents: check they all exist. If not: "{{skill}} requires agents: {{list}}. Missing: {{missing}}. Add them first?"

5b: Generate Skill

Read the appropriate template:

• Review/gate skills → templates/skill-review.md
• Pipeline/feature skills → templates/skill-pipeline.md
• Workflow skills → templates/skill-workflow.md

Generate the skill:

mkdir -p .claude/skills/{{skill-name}}
Write .claude/skills/{{skill-name}}/SKILL.md

5c: Update Config Metadata

Add the new skill to .claude/config-meta.json files.skills array.

5d: Present Result

## Skill Added: {{skill-name}}

**Command**: /{{skill-name}}
**Description**: {{description}}
**Agents used**: {{list}}

---

6. Phase 5 — Remove (if requested)

6a: Dependency Check

Before removing an agent, check if any existing skills reference it via Task spawning:

Grep pattern="{{agent-name}}" path=".claude/skills/"

If found:

"Warning: {{N}} skills reference {{agent-name}}. Removing it will break these workflows: {{list}}. Proceed?"

6b: Remove

Delete .claude/agents/{{agent-name}}.md

Update coordination rules and map to remove the agent. Update config-meta.json to remove from files.agents.

---

7. Phase 6 — Evolution Mode

When the user wants to switch project phases.

7a: Load Current State

Read ".claude/config-meta.json"

Extract: current phase, profile, generated files list.

7b: Ask Target Phase

AskUserQuestion: "What phase are you transitioning to?"

• Options:
  • "[A] Prototype — relax rules, fast iteration"
  • "[B] Production — tighten rules, full validation"
  • "[C] Custom phase name"

7c: Show Diff Plan

Based on current phase → target phase, compute what changes:

## Phase Evolution: {{current}} → {{target}}

### Rules Changes
| Rule File | Action | Reason |
|-----------|--------|--------|
| {{rule}} | {{Add/Remove/Modify}} | {{why}} |

### Hook Changes
| Hook | Action | Reason |
|------|--------|--------|
| {{hook}} | {{Add/Enable/Disable}} | {{why}} |

### Skill Changes
| Skill | Action | Reason |
|-------|--------|--------|
| {{skill}} | {{Add/Enable/Relax}} | {{why}} |

### Agent Changes
| Agent | Action | Reason |
|-------|--------|--------|
| {{agent}} | {{Modify review level}} | {{why}} |

7d: Apply Changes

After user confirms:

1. Prototype phase:

   • Relax rules: comment out strict checks, keep only security basics
   • Disable heavy hooks: keep session-start, disable validate-push
   • Disable gate skills: skip sign-off phases in pipeline skills
   • Reduce agent review: allow more autonomous operation

2. Production phase:

   • Tighten rules: enable all checks including security, compliance
   • Enable all hooks: full validation chain
   • Enable gate skills: require sign-off on all pipeline completions
   • Full agent review: no autonomous file writes

3. Custom phase:

   • Ask which specific changes the user wants
   • Apply selectively

7e: Update Metadata

Edit .claude/config-meta.json
  "project_phase": "{{new-phase}}",
  "last_evolution": {
    "from": "{{old-phase}}",
    "to": "{{new-phase}}",
    "timestamp": "{{current-time}}"
  }

7f: Present Result

## Phase Evolved: {{old-phase}} → {{target}}

### Changes Applied
- {{N}} rule files modified
- {{M}} hooks updated
- {{K}} skills adjusted
- {{J}} agent configs updated

### What's Different Now
{{human-readable summary of key changes}}

### Rollback
To undo: `/expand-team evolve {{old-phase}}`

---

8. Status Command

When the user runs /expand-team status:

## Team Status

**Profile**: {{type}}
**Phase**: {{current-phase}}
**Collaboration**: {{collaboration-mode}}
**Generated**: {{timestamp}} ({{generation_count}} generations)

### Agents ({{N}} total)
| Agent | Tier | Model | Status |
|-------|------|-------|--------|
{{list all agents with their status}}

### Skills ({{M}} total)
| Skill | Type | Status |
|-------|------|--------|
{{list all skills}}

### Hooks ({{H}} total)
| Hook | Status |
|------|--------|
{{list all hooks with enabled/disabled status}}

### Config Health
- [{{check}}] All agents reference existing agents in delegation map
- [{{check}}] All skills reference existing agents
- [{{check}}] Config-meta.json matches actual files on disk
- [{{check}}] No orphaned files (generated but not in config-meta)

---

9. Summary

After all additions/removals/evolutions, present a final summary:

## Team Updated

**Current team**: {{N}} agents (+{{added}}, -{{removed}})
**Phase**: {{current-phase}}
**Available to add**: {{remaining}} agents, {{remaining-skills}} skills

Run `/expand-team` again to continue expanding.
Run `/expand-team evolve <phase>` to switch project phase.
Run `/expand-team status` to see full team status.
Run any `/skill-name` to start using the team.