create-start-work

What this skill does

# Create a Project-Specific Start-Work Skill

You are creating a `/start-work` skill inside a meta-repo's `.claude/skills/start-work/SKILL.md`. This skill will orchestrate the full development lifecycle for that specific project.

## Context Awareness

Check the conversation context. The user may have just set up a meta-repo with `/setup-meta-repo`, or they might reference an existing workspace. Use `$ARGUMENTS` if provided, otherwise infer the target workspace from context or the current working directory.

---

## The Development Phases

Every start-work skill follows this phased lifecycle. The generated skill MUST include all of these:

| # | Phase | What Happens |
|---|-------|-------------|
| 0 | Track | Create phase tracker tasks for visibility |
| 1 | Setup | Fetch issue details, determine scope (which sub-repo(s)), enter plan mode |
| 2 | Research | Create a research team with Explore agents to investigate the codebase in parallel |
| 3 | Plan | Write implementation plan, break into sub-tasks, exit plan mode for user approval |
| 4 | Branch | Create feature branch from base branch in target sub-repo(s) |
| 5 | Implement | Create an implementation team, spawn specialists, monitor progress |
| 6 | Review | Code review of all changes, fix blocking issues |
| 7 | Ship | Commit, push, create PR, update status, shutdown teams, report |

**Phases 2 and 3 happen inside plan mode.** Plan mode is entered at the end of Phase 1 and exited at the end of Phase 3 when the user approves.

---

## Step 1: Research the Workspace

Before asking questions, understand what you're working with:

- Read the root `CLAUDE.md` — understand the sub-repos, their roles, tech stacks
- Check each sub-repo's `CLAUDE.md` — dev commands, build commands, test commands, ports
- Check for existing `.claude/agents/` — what agents already exist?
- Check for existing `.claude/skills/` — what skills are already set up?
- Check `.mcp.json` — what MCP servers are configured?

---

## Step 2: Ask Clarifying Questions

Use `AskUserQuestion`. Skip anything obvious from context.

**Always ask:**
- **Does the team use Linear?** — "Do you use Linear for project management, or should the workflow use raw Claude Code plan mode?"

**Ask if not obvious from context:**
- **Base branch** — What branch do you develop from? (e.g., `develop`, `main`)
- **PR target** — Same as base branch? (usually yes)
- **Branch naming** — What convention? (e.g., `feat/TF-123-description`, `tf-123-description`)
- **Commit style** — Conventional commits? Include ticket ID?

**If Linear:**
- **Branch ticket extraction** — How to extract ticket ID from branch name? (e.g., branch `wha-123-foo` -> ticket `WHA-123`)
- **Ticket prefix** — What's the project prefix in Linear? (e.g., `WHA`, `TF`)

---

## Step 3: Generate the Start-Work Skill

Create `.claude/skills/start-work/SKILL.md` in the workspace root.

### Key Principles for the Generated Skill

1. **Phase gates** — Each phase has explicit pass/fail criteria. Don't proceed until the gate passes.

2. **Teams, not bare agents** — ALWAYS `TeamCreate` before spawning agents. Never use `Task()` without `team_name`.

3. **Research uses Explore teams** — Phase 2 creates a research team with Explore agent teammates scoped to the in-scope sub-repos. The generated skill should describe creating research tasks based on the sub-repos discovered in Phase 1, NOT hardcode specific sub-repo names.

4. **Plan mode for Phases 2-3** — Research and planning both happen inside plan mode. This keeps it read-only until the user approves.

5. **The generated skill can reference creating project-specific agents** — If the workspace doesn't have `.claude/agents/` for its sub-repos, the start-work skill should note that the orchestrator can spawn agent builder tasks to create them on-the-fly based on the project's stack. Don't prescribe specific agents in the generated skill — let the orchestrator determine what's needed per-project.

6. **Implementation team composition is dynamic** — The generated skill should describe spawning specialists based on the scope (which sub-repos are in play), plus always including a test-runner. Don't hardcode agent names — describe the pattern.

7. **Memory checkpoints** — After each phase gate passes, the orchestrator MUST update its auto memory (the persistent memory at `~/.claude/projects/<project>/memory/MEMORY.md` that Claude Code provides). Write the current phase, issue/task ID, team name, branch name, sub-issue/task mappings, and scope. This is NOT a random markdown file — it's Claude Code's built-in memory that persists across sessions and survives context compaction. On resume, the orchestrator reads its memory first to determine where it left off. The generated skill should include explicit "Update memory checkpoint" steps after every phase gate.

8. **Anti-patterns section** — Include common mistakes to avoid (bare agents without teams, skipping phases, re-exploring after research, etc.)

### Linear Mode vs Raw Mode

**If the team uses Linear**, the generated skill should:
- Fetch issue details from Linear MCP in Phase 1
- Create sub-issues in Linear during Phase 3 (orchestrator creates them directly via MCP, NEVER delegates to agents)
- Include a linear-manager equivalent in the implementation team to sync task status back to Linear
- Update parent issue status at key milestones (In Progress, In Review)
- Include the ticket ID in branch names, commits, and PR title
- Use `ToolSearch` to load Linear MCP tools before calling them

**If the team does NOT use Linear**, the generated skill should:
- Accept a plain-text description of the work as `$ARGUMENTS` instead of a ticket ID
- Use Claude Code plan mode natively — research, write plan, get user approval
- Skip all Linear-specific steps (no MCP calls, no issue creation, no status updates)
- Still follow the same phase structure (setup → research → plan → branch → implement → review → ship)
- Use task lists (`TaskCreate`/`TaskUpdate`) for tracking instead of Linear

### Customization Points

Replace these with project-specific values:

| Placeholder | Source |
|:------------|:-------|
| Base branch | User answer (e.g., `develop`, `main`) |
| Branch naming pattern | User answer |
| Sub-repo names and descriptions | From root CLAUDE.md |
| Dev/build/test/lint commands per sub-repo | From each sub-repo's CLAUDE.md |
| Commit message format | User answer |
| PR template | User answer or generate from project conventions |
| Linear ticket prefix | User answer (Linear mode only) |
| Docker / migration ownership | From root CLAUDE.md |

### Structure of the Generated Skill

The generated `SKILL.md` should follow this structure:

```
---
name: start-work
description: Start work on [a Linear issue / a task]. Orchestrates the full development lifecycle from [issue/task] to PR.
argument-hint: [issue-id or task description]
disable-model-invocation: false
allowed-tools: [appropriate tools list]
---

# Start Work

## Hard Rules
[Project-specific rules + universal rules like "always TeamCreate before agents"]

## Anti-Patterns
[Common mistakes table]

## Phase Overview
[Table of all 8 phases with gates]

## Phase 0: Track
[Create tracker tasks + write initial memory checkpoint]

## Phase 1: Setup
[Fetch issue/understand task, determine scope, enter plan mode]
→ Memory checkpoint: issue ID, scope, target repos

## Phase 2: Research (Inside Plan Mode)
[Create research team, spawn Explore agents for in-scope repos, synthesize, cleanup team]
→ Memory checkpoint: research summary location, team status

## Phase 3: Plan (Inside Plan Mode)
[Write plan, create sub-tasks (in Linear or TaskList), exit plan mode]
→ Memory checkpoint: sub-issue/task mappings, plan approved

## Phase 4: Branch
[Create feature branch from base branch in target sub-repos]
→ Memory checkpoint: branch name(s)

## Phase 5: Implement
[Create impl team, spawn specialists + test-runner (+ linear-manager if Linear), monitor]
→ Memory checkpoint: te