agent-skills/skills/kickstart/SKILL.md

---
name: kickstart
description: "Launch an orchestrator session for a milestone, issue, or task. Use when starting autonomous work on a milestone, orchestrating issue completion, or resuming from a handoff. Triggers on: kickstart, orchestrate, start milestone, resume orchestrator."
---

# Kickstart Orchestrator

Launch an orchestrator session with a single command. Replaces the manual boilerplate of specifying mission, quality gates, branch strategy, and tracking protocol.

**Usage:**
```
/kickstart                     — List open milestones, ask user to pick
/kickstart 0.0.9               — Orchestrate a milestone (by version)
/kickstart M10-Telemetry       — Orchestrate a milestone (by name)
/kickstart #42                 — Orchestrate a single issue
/kickstart MS-SEC-001          — Resume a specific task from tasks.md
/kickstart resume              — Resume from existing docs/tasks.md
```

---

## Step 1: Parse Argument & Detect Context

### 1a. Determine target type

Parse the argument (if any) provided after `/kickstart`:

| Pattern | Type | Example |
|---------|------|---------|
| No argument | **interactive** | `/kickstart` |
| Starts with `#` | **issue** | `/kickstart #42` |
| `resume` (literal) | **resume** | `/kickstart resume` |
| Contains `-` with uppercase + digits at end | **task ID** | `/kickstart MS-SEC-001` |
| Anything else | **milestone** | `/kickstart 0.0.9` or `/kickstart M10-Telemetry` |

### 1b. If no argument (interactive mode)

List open milestones and ask the user to choose:

```bash
~/.claude/scripts/git/milestone-list.sh -s open
```

Present the results and ask:
```
Which target do you want to orchestrate?
A. [milestone 1]
B. [milestone 2]
C. Specific issue number: #___
D. Resume from existing docs/tasks.md
```

Wait for user selection before proceeding.

### 1c. Detect project context

Run these to understand the current project:

```bash
# Get repo info from git remote
REMOTE_URL=$(git remote get-url origin 2>/dev/null)
# Parse org, repo, platform from remote URL

# Check for existing orchestrator state
ls docs/tasks.md 2>/dev/null
ls docs/orchestrator-learnings.json 2>/dev/null

# Detect default branch (usually develop or main)
git branch -r | grep -E 'origin/(develop|main)' | head -1
```

Read the project's `CLAUDE.md` (if it exists) and scan for:
- Quality gate commands (look for `pnpm`, `npm`, `pytest`, `lint`, `typecheck`, `test`)
- Branch conventions
- Task prefix conventions

### 1d. Present context summary to user

Before proceeding, show what was detected:

```
=== Kickstart Context ===
Target:       [milestone/issue/task]
Project:      [org/repo]
Platform:     [Gitea/GitHub]
Branch base:  [develop/main]
Quality gates: [detected commands or "none detected — will ask"]
Existing state: [docs/tasks.md found / none]
```

Ask the user to confirm or override any detected values.

---

## Step 2: Fetch Target Data

### For milestone target

```bash
# Get all open issues in this milestone
~/.claude/scripts/git/issue-list.sh -m "<milestone-name>" -s open

# For each issue, get details (labels, description)
~/.claude/scripts/git/issue-view.sh -i <number>
```

Categorize issues by labels (feature, bug, task, security, etc.) to determine phasing.

### For issue target

```bash
~/.claude/scripts/git/issue-view.sh -i <number>
```

Read the issue description, labels, and any linked milestone.

### For resume target

Read `docs/tasks.md` and determine:
- How many tasks are `done` vs `not-started` vs `in-progress` vs `failed`
- What the next unblocked task is
- Whether any tasks are stuck (in-progress with no agent)

Report status to user before continuing.

---

## Step 3: Load Orchestrator Protocol

**CRITICAL:** Read the full orchestrator guide:

```
Read ~/.claude/agent-guides/orchestrator.md
```

Also load skills relevant to the project's tech stack from the dispatch table in `~/.claude/CLAUDE.md`. For example:
- NestJS project → load `nestjs-best-practices`
- Next.js project → load `next-best-practices`, `vercel-react-best-practices`
- Python project → load `fastapi`, `python-performance-optimization`

Always load these orchestrator-relevant skills:
- `verification-before-completion` — evidence-based completion claims
- `dispatching-parallel-agents` — parallel worker patterns

---

## Step 4: Bootstrap or Resume

### 4a. Fresh milestone/issue (no existing tasks.md)

Create tracking files using templates:

```bash
TEMPLATES=~/src/jarvis-brain/docs/templates

# Create tasks.md scaffold
envsubst < $TEMPLATES/orchestrator/tasks.md.template > docs/tasks.md

# Create learnings tracking
envsubst < $TEMPLATES/orchestrator/orchestrator-learnings.json.template > docs/orchestrator-learnings.json
```

Then populate `docs/tasks.md` with tasks derived from the issues:

- One task row per issue (for milestone targets) or per acceptance criterion (for single issues)
- Set reasonable token estimates based on issue complexity
- Establish dependencies between tasks where logical
- Create feature branches: `feature/<milestone-slug>` as the integration branch

Commit the bootstrap:
```bash
git add docs/tasks.md docs/orchestrator-learnings.json
git commit -m "chore: Bootstrap orchestrator for <target>"
git push
```

### 4b. Resume (existing tasks.md)

Read `docs/tasks.md` and validate:
- Schema matches expected format (id, status, description, issue, branch, etc.)
- No tasks stuck in `in-progress` without an active agent
- Dependencies are consistent (no circular deps, no done tasks blocking not-started)

Mark any orphaned `in-progress` tasks as `not-started` (previous agent likely lost context).

Report to user:
```
=== Resume Status ===
Total tasks:    15
Completed:      8 (53%)
In progress:    0 (reset from orphaned)
Not started:    5
Failed:         2

Next task: MS-SEC-009 — "Add input validation to API endpoints"
```

---

## Step 5: Begin Orchestration

You are now the **orchestrator**. Follow the protocol from `~/.claude/agent-guides/orchestrator.md` exactly.

### Standing Orders (baked in — user never needs to specify these)

1. **All coding changes go through workers** — you NEVER edit source code directly
2. **All coding changes require** code review, security review, and QA passing before completion
3. **Completed issues are closed** in the repo via `~/.claude/scripts/git/issue-close.sh`
4. **tasks.md is the single source of truth** — you are the sole writer
5. **Branch from `develop`** (or whatever was detected/confirmed in Step 1) as the upstream
6. **Max 2 parallel workers** at any time
7. **Two-Phase Completion:** Bulk phase (target 90%), then Polish phase (target 100%)
8. **Context threshold (55-60%):** Output handoff kickstart and STOP — do not compact

### Orchestrator Loop

```
WHILE tasks remain not-started or in-progress:
  1. Find next unblocked task (all depends_on are done)
  2. Update tasks.md: status=in-progress, started_at=now
  3. Spawn worker via Task tool with:
     - Task details and acceptance criteria
     - Branch to work on
     - Quality gate commands
     - Expected JSON result format
  4. Parse worker result JSON
  5. Calculate variance: (actual - estimate) / estimate × 100
  6. Update tasks.md: status=done/failed, completed_at, used
  7. If variance > 50%: log to orchestrator-learnings.json
  8. Commit + push tasks.md update
  9. If issue fully resolved: close issue via git scripts
  10. Check context usage — if >= 55%, go to Handoff
```

### Worker Task Template

When spawning a worker, provide this structure:

```markdown
## Task: {task_id} — {description}

**Issue:** #{issue_number}
**Branch:** {branch_name}
**Base:** {develop|main}

### Requirements
{Issue description and acceptance criteria}

### Quality Gates
Run these before reporting success:
{quality gate commands from project}

### Skills
Read these before starting:
- ~/.claude/skills/{relevant-skill}/SKILL.md

### Report Format
When done, report as JSON:
{
  "task_id": "{id}",
  "status": "success|failed",
  "used": "{token estimate}",
  "commit_sha": "{sha}",
  "notes": "{what was done or why it failed}"
}
```

### Handoff (55-60% context)

When context reaches 55-60%, output this handoff message and STOP:

```
=== ORCHESTRATOR HANDOFF ===

To resume, run:
/kickstart resume

Or programmatically:
claude -p "Read ~/.claude/skills/kickstart/SKILL.md then kickstart resume for project at $(pwd)"

State: docs/tasks.md (committed and pushed)
Progress: X/Y tasks complete
Next task: {task_id} — {description}
```

Then STOP COMPLETELY. Do not continue working.

---

## Quality Gate Detection

If the project CLAUDE.md doesn't specify quality gates, check for these patterns:

| File | Likely Quality Gates |
|------|---------------------|
| `package.json` with `scripts.lint` | `pnpm lint` or `npm run lint` |
| `package.json` with `scripts.test` | `pnpm test` or `npm run test` |
| `package.json` with `scripts.typecheck` | `pnpm typecheck` |
| `tsconfig.json` | `pnpm tsc --noEmit` |
| `pyproject.toml` | `pytest`, `ruff check`, `mypy` |
| `.woodpecker.yml` | Parse pipeline steps for commands |
| `Makefile` | `make lint`, `make test` |

If no quality gates can be detected, ask the user:
```
I couldn't detect quality gate commands for this project.
What commands should workers run to verify their changes?

Examples: "pnpm lint && pnpm typecheck && pnpm test"
```

---

## Notes

- This skill transforms the current session — after kickstart, the agent IS the orchestrator
- The skill itself is just setup instructions — the orchestrator guide has the full execution protocol
- For programmatic use: `claude -p "Read ~/.claude/skills/kickstart/SKILL.md then kickstart milestone X for project at /path"`
- Local-only skill (not in agent-skills repo) because it references `~/.claude/` paths