agent-skills/skills/kickstart/SKILL.md

name, description

name	description
kickstart	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:

~/.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:

# 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

# 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

~/.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:

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:

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:

## 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