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:

"${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:

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

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

---

Step 2: Fetch Target Data

For milestone target

# 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

"${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:

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

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