feat: Add kickstart skill — orchestrator launcher via /kickstart command

/kickstart [milestone|issue|task] replaces manual orchestrator boilerplate. Auto-discovers project context, fetches issues from Gitea/GitHub, bootstraps tracking files, and transforms the session into an orchestrator. Modes: milestone, issue, task ID, resume, interactive (no args) Built-in: quality gates, Two-Phase Completion, context handoff protocol Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-16 16:59:04 -06:00
parent 798fce9487
commit 1ebc161f2c
2 changed files with 329 additions and 4 deletions
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # Agent Skills

-Complete agent skill fleet for Mosaic Stack. 93 skills across 11 domains — coding, business development, design, marketing, writing, orchestration, document generation, Vue/Vite ecosystem, and more. Platform-aware — works with both GitHub (`gh`) and Gitea (`tea`) via our abstraction scripts.
+Complete agent skill fleet for Mosaic Stack. 94 skills across 12 domains — coding, business development, design, marketing, writing, orchestration, document generation, Vue/Vite ecosystem, and more. Platform-aware — works with both GitHub (`gh`) and Gitea (`tea`) via our abstraction scripts.

 ## Security Audit

@@ -14,9 +14,9 @@ All skills were reviewed on 2026-02-16. Findings:
 | W-002 | WARNING | `mcp-builder` | Can connect to arbitrary MCP servers | Awareness only — review server URLs |
 | W-003 | WARNING | `create-agent` | Uses `Function()` constructor (eval equivalent) | Awareness only — review generated code |

-88 of 93 skills passed all checks as clean instruction-only SKILL.md files.
+88 of 93 audited skills passed all checks as clean instruction-only SKILL.md files.

-## Skills (93)
+## Skills (94)

 ### Code Quality & Review (5)

@@ -157,6 +157,12 @@ All skills were reviewed on 2026-02-16. Findings:
 | `pinia` | Pinia state management | antfu |
 | `antfu` | Anthony Fu's coding conventions | antfu |

+### Orchestration (1)
+
+| Skill | Purpose | Origin |
+|-------|---------|--------|
+| `kickstart` | Launch orchestrator for milestone/issue/task — auto-discovers context, bootstraps tracking | Mosaic Stack |
+
 ### Meta / Skill Authoring (4)

 | Skill | Purpose | Origin |
@@ -185,7 +191,7 @@ All skills were reviewed on 2026-02-16. Findings:
 | [wshobson/agents](https://github.com/wshobson/agents) | 3 | Architecture, Python, Tailwind |
 | [mblode/agent-skills](https://github.com/mblode/agent-skills) | 1 | UI animation |
 | [giuseppe-trisciuoglio/developer-kit](https://github.com/giuseppe-trisciuoglio/developer-kit) | 1 | shadcn/ui |
-| Adapted (Mosaic Stack) | 2 | PR review, code review |
+| Mosaic Stack (original) | 3 | PR review, code review, orchestration |

 ## Installation

--- a/skills/kickstart/SKILL.md
+++ b/skills/kickstart/SKILL.md
@@ -0,0 +1,319 @@
+---
+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