| name | team-designer |
| description | Meta-skill for generating team skills following the v4 architecture pattern. Produces complete skill packages with SKILL.md router, coordinator, worker roles, specs, and templates. Triggers on "team-designer", "design team". |
| allowed-tools | ["AskUserQuestion","Bash","Edit","Glob","Grep","Read","Write","mcp__maestro__team_msg","teammate"] |
| session-mode | run |
<required_reading>
@~/.maestro/workflows/run-mode-lite.md
</required_reading>
Team Skill Designer
Generate complete team skills following the team-lifecycle-v4 architecture: SKILL.md as universal router, coordinator with beat model, worker roles with optional commands/, shared specs, and templates.
Architecture Overview
┌─────────────────────────────────────────────────────────────────┐
│ Team Skill Designer (SKILL.md) │
│ → Orchestrator: gather requirements, generate files, validate │
└───────────────────────────┬──────────────────────────────────────┘
│
┌───────────┬───────────┼───────────┬───────────┐
↓ ↓ ↓ ↓
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ Phase 1 │ │ Phase 2 │ │ Phase 3 │ │ Phase 4 │
│ Require │ │ Scaffold│ │ Content │ │ Valid │
│ Analysis│ │ Gen │ │ Gen │ │ & Report│
└─────────┘ └─────────┘ └─────────┘ └─────────┘
↓ ↓ ↓ ↓
teamConfig SKILL.md roles/ Validated
+ dirs specs/ skill pkg
templates/
Key Design Principles
- v4 Architecture Compliance: Generated skills follow team-lifecycle-v4 pattern — SKILL.md = pure router, beat model = coordinator-only, unified structure (roles/ + specs/ + templates/)
- Golden Sample Reference: Uses
team-lifecycle-v4 as reference implementation at ~ or <project>/.pi/skills/team-lifecycle-v4/
- Intelligent Commands Distribution: Auto-determines which roles need
commands/ (2+ commands) vs inline logic (1 command)
- team-worker Compatibility: Role.md files include correct YAML frontmatter for team-worker agent parsing
Pre-load (before execution)
- Codebase docs: If
.workflow/codebase/ARCHITECTURE.md exists, read for module boundaries
- Specs (coding):
maestro load --type spec --category coding — load coding constraints as shared context
- Wiki knowledge:
maestro search "skill design team architecture" --json — top 5 entries as prior context
- All optional — proceed without if unavailable
Execution Flow
Input Parsing:
└─ Parse user requirements (skill name, roles, pipelines, domain)
Phase 1: Requirements Analysis
└─ Ref: phases/01-requirements-analysis.md
├─ Tasks: Detect input → Gather roles → Define pipelines → Build teamConfig
└─ Output: teamConfig
Phase 2: Scaffold Generation
└─ Ref: phases/02-scaffold-generation.md
├─ Tasks: Create dirs → Generate SKILL.md router → Verify
└─ Output: SKILL.md + directory structure
Phase 3: Content Generation
└─ Ref: phases/03-content-generation.md
├─ Tasks: Coordinator → Workers → Specs → Templates
└─ Output: roles/**/*.md, specs/*.md, templates/*.md
Phase 4: Validation
└─ Ref: phases/04-validation.md
└─ Output: Validation report (PASS/REVIEW/FAIL)
Return:
└─ Summary with skill location and usage instructions
Phase Reference Documents (read on-demand when phase executes):
Golden Sample
Generated skills follow the architecture of ~ or <project>/.pi/skills/team-lifecycle-v4/:
.claude/skills/<skill-name>/
├── SKILL.md # Universal router (all roles read)
├── roles/
│ ├── coordinator/
│ │ ├── role.md # Orchestrator + beat model + entry router
│ │ └── commands/
│ │ ├── analyze.md # Task analysis
│ │ ├── dispatch.md # Task chain creation
│ │ └── monitor.md # Beat control + callbacks
│ ├── <inline-worker>/
│ │ └── role.md # Phase 2-4 embedded (simple role)
│ └── <command-worker>/
│ ├── role.md # Phase 2-4 dispatcher
│ └── commands/
│ ├── <cmd-1>.md
│ └── <cmd-2>.md
├── specs/
│ ├── pipelines.md # Pipeline definitions + task registry
│ └── <domain-specs>.md # Domain-specific specifications
└── templates/ # Optional document templates
Data Flow
User Input (skill name, roles, pipelines)
↓
Phase 1: Requirements Analysis
↓ Output: teamConfig
↓
Phase 2: Scaffold Generation
↓ Input: teamConfig
↓ Output: SKILL.md + skillDir
↓
Phase 3: Content Generation
↓ Input: teamConfig + skillDir
↓ Output: roles/, specs/, templates/
↓
Phase 4: Validation
↓ Input: teamConfig + all files
↓ Output: validation report
↓
Return summary to user
Core Rules
- Start Immediately: First action is Phase 1 execution
- Parse Every Output: Extract teamConfig from Phase 1 for subsequent phases
- Auto-Continue: After each phase, automatically execute next phase
- Progressive Phase Loading: Read phase docs ONLY when that phase is about to execute
- Golden Sample Fidelity: Generated files must match team-lifecycle-v4 patterns
- DO NOT STOP: Continuous workflow until all 4 phases complete
Input Processing
Convert user input to structured format:
SKILL_NAME: [kebab-case name, e.g., team-code-review]
DOMAIN: [what this team does, e.g., "multi-stage code review with security analysis"]
ROLES: [worker roles beyond coordinator, e.g., "analyst, reviewer, security-expert"]
PIPELINES: [pipeline types and flows, e.g., "review-only: SCAN-001 → REVIEW-001 → REPORT-001"]
SESSION_PREFIX: [3-4 char, e.g., TCR]
Error Handling
- Invalid role name: Must be lowercase alphanumeric with hyphens, max 20 chars
- Circular dependencies: Detect and report in pipeline validation
- Missing golden sample: Fall back to embedded templates in phase files
- Directory conflict: Warn if skill directory already exists, ask user to confirm overwrite
