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
"${MOSAIC_HOME:-$HOME/.config/mosaic}/rails/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 `AGENTS.md` first (and `SOUL.md` if present). If only `CLAUDE.md` exists, use it as compatibility fallback. 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]
Delegation:   [native-subagent | matrix-rail-fallback]
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.

### 1e. Detect delegation mode

Before orchestration begins, decide delegation mode:

- **native-subagent**: runtime has reliable subagent/background task primitive
- **matrix-rail-fallback**: use deterministic Mosaic rail when native primitive is absent/unreliable

Fallback commands:

```bash
~/.config/mosaic/bin/mosaic-orchestrator-matrix-cycle
~/.config/mosaic/bin/mosaic-orchestrator-run --poll-sec 10
```

---

## Step 2: Fetch Target Data

### For milestone target

```bash
# Get all open issues in this milestone
"${MOSAIC_HOME:-$HOME/.config/mosaic}/rails/git/issue-list.sh" -m "<milestone-name>" -s open

# For each issue, get details (labels, description)
"${MOSAIC_HOME:-$HOME/.config/mosaic}/rails/git/issue-view.sh" -i <number>
```

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

### For issue target

```bash
"${MOSAIC_HOME:-$HOME/.config/mosaic}/rails/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 ~/.config/mosaic/guides/orchestrator.md
```

Also load skills relevant to the project's tech stack from project docs (`AGENTS.md`/`SOUL.md`) plus `~/.config/mosaic/STANDARDS.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 `~/.config/mosaic/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. **Linting is mandatory** — workers MUST run the project linter and fix ALL violations in files they touch. Zero lint errors. No disabling rules. No skipping files. This is non-negotiable.
4. **Completed issues are closed** in the repo via `"${MOSAIC_HOME:-$HOME/.config/mosaic}/rails/git/issue-close.sh"`
5. **tasks.md is the single source of truth** — you are the sole writer
6. **Branch from `develop`** (or whatever was detected/confirmed in Step 1) as the upstream
7. **Max 2 active worker tasks** at any time (applies to native and matrix modes)
8. **Two-Phase Completion:** Bulk phase (target 90%), then Polish phase (target 100%)
9. **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. Delegate worker task with:
     - Task details and acceptance criteria
     - Branch to work on
     - Quality gate commands
     - Expected JSON result format
     - Native mode: runtime Task/subagent primitive
     - Matrix mode: queue task in `.mosaic/orchestrator/tasks.json` and run `~/.config/mosaic/bin/mosaic-orchestrator-matrix-cycle`
  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 (MANDATORY — zero tolerance)
Run ALL of these before reporting success. Fix every failure.
```
{quality gate commands from project}
```
**Linting is NON-NEGOTIABLE.** Run the project linter and fix ALL violations
in every file you touched. Do NOT leave lint warnings, do NOT disable rules,
do NOT skip files. If you changed it, you lint it.

### Skills
Read these before starting:
- ~/.config/mosaic/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:
[runtime command] "Read ~/.config/mosaic/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 project docs (`AGENTS.md`/`SOUL.md`/`CLAUDE.md`) don'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: pass this skill file path to your active runtime and request kickstart for the target repo.
- This skill is runtime-agnostic and expects Mosaic rails/guides at `~/.config/mosaic`.