team-ship

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)
--track tdd	TDD track: qa-test-cases → qa-tdd-orchestrate → qa-test-mutate → qa-quality-gate
--track sprint	Sprint track: reads sprint plan artifact from pm-sprint-plan, executes dynamic skill queue
--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), --track sprint, --detect, or --roles
3. Check for --dry-run flag

Sprint Track Mode

If --track sprint:

1. Read the latest sprint plan artifact:

   SPRINT_PLAN=$(ls -t $JAAN_OUTPUTS_DIR/pm/sprint-plan/*/*.md 2>/dev/null | head -1)
   

2. If not found → "No sprint plan found. Run /pm-sprint-plan first."
3. Parse YAML frontmatter for queue array and closing_skills
4. Build team roster dynamically from queue roles (only spawn roles that appear in the queue)
5. Override initiative text with sprint plan focus area
6. Skip PM teammate (Phase 1) — sprint plan replaces PRD

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/team-ship-reference.md section "Sprint Track Execution" for plan consumption and verification gate logic.

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 (for selected track), 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 9a: TDD Track Execution (--track tdd)

If --track tdd selected, execute this specialized pipeline instead of standard Phase 2-3:

TDD Pipeline:

1. qa-test-cases -- Generate BDD test cases from initiative
2. qa-tdd-orchestrate -- Run RED/GREEN/REFACTOR cycles with context isolation
3. qa-test-mutate -- Validate test effectiveness via mutation testing
4. qa-quality-gate (if available) -- Compute composite quality score

If qa-quality-gate skill is not available: skip with explicit warning: "Quality gate skill not available -- skipping composite scoring. Run qa-test-run coverage report as fallback."

TDD-Specific Roles:

tdd-writer role:

• Spawn prompt restricts to: requirements text + test framework docs ONLY
• Excluded: implementation plans, existing source code, scaffold output
• Skills: qa-test-cases, qa-tdd-orchestrate (RED phase)

tdd-implementer role:

• Spawn prompt restricts to: failing test output + test file content ONLY
• Excluded: requirements text, RED agent reasoning, architecture plans
• Skills: qa-tdd-orchestrate (GREEN phase)

Execution Rules:

• Max 5 concurrent teammates per phase (fan-out cap)
• DAG validation: verify dependency graph is acyclic before spawning
• After TDD pipeline completes, skip to Phase 4 (Verify + Wrap Up)

Update checkpoint: track=tdd, pipeline stages.

---

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:
  • Fast track: qa-test-generate → qa-test-run
  • Full track: qa-test-generate → qa-test-run → qa-contract-validate "{api_contract_path}"
• 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. If visual-qa role was active: read visual verification report, present summary to user
4. /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