team-ship

Assemble a virtual company of AI teammates — each a role — to ship an idea from concept to production.

Context Files

• ${CLAUDE_PLUGIN_ROOT}/skills/team-ship/roles.md - Role definitions (CRITICAL — teammate roster)
• ${CLAUDE_PLUGIN_ROOT}/docs/extending/team-ship-reference.md - Spawn prompts, dependency algo, schemas
• $JAAN_CONTEXT_DIR/tech.md - Tech stack context
• $JAAN_CONTEXT_DIR/config.md - Project configuration
• $JAAN_TEMPLATES_DIR/jaan-to:team-ship.template.md - Orchestration log template
• $JAAN_LEARN_DIR/jaan-to:team-ship.learn.md - Past lessons (loaded in Pre-Execution)
• ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md - Language resolution protocol

Input

Arguments: $ARGUMENTS

Argument	Effect
[initiative]	Idea to build (required unless --detect or --resume)
--track fast	8-skill fast track: PM → Backend → Frontend → QA → DevOps
--track full	20-skill full track: all roles, all design steps (default)
--detect	Detect audit mode: 5 parallel auditors → detect-pack
--roles role1,role2	Custom role selection from roles.md
--dry-run	Display planned team structure without spawning
--resume	Resume from last checkpoint

---

Pre-Execution Protocol

MANDATORY — Read and execute ALL steps in: ${CLAUDE_PLUGIN_ROOT}/docs/extending/pre-execution-protocol.md
Skill name: team-ship
Execute: Step 0 (Init Guard) → A (Load Lessons) → B (Resolve Template) → C (Offer Template Seeding)

Also read context files if available:

• $JAAN_CONTEXT_DIR/tech.md — Tech stack for teammate context
• $JAAN_CONTEXT_DIR/config.md — Project configuration

Language Settings

Read and apply language protocol: ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md
Override field for this skill: language_team-ship

Language exception: Generated code, skill commands, YAML, and role names remain in English.

---

PHASE 0: Validation & Setup

Thinking Mode

ultrathink

Use extended reasoning for:

• Analyzing initiative scope and complexity
• Selecting optimal track and team composition
• Planning dependency graph and execution phases
• Reviewing checkpoint for resume scenarios

Step 1: Environment Checks

1. Agent Teams enabled? Read jaan-to/config/settings.yaml for agent_teams_enabled.
   If false or missing:

   "Agent Teams is not enabled. To use team-ship:

   1. Add agent_teams_enabled: true to jaan-to/config/settings.yaml
   2. Set environment variable: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
   3. Restart Claude Code session"
      STOP — do not proceed.

2. Resume mode? If --resume flag:

   • Scan $JAAN_OUTPUTS_DIR/team/ for most recent checkpoint.yaml
   • If found → load checkpoint, skip to resume point (see reference: "Resume Logic")
   • If not found → inform user, offer to start fresh

Step 2: Parse Arguments

1. Extract initiative text (everything not a flag)
2. Determine track: --track fast, --track full (default), --detect, or --roles
3. Check for --dry-run flag

Step 3: Read Role Catalog

1. Read ${CLAUDE_PLUGIN_ROOT}/skills/team-ship/roles.md
2. Filter roles by selected track
3. If --roles specified: filter to only those roles
4. For --detect: select only detect-* roles

Step 4: Build Team Roster

For each selected role from roles.md:

1. Extract: Title, Model, Skills (for selected track), Phase, Dependencies, Messages
2. Build dependency graph

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/team-ship-reference.md
section "Dependency Graph Resolution Algorithm" for phase grouping logic.

3. Group roles into execution phases by dependency resolution
4. Calculate: total skills, teammate count, max concurrent teammates

Step 5: Read Tech Context

Read $JAAN_CONTEXT_DIR/tech.md (if exists) — summarize in 2-3 lines for spawn prompts.
This summary is injected into each teammate's spawn prompt as {tech_context_summary}.

---

DRY-RUN GATE

If --dry-run flag is set:

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/team-ship-reference.md
section "Dry-Run Display Format" for the output template.

Display team plan: roster, phases, dependency graph, token estimate.
Write plan to $JAAN_OUTPUTS_DIR/team/{id}-{slug}/plan.md.
STOP — do not spawn teammates.

---

HARD STOP — Team Composition Approval

Present to user:

TEAM COMPOSITION
────────────────
Track: {track} ({skill_count} skills)
Initiative: "{initiative}"

Teammates ({count}):
  {role}: {skills_list} [{model}]
  ...

Phases:
  Phase 1: {roles} → PRD approval gate
  Phase 2: {roles} (parallel)
  Phase 3: {roles} (parallel)
  Phase 4: Verify + Changelog (lead)

"Assemble this team and begin? [y/n/edit]"

If edit: let user adjust roles, track, or model choices. Rebuild roster.

Do NOT proceed without explicit approval.

---

PHASE 1: Define (PM Teammate)

Step 6: Spawn PM Teammate

If --detect mode: skip to Phase 2 (Detect Mode).

1. Read spawn prompt template from reference file

   Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/team-ship-reference.md
   section "PM Teammate Prompt" for the full prompt template.

2. Fill template variables: {initiative}, {slug}, {tech_context_summary}
3. Spawn PM teammate with configured model
4. Wait for PM to message lead with PRD path and story paths

Step 7: PRD Approval Gate

When PM completes:

1. Read PRD summary from output path
2. Present PRD summary to user

"The PM has drafted the PRD. Review it at: {prd_path}
Approve to spawn the build team? [y/n/edit]"

If no: provide feedback to PM teammate, PM revises, repeat.
If yes: shut down PM teammate (free context), proceed to Phase 2.

Update checkpoint: phase=1, pm=done, artifacts.prd_path, artifacts.entities.

---

PHASE 2: Design + Build (Parallel Teammates)

Step 8: Spawn Build Team

Determine Phase 2 roles from roster (those with Phase=2).

For each Phase 2 role:

1. Read spawn prompt template from reference file

   Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/team-ship-reference.md
   section "{Role} Teammate Prompt" for each role's template.

2. Fill template variables: {prd_path}, {stories_path}, {entities}, {slug}
3. Spawn teammate with role's configured model
4. Register in shared task list

For --detect mode, instead spawn all detect-* roles from roster in parallel.

Step 9: Monitor & Coordinate

While Phase 2 teammates are active:

1. Relay inter-teammate messages (Backend→Frontend API contract, etc.)
2. Monitor task completion via shared task list
3. Update checkpoint after each role completes a skill
4. If a teammate goes idle, TeammateIdle hook redirects to unclaimed tasks
5. If TaskCompleted hook rejects quality, relay feedback to teammate

When all Phase 2 roles report done:

• For --detect mode: lead runs /jaan-to:detect-pack to consolidate. Skip to Phase 4 wrap-up.
• For build tracks: shut down Phase 2 teammates, proceed to Phase 3.

Update checkpoint: phase=2, role statuses.

---

PHASE 3: Integration + Ship

Step 10: Integration (Lead Runs)

Lead executes directly (not a teammate — integration touches multiple output dirs):

1. /jaan-to:dev-project-assemble — wire scaffolds together
2. /jaan-to:dev-output-integrate — copy to project locations

If integration fails: update checkpoint (status=paused), present error to user.

Step 11: Spawn Phase 3 Teammates

After integration succeeds, spawn Phase 3 roles from roster:

• QA teammate: message to proceed with qa-test-generate → qa-test-run
• DevOps teammate (spawn)
• Security teammate (spawn, full track only)

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/team-ship-reference.md
section "DevOps Teammate Prompt" and "Security Teammate Prompt".

Wait for all Phase 3 teammates to complete. Monitor same as Step 9.

Update checkpoint: phase=3, role statuses.

---

PHASE 4: Verify + Wrap Up

Step 12: Verification

Lead runs directly:

1. /jaan-to:dev-verify — build + runtime validation
2. If tests failed in QA: present results, offer fix-and-retry cycle
3. /jaan-to:release-iterate-changelog — generate changelog

Step 13: Cleanup

1. Shut down any remaining teammates
2. Clean up team resources

Step 14: Write Orchestration Log

Write to $JAAN_OUTPUTS_DIR/team/{id}-{slug}/log.md using template.

Include: initiative, track, team roster, phase timeline, skill outputs, test results, final status.

Step 15: Final Checkpoint

Update checkpoint: phase=4, status=completed.

"Team work complete. Orchestration log: {log_path}
All outputs in: $JAAN_OUTPUTS_DIR/"

---

Step 16: Capture Lessons

"Any feedback on the team orchestration? [y/n]"

If yes: run /jaan-to:learn-add team-ship "{feedback}"

---

Skill Alignment

• Two-phase workflow with HARD STOP for human approval
• Role-based orchestration with configurable teammates
• Token-optimized via reference extraction
• Maintains human control at gate checkpoints

Definition of Done

• Environment checks passed (agent teams enabled, env var set)
• Team roster approved by user
• All roles completed their skill chains
• PRD approved at Phase 1 gate
• Integration successful (dev-project-assemble + dev-output-integrate)
• Tests passing (qa-test-run)
• Verification complete (dev-verify)
• All teammates shut down
• Team cleaned up
• Orchestration log written
• Checkpoint marked as completed