diff --git a/README.md b/README.md index f618d91..4c5e35a 100644 --- 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 diff --git a/skills/kickstart/SKILL.md b/skills/kickstart/SKILL.md new file mode 100644 index 0000000..e823be6 --- /dev/null +++ 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 "" -s open + +# For each issue, get details (labels, description) +~/.claude/scripts/git/issue-view.sh -i +``` + +Categorize issues by labels (feature, bug, task, security, etc.) to determine phasing. + +### For issue target + +```bash +~/.claude/scripts/git/issue-view.sh -i +``` + +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/` as the integration branch + +Commit the bootstrap: +```bash +git add docs/tasks.md docs/orchestrator-learnings.json +git commit -m "chore: Bootstrap orchestrator for " +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