@kennethsolomon/shipkit 3.8.0 → 3.10.0

package/skills/sk:start/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: sk:start
+description: Smart entry point — classifies your task, detects scope, and routes to the optimal flow (feature/debug/hotfix/fast-track), mode (manual/autopilot), and agent strategy (solo/team).
+user_invocable: true
+allowed_tools: Read, Write, Bash, Glob, Grep, Agent, Skill
+---
+
+# Smart Start
+
+Single entry point that classifies your task and recommends the optimal workflow configuration. Replaces the need to know which command to run first.
+
+## Usage
+
+```
+/sk:start <task description>
+/sk:start --manual add user profile page
+/sk:start --team add profile page with API
+/sk:start --debug fix login redirect loop
+/sk:start --hotfix prod payments failing
+/sk:start --fast-track bump lodash dependency
+```
+
+## Steps
+
+### Step 1 — Classify (automatic, no prompt)
+
+Read the task description from arguments. Scan for signal keywords to determine flow and scope:
+
+**Flow detection:**
+
+| Signal Keywords | Detected Flow |
+|----------------|---------------|
+| bug, fix, broken, error, regression, failing, crash, wrong | `debug` (11 steps) |
+| urgent, prod down, hotfix, emergency, critical, production, incident | `hotfix` (11 steps) |
+| config, bump, typo, copy, rename, dependency, upgrade, version, docs | `fast-track` (10 steps) |
+| *(default — no special signals)* | `feature` (21 steps) |
+
+**Scope detection:**
+
+| Signal Keywords | Detected Scope |
+|----------------|----------------|
+| Frontend: component, page, view, CSS, UI, form, modal, button, sidebar, navbar, layout, style, tailwind, animation | `frontend` |
+| Backend: API, endpoint, controller, model, migration, service, queue, job, middleware, database, schema, route | `backend` |
+| Both frontend AND backend keywords present | `full-stack` |
+| Neither | `unknown` (ask user) |
+
+**Agent recommendation:**
+
+| Scope | Agents |
+|-------|--------|
+| `full-stack` | `team` (backend + frontend + QA agents) |
+| `frontend` only | `solo` |
+| `backend` only | `solo` |
+| `unknown` | `solo` (default) |
+
+### Step 2 — Recommend (one prompt, user confirms or overrides)
+
+Present the classification and recommendation:
+
+```
+Detected: [Full-stack feature / Backend bug fix / Frontend hotfix / Small config change / etc.]
+Recommended:
+  Flow:   [feature (21 steps) / debug (11 steps) / hotfix (11 steps) / fast-track (10 steps)]
+  Mode:   [autopilot / manual]
+  Agents: [team (backend + frontend + QA) / solo]
+
+Proceed? (y) or override: manual / no-team / --debug / --hotfix / --fast-track
+```
+
+Default mode recommendation:
+- `feature` flow → recommend `autopilot`
+- `debug` flow → recommend `autopilot`
+- `hotfix` flow → recommend `autopilot`
+- `fast-track` flow → recommend `autopilot`
+
+Wait for user response:
+- `y` or `yes` → proceed with recommendation
+- `manual` → use recommended flow but in manual mode (step-by-step)
+- `no-team` → use autopilot but single-agent (no team)
+- `--debug` → force debug flow
+- `--hotfix` → force hotfix flow
+- `--fast-track` → force fast-track flow
+- Any other override → apply it
+
+### Step 3 — Route (enters the chosen flow)
+
+1. Reset `tasks/workflow-status.md`:
+   - Set all steps to `not yet`
+   - Add metadata to the tracker header:
+     ```
+     > Mode: [autopilot/manual] | Agents: [team/solo] | Flow: [feature/debug/hotfix/fast-track]
+     ```
+
+2. Dispatch to the chosen flow:
+
+   **If autopilot mode:**
+   - Invoke `/sk:autopilot` with the task description
+   - Autopilot handles everything from here
+
+   **If manual mode + team:**
+   - Start the normal step-by-step workflow (`/sk:brainstorm`)
+   - Note in tracker: "Team mode active — activate `/sk:team` at step 9"
+   - User drives each step manually; team mode activates at write-tests/implement
+
+   **If manual mode + solo:**
+   - Start the normal step-by-step workflow (`/sk:brainstorm`)
+   - Standard manual behavior — no changes from current flow
+
+   **If debug flow:**
+   - Invoke `/sk:debug` with the task description
+
+   **If hotfix flow:**
+   - Invoke `/sk:hotfix` with the task description
+
+   **If fast-track flow:**
+   - Invoke `/sk:fast-track` with the task description
+
+## Override Flags
+
+| Flag | Effect |
+|------|--------|
+| `--manual` | Force manual mode (step-by-step, no auto-advance) |
+| `--no-team` | Force single-agent even if full-stack detected |
+| `--team` | Force team mode even if single-domain detected |
+| `--debug` | Force debug flow (bug fix) |
+| `--hotfix` | Force hotfix flow (production emergency) |
+| `--fast-track` | Force fast-track flow (small change) |
+
+Flags can be combined: `/sk:start --manual --team add profile page`
+
+## Relationship to Existing Commands
+
+- `/sk:start` is the **recommended** entry point for all new work
+- Old commands still work as direct entry points:
+  - `/sk:brainstorm` → manual feature workflow
+  - `/sk:debug` → bug fix flow
+  - `/sk:hotfix` → hotfix flow
+  - `/sk:fast-track` → fast-track flow
+  - `/sk:autopilot` → autopilot mode directly
+- `/sk:start` calls those same flows internally — it's a router, not a replacement
+
+## Model Routing
+
+Read `.shipkit/config.json` from the project root if it exists.
+
+- If `model_overrides["sk:start"]` is set, use that model — it takes precedence.
+- Otherwise use the `profile` field. Default: `balanced`.
+
+| Profile | Model |
+|---------|-------|
+| `full-sail` | haiku |
+| `quality` | haiku |
+| `balanced` | haiku |
+| `budget` | haiku |
+
+> Start is a lightweight classifier — haiku is sufficient for keyword matching and routing.

package/skills/sk:team/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: sk:team
+description: Parallel domain agents for full-stack implementation — spawns Backend, Frontend, and QA agents in isolated worktrees.
+user_invocable: true
+allowed_tools: Read, Write, Bash, Glob, Grep, Agent
+---
+
+# Team Mode
+
+Splits implementation across specialized parallel agents when a task spans multiple domains (frontend + backend). Each agent works in an isolated worktree to avoid conflicts. Works in both manual and autopilot modes.
+
+## When to Use
+
+- Full-stack features with both backend API and frontend UI work
+- Tasks where frontend and backend have clear boundaries (separate directories)
+- Changes large enough that parallel implementation saves meaningful time
+
+## When NOT to Use
+
+- Backend-only or frontend-only tasks — single agent is faster
+- Tasks where frontend and backend share files (e.g., Inertia controllers returning views)
+- Small changes (<100 lines estimated) — worktree overhead exceeds time saved
+- Tasks without a clear API contract boundary
+
+## Agents
+
+| Agent | Role | Isolation | Model |
+|-------|------|-----------|-------|
+| **Backend Agent** | Writes backend tests + implements API/services/models | Isolated worktree | sonnet |
+| **Frontend Agent** | Writes frontend tests + implements UI/components/pages | Isolated worktree | sonnet |
+| **QA Agent** | Writes E2E test scenarios while others implement | Background | sonnet |
+
+## Prerequisites
+
+The plan in `tasks/todo.md` MUST contain an explicit **API contract** section defining:
+- Endpoint paths and HTTP methods
+- Request payload shapes (with types)
+- Response payload shapes (with types)
+- Authentication requirements
+- Error response formats
+
+If no API contract is found, team mode warns and falls back to single-agent sequential mode.
+
+## Steps
+
+### 0. Validate Prerequisites
+
+1. Read `tasks/todo.md` — scan for API contract section
+2. If no API contract found:
+   > "No API contract found in plan. Team mode requires explicit endpoint definitions as the shared boundary between agents. Falling back to single-agent mode."
+   - Exit team mode, proceed with normal sequential implementation
+3. If API contract found, continue
+
+### 1. Prepare Worktrees
+
+1. Get current branch name: `git branch --show-current`
+2. Verify working directory is clean: `git status --porcelain`
+3. Note: worktree creation is handled by the Agent tool's `isolation: "worktree"` parameter
+
+### 2. Spawn Agents (parallel)
+
+Launch all 3 agents simultaneously using the Agent tool:
+
+**Backend Agent** (`isolation: "worktree"`):
+- Task: "Read the API contract in tasks/todo.md. Write backend tests for all endpoints (controller tests, model tests, validation tests). Then implement: migrations, models, services, controllers, routes. Make all tests pass. Commit with `feat(backend): [description]`."
+- Receives: full plan from `tasks/todo.md`, `tasks/lessons.md`
+
+**Frontend Agent** (`isolation: "worktree"`):
+- Task: "Read the API contract in tasks/todo.md. Write frontend tests for all components/pages (component tests, interaction tests, form tests). Mock API endpoints using contract shapes. Then implement: API client, composables/hooks, components, pages, routes. Make all tests pass. Commit with `feat(frontend): [description]`."
+- Receives: full plan from `tasks/todo.md`, `tasks/lessons.md`
+
+**QA Agent** (`run_in_background: true`):
+- Task: "Read the plan in tasks/todo.md. Write E2E test scenarios covering all user flows. Do NOT run them — they'll be executed after merge. Report scenario count and coverage summary."
+- Receives: full plan from `tasks/todo.md`
+
+### 3. Wait for Completion
+
+Wait for Backend Agent and Frontend Agent to complete. The QA Agent runs in the background and will be collected later.
+
+For each completed agent, check:
+- Did it succeed or hit 3-strike failure?
+- What files were changed?
+- What tests pass?
+
+### 4. Merge Worktrees
+
+If both agents used worktree isolation and made changes:
+
+1. Check if worktree branches exist
+2. Merge backend worktree branch into feature branch:
+   ```bash
+   git merge <backend-worktree-branch> --no-edit
+   ```
+3. Merge frontend worktree branch into feature branch:
+   ```bash
+   git merge <frontend-worktree-branch> --no-edit
+   ```
+4. If merge conflicts occur:
+   - Attempt auto-resolution for non-overlapping changes
+   - If conflicts are in shared files (routes, config, types), resolve by combining both additions
+   - If conflicts are ambiguous, stop and ask user:
+     > "Merge conflict in [file]. Backend added [X], Frontend added [Y]. Which to keep, or combine?"
+
+### 5. Collect QA Agent Results
+
+Collect the QA Agent's E2E scenarios. These will be used in the E2E gate (step 17).
+
+### 6. Report Results
+
+```
+Team implementation complete:
+  Backend Agent: [N] files changed, [M] tests passing
+  Frontend Agent: [N] files changed, [M] tests passing
+  QA Agent: [N] E2E scenarios written
+  Merge: [clean / N conflicts resolved]
+
+Ready for commit and quality gates.
+```
+
+## Fallback
+
+If worktree creation fails (git state issues, disk space, etc.):
+> "Worktree creation failed: [error]. Falling back to single-agent sequential mode."
+
+Run normal sequential implementation (write-tests → implement) instead.
+
+## Model Routing
+
+Read `.shipkit/config.json` from the project root if it exists.
+
+- If `model_overrides["sk:team"]` is set, use that model — it takes precedence.
+- Otherwise use the `profile` field. Default: `balanced`.
+
+| Profile | Model |
+|---------|-------|
+| `full-sail` | opus (inherit) |
+| `quality` | opus (inherit) |
+| `balanced` | sonnet |
+| `budget` | sonnet |
+
+> `opus` = inherit. When spawning sub-agents via the Agent tool, pass `model: "<resolved-model>"`.