Merge branch 'feat/v0.13-onboard' — /onboard auto-project-analyze skill

2026-04-22 08:50:09 +08:00 · 2026-04-22 08:50:09 +08:00 · 33cd9a489b
commit 33cd9a489b
parent 9ca7c4e148 293e96af5d
6 changed files with 773 additions and 0 deletions
--- a/skills/onboard/SKILL.md
+++ b/skills/onboard/SKILL.md
@ -0,0 +1,132 @@
+---
+name: onboard
+description: Scan a project (or scope of projects) and propose candidate agents, hooks, and primitives based on detected stack, CI, deploy, tests, and env surface. Three modes — Full auto, Step-by-step, Full manual — reuse the same scan+propose foundation and differ only in confirm-gate count. Delegates to /new-agent, /escalate-recurrence, and kei-sleep-queue.
+argument-hint: <project-path or glob scope>
+---
+
+# Onboard — Auto Project Analysis (index)
+
+You are analysing an existing project (or a scope of projects) and proposing
+the right kit artefacts for it: project-specialist agents, stack-specific
+hooks, and install-time primitives.
+
+This skill is a **proposer + applier**, not a manifest writer. It
+scans, scores, proposes, and then delegates each accepted candidate to the
+existing pipeline:
+
+- **Agents** → handoff to `/new-agent` (the 8-phase wizard)
+- **Hooks + rules** → handoff to `/escalate-recurrence`
+- **Primitives** → `kei-sleep-queue add` (or direct `install.sh --add=`
+  suggestion in the final report)
+
+This `SKILL.md` is the INDEX. Each phase lives in its own file and runs in
+strict order. Never skip or re-order phases.
+
+---
+
+## Prerequisite check
+
+Before Phase 1, verify the kit baseline is present:
+
+- `~/.claude/skills/new-agent/SKILL.md` (or the kit-shipped
+  `skills/new-agent/SKILL.md`) — required for agent delegation
+- `~/.claude/skills/escalate-recurrence/SKILL.md` — required for hook/rule
+  delegation
+- `~/.claude/skills/compose-solution/SKILL.md` — required only when a
+  proposed candidate crosses artefact boundaries
+
+If any are missing, stop and tell the user: "Install KeiSeiKit v0.12+ first
+(run `install.sh --profile=dev` from the kit repo)." Do not fall through.
+
+---
+
+## Pipeline overview (5 phases + final report)
+
+| Phase | File | Purpose | AskUserQuestion |
+|---|---|---|---|
+| 1 | [phase-1-scan.md](phase-1-scan.md) | Free-text intake + Bash scan of artefacts | 1× (scope granularity, multi-project only) |
+| 2 | [phase-2-propose.md](phase-2-propose.md) | Analyse scan → propose N agents, M hooks, K primitives | 0 |
+| 3 | [phase-3-mode-pick.md](phase-3-mode-pick.md) | Pick Full auto / Step-by-step / Full manual | 1× |
+| 4 | [phase-4-apply.md](phase-4-apply.md) | Apply by mode (each mode has its own confirm-gates) | 1-N× |
+| 5 | [phase-5-report.md](phase-5-report.md) | Summary + suggested next steps | 0 |
+
+Minimum AskUserQuestion count across the 5 phases: **6** — 1 (Phase 1
+scope-granularity if multi-project), 1 (Phase 3 mode), at least 4 inside
+Phase 4 (mode-specific confirms: Full-auto has 1; Step-by-step has ≥N per
+candidate; Full manual delegates per candidate, each wizard emitting its
+own AskUserQuestion calls).
+
+---
+
+## Variables the pipeline produces
+
+| Name | Set in | Meaning |
+|---|---|---|
+| `PATHS` | Phase 1a | One or more project root paths (glob-resolved) |
+| `SCAN` | Phase 1b | Per-project scan summary: stack, CI, deploy, tests, README-purpose, recent activity, env-var surface |
+| `CANDIDATES` | Phase 2 | List of (kind, name, confidence, rationale) tuples — kind ∈ {agent, hook, primitive} |
+| `MODE` | Phase 3 | full-auto / step-by-step / full-manual |
+| `APPLIED` | Phase 4 | Candidates that were applied (path + delegation target) |
+| `SKIPPED` | Phase 4 | Candidates the user declined |
+
+---
+
+## Final report (emit after Phase 5)
+
+```
+=== ONBOARD REPORT ===
+Scope:       <1 project | N projects>
+Scan:        <stack(s) | CI | deploy | tests | env-vars>
+Proposed:    <N agents | M hooks | K primitives>
+Mode:        <full-auto | step-by-step | full-manual>
+Applied:     <N agents | M hooks | K primitives>
+Skipped:     <count>
+Next:        <e.g. "run install.sh --profile=dev to enable /schema-design if DB detected">
+```
+
+---
+
+## Rules (apply throughout)
+
+- **RULE 0.4 (NO HALLUCINATION).** Phase-1 scan uses exact grep/ls output.
+  If grep returns nothing for a framework, mark it as "not detected". Never
+  invent a framework based on directory names or README prose alone.
+  Confidence grade (E3-E4 for scan-derived, never E1-E2).
+- **RULE 0.8 (SECRETS).** Never read actual `.env` or `secrets/*.env` files.
+  Read only `.env.example`, `.env.template`, and schema files. The env-var
+  surface in Phase 1b is the list of KEY names, never values.
+- **RULE 0.13 (NO GIT).** This skill does not invoke git. The orchestrator
+  (or the user in a follow-up turn) handles commits.
+- **NO DOWNGRADE.** Any phase that fails returns 2-3 constructive paths,
+  never "can't be done". Example: scan finds no lockfile → propose
+  "(A) Ask user to specify stack, (B) Scan for code-file extensions, (C)
+  Skip stack-specialisation, propose generic agent only".
+- **Plan Mode First.** This skill IS the plan; each phase has a
+  verify-criterion. No Edit/Write before the corresponding phase's
+  confirm click.
+- **Constructor Pattern.** Each phase file is a single cube. This index
+  stays ≤200 LOC; phase files each ≤150 LOC. Candidates that exceed
+  complexity budget at application time are split — never stuffed into
+  one manifest.
+- **Surgical Changes.** Onboard writes nothing directly — all writes are
+  delegated to `/new-agent`, `/escalate-recurrence`, or `kei-sleep-queue`.
+  The only in-place artefacts onboard produces are ephemeral scan summaries
+  displayed in the conversation.
+
+---
+
+## References
+
+- [phase-1-scan.md](phase-1-scan.md) · [phase-2-propose.md](phase-2-propose.md)
+  · [phase-3-mode-pick.md](phase-3-mode-pick.md) · [phase-4-apply.md](phase-4-apply.md)
+  · [phase-5-report.md](phase-5-report.md)
+- `skills/new-agent/SKILL.md` — agent delegation target (Phase 4)
+- `~/.claude/skills/escalate-recurrence/SKILL.md` — hook/rule delegation
+  target (Phase 4)
+- `skills/compose-solution/SKILL.md` — cross-artefact delegation (Phase 4
+  fallback)
+- `_primitives/MANIFEST.toml` — primitive catalogue (Phase 2 lookup source)
+- `_primitives/kei-sleep-queue.sh` — primitive install queueing
+- `_blocks/stack-*.md`, `_blocks/deploy-*.md`, `_blocks/ci-*.md` — Phase 2
+  block suggestions per detected stack
+- `_manifests/kei-*.toml` — 12 kit agents (Phase 2 handoff references)
--- a/skills/onboard/phase-1-scan.md
+++ b/skills/onboard/phase-1-scan.md
@ -0,0 +1,116 @@
+# Phase 1 — Intake + Scan
+
+Free-text intake of target paths, then read-only Bash sweep of declarative
+artefacts. Output: one structured summary per project.
+
+## 1a — Ask for the path(s)
+
+Emit a regular message (NOT AskUserQuestion):
+
+> Give me the project path(s) to onboard. Accepts:
+> - single path: `~/Projects/MyApp/`
+> - glob scope:  `~/Projects/keit-*`
+> - list:        `~/Projects/App1/, ~/Projects/App2/`
+>
+> Reply in one line.
+
+Resolve the reply into `PATHS` (one or more absolute paths). Expand `~`.
+Expand the glob via `ls -d <glob> 2>/dev/null`. If zero paths resolve →
+tell the user, ask again. Never fall through.
+
+## 1b — Scope-granularity click (AskUserQuestion, conditional)
+
+Only emit this call if `len(PATHS) > 1`. For a single project, skip to 1c.
+
+```json
+{
+  "questions": [
+    {
+      "question": "Scope granularity for the N projects?",
+      "header": "Scope",
+      "multiSelect": false,
+      "options": [
+        {"label": "Per-project (independent)", "description": "Scan+propose+apply each project separately — different configs per project"},
+        {"label": "Bulk same-config",          "description": "Scan each; propose a SHARED config; apply the same agent/hook set to all matching projects"},
+        {"label": "Mixed",                     "description": "Scan each, propose per-project, but offer a bulk-apply shortcut at confirm-time"}
+      ]
+    }
+  ]
+}
+```
+
+Store as `GRANULARITY`. Default (single path) → `per-project`.
+
+## 1c — Read-only scan (Bash, per project)
+
+For each path in `PATHS`, run a single Bash sweep. Every command must be
+read-only (no mkdir, no touch, no >). Absolute paths only.
+
+```bash
+P="<absolute-project-path>"
+
+# Framework / package manifests
+ls -1 "$P"/package.json "$P"/Cargo.toml "$P"/pyproject.toml \
+      "$P"/pubspec.yaml "$P"/go.mod "$P"/Package.swift \
+      "$P"/requirements.txt 2>/dev/null
+
+# CI
+ls -1 "$P"/.github/workflows/*.yml "$P"/.github/workflows/*.yaml \
+      "$P"/.forgejo/workflows/*.yml "$P"/.gitea/workflows/*.yml \
+      "$P"/.gitlab-ci.yml "$P"/.circleci/config.yml 2>/dev/null
+
+# Deploy
+ls -1 "$P"/docker-compose*.yml "$P"/docker-compose*.yaml \
+      "$P"/Dockerfile "$P"/Dockerfile.* \
+      "$P"/fly.toml "$P"/wrangler.toml "$P"/modal.toml \
+      "$P"/render.yaml "$P"/vercel.json 2>/dev/null
+
+# Tests
+ls -1d "$P"/tests "$P"/test "$P"/__tests__ "$P"/spec 2>/dev/null
+find "$P" -maxdepth 3 -type f \
+     \( -name "*_test.go" -o -name "*.test.ts" -o -name "*.test.tsx" \
+        -o -name "*.test.js" -o -name "*.spec.ts" -o -name "test_*.py" \) \
+     2>/dev/null | head -5
+
+# README (first 100 lines — purpose extraction)
+head -n 100 "$P"/README.md 2>/dev/null
+
+# Recent activity (log ONLY; no writes — git is BLOCKED for state change
+# but read-only log is the only inspection primitive available)
+git -C "$P" log --oneline -20 2>/dev/null
+
+# Env surface — schema files ONLY, never actual secrets
+ls -1 "$P"/.env.example "$P"/.env.template \
+      "$P"/secrets/*.env.example 2>/dev/null
+grep -h '^[A-Z][A-Z0-9_]*=' \
+     "$P"/.env.example "$P"/.env.template 2>/dev/null | \
+     cut -d= -f1 | sort -u
+```
+
+Capture each block of output (even if empty — empty IS a signal).
+
+## 1d — Structured summary per project
+
+Produce a markdown summary per project in the conversation (do NOT write
+to disk). Shape:
+
+```
+## Scan: <project-path>
+Stack:        <package.json → Node/<framework> | Cargo.toml → Rust | pyproject → Python | pubspec → Flutter | go.mod → Go | Package.swift → Swift | NONE_DETECTED>
+CI:           <github-actions | forgejo-actions | gitlab-ci | circleci | NONE>
+Deploy hints: <docker-compose | Dockerfile | fly.io | cloudflare-workers | modal | vercel | NONE>
+Tests:        <tests/ dir | test files found | NONE>
+README:       <first-sentence summary, verbatim quoted>
+Git activity: <N commits in last 20 log lines | NO_GIT>
+Env vars:     <KEY1, KEY2, ... (names only) | NONE>
+```
+
+## Verify-criterion
+
+- `PATHS` is non-empty and every entry resolves to a directory.
+- Per-project summary is present for each path in `PATHS`.
+- No actual secret values appear in the summary — only KEY names.
+- Absent signals are recorded as `NONE` / `NONE_DETECTED`, never invented.
+- If scan surfaces conflicting evidence (e.g. both `package.json` AND
+  `Cargo.toml`), list BOTH in the summary — do not pick one silently;
+  Phase 2 handles disambiguation.
--- a/skills/onboard/phase-2-propose.md
+++ b/skills/onboard/phase-2-propose.md
@ -0,0 +1,154 @@
+# Phase 2 — Propose Candidates
+
+Analyse `SCAN` from Phase 1 and produce `CANDIDATES` — a list of proposed
+agents, hooks, and primitives with confidence scores. Zero AskUserQuestion
+calls in this phase (it's pure analysis; Phase 3 does the mode pick).
+
+## 2a — Candidate kinds
+
+For each project in `PATHS`, emit up to:
+
+- **1 agent** — a project-specialist (maybe 0 if the project is too generic
+  or already has a specialist)
+- **M hooks** — stack-specific enforcement (0-3 typical)
+- **K primitives** — install-queued shell/rust helpers (0-5 typical)
+
+## 2b — Agent proposal (per project)
+
+Compose a dry-run `/new-agent` input based on the scan:
+
+- **Slug**: derive from `basename $PATH` lowercased, kebab-case
+- **Proposed name**: `kei-<slug>-specialist`
+- **Stack block** (from `_blocks/stack-*.md`):
+  - `package.json` + Next.js dep → `stack-nextjs`
+  - `package.json` + React + Vite → `stack-react-vite`
+  - `package.json` + SvelteKit → `stack-sveltekit`
+  - `package.json` + Astro → `stack-astro`
+  - `Cargo.toml` + `[[bin]]` + axum → `stack-rust-axum`
+  - `Cargo.toml` + `[[bin]]` no axum → `stack-rust-cli`
+  - `pyproject.toml` + FastAPI → `stack-fastapi-postgres`
+  - `pyproject.toml` + ML deps (torch/jax) → `stack-python-ml`
+  - `pubspec.yaml` → `stack-flutter`
+  - `go.mod` → `stack-go-server`
+  - `Package.swift` + macOS → `stack-swift-spm`
+  - `Package.swift` + iOS → `stack-swift-ios`
+  - STM32/ESP32 toolchain hint → `stack-embedded-stm32`
+  - None detected → **confidence=speculative**, do not propose stack block
+- **Deploy block**:
+  - `docker-compose*.yml` → `deploy-docker`
+  - `Dockerfile` alone → `deploy-docker`
+  - `wrangler.toml` → `deploy-cloudflare`
+  - `modal.toml` or `Modal` string in code → `deploy-modal`
+  - AWS EC2 hint (README/infra/terraform) → `deploy-aws-ec2`
+  - None detected → skip deploy block
+- **Conditional domain blocks**:
+  - Env vars include `*_API_KEY` / `*_TOKEN` (paid-API names) →
+    `domain-paid-apis`
+  - ML stack detected → `domain-ml-training` + `rule-math-first`
+  - `secrets/*.env.example` present → `domain-has-secrets`
+- **Handoffs** (from kit-12 set, verify each exists via
+  `ls ~/.claude/agents/_manifests/kei-*.toml` or
+  `ls _manifests/kei-*.toml`):
+  - always: `kei-code-implementer`, `kei-critic`, `kei-validator`
+  - paid-APIs → `kei-cost-guardian`
+  - ML → `kei-ml-implementer` + `kei-ml-researcher`
+  - deploy detected → `kei-infra-implementer`
+  - Rust/Swift/Go → `kei-security-auditor`
+
+Confidence rubric (E3-E4 range — scan-derived, never E1):
+
+- **high**: manifest file + dep signature both match (e.g. `Cargo.toml` +
+  `axum = "..."` → `stack-rust-axum` high)
+- **medium**: manifest file matches, no dep signature (e.g. `Cargo.toml`
+  with no crate hint → `stack-rust-cli` medium)
+- **speculative**: only weak signal (README prose, dir name)
+
+## 2c — Hook proposal (per project)
+
+Map scan → hook suggestions:
+
+- Python detected → `no-python-without-approval` bypass hint (confidence
+  high if `pyproject.toml` present; pattern already exists at
+  `~/.claude/hooks/no-python-without-approval.sh`). Propose: "Document the
+  RULE 0.2 exception for this project in its CLAUDE.md; hook stays global."
+- Rust detected → propose `cargo-check-preedit` (pre-edit hook running
+  `cargo check --message-format=short`). If it doesn't exist on disk, it's
+  a CREATE via `/escalate-recurrence`.
+- TypeScript detected (`tsconfig.json` + `.ts` files) → propose
+  `tsc-on-save` equivalent (PostToolUse:Edit running `tsc --noEmit`).
+- Go detected → propose `gofmt-check` PreToolUse:Edit.
+- Flutter detected → propose `flutter-analyze-precommit` hint.
+- CI files present → propose `kei-ci-lint` PostToolUse:Edit (verifies
+  workflow YAML on every edit; primitive `kei-ci-lint.sh` exists).
+
+For each hook candidate:
+
+- Verify the pattern already exists: `ls ~/.claude/hooks/<name>.sh` or the
+  Rust binary under `~/.claude/hooks/_rust/<name>/`.
+- If exists → confidence high, action = "document / enable".
+- If not exists → confidence medium, action = "delegate to
+  `/escalate-recurrence` to author".
+
+## 2d — Primitive proposal (per project)
+
+Read `_primitives/MANIFEST.toml` (already on disk). Map scan → primitives:
+
+- CI detected → `kei-ci-lint` (high confidence)
+- Doc heavy (`docs/`, many `.md`) → `kei-docs-scaffold` (medium)
+- DB migrations (schema files, `migrations/` dir) → `kei-migrate` (high)
+- Frontend + live preview needed → `live-preview`, `design-scrape`,
+  `frontend-inspect`, `screenshot-decode` (bundle as `frontend` profile
+  suggestion)
+- Ops / VPS → `provision-hetzner`, `provision-vultr`, `harden-base` (ops
+  profile suggestion)
+- Non-native docs (.docx/.xlsx/.pptx) in repo → `tomd` (high)
+
+For each primitive candidate:
+
+- Verify it exists in `MANIFEST.toml` via grep.
+- Recommend install mode:
+  - `install.sh --add=<primitive>` (one-off)
+  - `install.sh --profile=<profile>` (if multiple primitives in same
+    profile)
+  - `kei-sleep-queue add` (if the user wants it queued for a later sleep
+    session — useful for big installs)
+
+## 2e — Output structure
+
+Emit a structured summary (display only — no file write):
+
+```
+## Candidates for <project-path>
+
+### Agent (1 proposal)
+- kei-<slug>-specialist  [confidence: high]
+  Blocks: baseline, evidence-grading, memory-protocol, rule-pre-dev-gate,
+          <stack>, <deploy>, <domain-blocks>
+  Handoffs: <list>
+  Rationale: <1-2 lines tied to scan evidence>
+
+### Hooks (M proposals)
+- <hook-name>   [high | medium | speculative]
+  Action: document / enable | delegate to /escalate-recurrence
+  Rationale: <scan evidence>
+
+### Primitives (K proposals)
+- <primitive>   [confidence]
+  Install:  install.sh --add=<primitive>
+  Rationale: <scan evidence>
+```
+
+Store the full list as `CANDIDATES` for Phase 4 consumption.
+
+## Verify-criterion
+
+- Every proposed block name exists under `_blocks/` (ls-verify before
+  citing).
+- Every proposed handoff target exists under `_manifests/kei-*.toml`.
+- Every proposed primitive exists in `_primitives/MANIFEST.toml`.
+- Confidence scores are present on every candidate.
+- No candidate invented from thin air — rationale must cite one or more
+  scan lines from Phase 1.
+- Zero candidates is a valid result — if scan produced nothing actionable,
+  emit an empty list with a note ("scan was inconclusive; recommended
+  action: Phase 3 → pick Full manual to walk `/new-agent` yourself").
--- a/skills/onboard/phase-3-mode-pick.md
+++ b/skills/onboard/phase-3-mode-pick.md
@ -0,0 +1,73 @@
+# Phase 3 — Mode Pick
+
+Single AskUserQuestion. The user picks how much confirm-gating they want on
+the Phase-4 apply step.
+
+## 3a — Mode click (AskUserQuestion, ONE call)
+
+```json
+{
+  "questions": [
+    {
+      "question": "How should Phase 4 apply the proposed candidates?",
+      "header": "Mode",
+      "multiSelect": false,
+      "options": [
+        {"label": "Full auto",     "description": "One approval → apply EVERY candidate (agents via /new-agent auto-flow, hooks via /escalate-recurrence auto-flow, primitives queued). Fastest path."},
+        {"label": "Step-by-step",  "description": "Per-candidate click: apply / skip / modify. Medium friction — good for mixed-confidence batches."},
+        {"label": "Full manual",   "description": "Each candidate fully delegated to /new-agent or /escalate-recurrence with scan-prefilled fields — you walk every wizard phase. Highest control."}
+      ]
+    }
+  ]
+}
+```
+
+Store as `MODE`. Value is one of `full-auto`, `step-by-step`, `full-manual`.
+
+## 3b — Pre-Phase-4 sanity
+
+Before leaving Phase 3, verify:
+
+- `CANDIDATES` is non-empty OR the user explicitly chose `full-manual`
+  (manual mode can start from scratch even if the scan produced nothing).
+- `MODE` is set.
+- If `CANDIDATES` is empty AND mode is `full-auto` or `step-by-step` →
+  re-prompt the user: "Scan found no actionable candidates. Re-run with
+  `full-manual` to walk `/new-agent` from scratch, or abort to adjust the
+  path scope." Offer three constructive paths:
+  (A) Switch to `full-manual` now
+  (B) Re-run Phase 1 with a different path
+  (C) Abort
+
+## 3c — Multi-project note
+
+If `len(PATHS) > 1` AND `GRANULARITY == "bulk-same-config"`:
+
+- The mode applies at the BULK level: one mode decision covers all
+  projects in `PATHS`.
+- The Phase-4 apply loop iterates over `PATHS`, but the per-candidate
+  click-batch is collapsed into one (e.g. "apply this agent to all 3
+  matching projects?").
+
+If `GRANULARITY == "mixed"`:
+
+- Mode applies at per-project level: Phase 4 asks again for mode per
+  project. This means the AskUserQuestion count grows — acceptable, user
+  opted in.
+
+If `GRANULARITY == "per-project"`:
+
+- Mode is asked fresh per project at the TOP of Phase 4's per-project
+  iteration (so each project can pick its own mode). This is NOT a
+  per-project re-emit of Phase 3 — just that Phase 4 re-uses 3a's question
+  text per project.
+
+## Verify-criterion
+
+- `MODE` is exactly one of the three labels.
+- If the user picked a mode that requires at least one candidate, the
+  candidate list is non-empty (or the user was re-prompted).
+- The AskUserQuestion call count for Phase 3 is exactly 1 per mode
+  decision — if multi-project mixed-granularity, it may fire N times
+  total (once per project) across the full skill run, which is explicit
+  and logged in the final report.
--- a/skills/onboard/phase-4-apply.md
+++ b/skills/onboard/phase-4-apply.md
@ -0,0 +1,194 @@
+# Phase 4 — Apply (branches on `MODE`)
+
+Three mode-specific branches. Each ends with `APPLIED` and `SKIPPED` lists
+ready for Phase 5.
+
+## 4-pre — Multi-project bulk shortcut (AskUserQuestion, conditional)
+
+Only emit if `len(PATHS) > 1` AND `GRANULARITY == "mixed"`. This lets the
+user opt into a bulk shortcut mid-apply without rewinding to Phase 1.
+
+```json
+{
+  "questions": [
+    {
+      "question": "Multi-project detected — apply same config to all matching projects?",
+      "header": "Bulk shortcut",
+      "multiSelect": false,
+      "options": [
+        {"label": "Yes — bulk same config",     "description": "Apply one agent/hook/primitive set to every project in PATHS. One decision covers all."},
+        {"label": "No — per-project decisions",  "description": "Keep per-project mode (default): each project gets its own apply loop"},
+        {"label": "Subset — pick projects",      "description": "Pick a subset of PATHS via free-text reply (comma-separated list of basename matches)"}
+      ]
+    }
+  ]
+}
+```
+
+Store as `BULK_MODE`. For single-project runs, skip this call.
+
+## 4a — Full-auto branch (1 confirm total)
+
+### Summary preview
+
+Display a single table:
+
+```
+=== APPLY PREVIEW (full-auto) ===
+Agents to create:    <N> (<name1>, <name2>, ...)
+Hooks to apply:      <M> (<hook1>, <hook2>, ...)
+Primitives to queue: <K> (<p1>, <p2>, ...)
+Target projects:     <path1>, <path2>, ...
+Estimated delegate calls: <N /new-agent + M /escalate-recurrence + K kei-sleep-queue add>
+```
+
+### Single confirm (AskUserQuestion)
+
+```json
+{
+  "questions": [
+    {
+      "question": "Apply all proposed candidates in full-auto?",
+      "header": "Confirm",
+      "multiSelect": false,
+      "options": [
+        {"label": "Yes — apply everything",      "description": "Run all delegations with scan-derived defaults. No further prompts from onboard (downstream wizards may still prompt)."},
+        {"label": "Downgrade to step-by-step",   "description": "Re-enter Phase 4 in step-by-step mode — per-candidate confirm"},
+        {"label": "Abort",                       "description": "Stop — nothing is applied. Proposals remain in chat for your reference."}
+      ]
+    }
+  ]
+}
+```
+
+### Execution (on "Yes — apply everything")
+
+For each agent candidate:
+
+- Invoke Agent tool with `subagent_type: kei-code-implementer`, prompt:
+  "Run the `new-agent` skill wizard non-interactively using these
+  scan-derived fields: stack=<Q1>, deploy=<Q2>, paid-apis=<Q3>, ml=<Q4>,
+  secrets=<Q5>, scrapers=<Q6>, slug=<slug>, description=<1-line>,
+  path=<project-path>, gotchas=<3-5 lines from scan>. Proposed name:
+  `kei-<slug>-specialist`."
+- Record the resulting manifest path + generated `.md` path in `APPLIED`.
+
+For each hook candidate that's CREATE:
+
+- Invoke Agent tool with prompt: "Run the `escalate-recurrence` skill for
+  pattern `<hook-name>`, severity `<suggested>`, event `<suggested>`,
+  triggers `<scan evidence>`."
+- Record the resulting hook path + rule path in `APPLIED`.
+
+For each hook candidate that's "document/enable":
+
+- Append a one-liner to the target project's CLAUDE.md (via
+  `/new-agent` — the wizard handles the bridge). No separate apply step
+  needed.
+
+For each primitive candidate:
+
+- Emit the install command. Two paths:
+  - If primitive install is trivial (shell-only, no deps) → suggest
+    `install.sh --add=<name>` in Phase 5 final report.
+  - If primitive install is heavy (builds Rust, needs env vars) → invoke
+    `kei-sleep-queue add` via Bash:
+    ```bash
+    ~/.claude/agents/_primitives/kei-sleep-queue.sh add \
+       "install-primitive-<name>" \
+       "install.sh --add=<name> from kit repo"
+    ```
+- Record the queue entry or suggested install command in `APPLIED`.
+
+### Verify
+
+- Every delegation returned a success signal (agent path exists on disk;
+  escalate-recurrence reported write completion; sleep-queue returned a
+  UUID).
+- Failed delegations → move the candidate to `SKIPPED` with failure
+  reason. Do NOT retry silently; report in Phase 5.
+
+## 4b — Step-by-step branch (≥N confirms)
+
+Iterate over `CANDIDATES` in order (agents first, then hooks, then
+primitives). For each, emit:
+
+```json
+{
+  "questions": [
+    {
+      "question": "<candidate-kind>: <name> — apply?",
+      "header": "Candidate",
+      "multiSelect": false,
+      "options": [
+        {"label": "Apply",          "description": "Run the delegation with scan-derived defaults (same as full-auto for this one)"},
+        {"label": "Skip",           "description": "Record in SKIPPED list; move to next candidate"},
+        {"label": "Modify (manual)", "description": "Drop into the full /new-agent or /escalate-recurrence wizard for this one candidate — you fill every field"}
+      ]
+    }
+  ]
+}
+```
+
+Branches:
+
+- `Apply` → same execution as 4a for this candidate.
+- `Skip` → append to `SKIPPED` with reason "user-declined-step-by-step".
+- `Modify (manual)` → delegate to the appropriate wizard with scan-derived
+  fields as SUGGESTIONS (user can override each). Agent candidates go to
+  `/new-agent`; hooks/rules go to `/escalate-recurrence`.
+
+### Verify
+
+- Every candidate in `CANDIDATES` received exactly one click.
+- `APPLIED + SKIPPED == CANDIDATES` (no silent drops).
+
+## 4c — Full-manual branch (per-candidate wizard walk)
+
+For EVERY candidate, fully delegate to the appropriate pipeline with
+scan-derived defaults pre-populated but every wizard-phase click surfaced
+to the user:
+
+- **Agent** → invoke `/new-agent` (or Agent tool with `subagent_type:
+  kei-code-implementer`) with prompt: "Run new-agent wizard INTERACTIVELY.
+  Pre-fill from scan: slug=<slug>, path=<project-path>, description=<1-
+  line>. User will click every phase. The 8-phase flow stands unchanged."
+- **Hook/Rule** → invoke `/escalate-recurrence` with prompt: "Run
+  escalate-recurrence INTERACTIVELY. Pre-fill pattern-name, severity
+  suggestion, event suggestion from scan. User clicks every phase."
+- **Primitive** → emit a one-line prompt: "Install `<name>` via
+  `install.sh --add=<name>`? (yes / queue for sleep / skip)" — one
+  AskUserQuestion per primitive:
+
+```json
+{
+  "questions": [
+    {
+      "question": "Primitive: <name> — install mode?",
+      "header": "Primitive",
+      "multiSelect": false,
+      "options": [
+        {"label": "Install now",              "description": "Print install.sh --add=<name> command for user to run"},
+        {"label": "Queue via kei-sleep-queue", "description": "Add to sleep queue — heavy installs run during a sleep session"},
+        {"label": "Skip",                      "description": "No install; record as SKIPPED"}
+      ]
+    }
+  ]
+}
+```
+
+### Verify
+
+- Every candidate walked its full wizard OR was explicitly skipped.
+- Wizard-emitted AskUserQuestion calls are counted in the final AskUser
+  total (they belong to the delegated skill, not to onboard, but onboard
+  reports them for transparency).
+
+## Verify-criterion (Phase 4 overall)
+
+- Exactly one branch ran per project (4a / 4b / 4c).
+- `APPLIED` and `SKIPPED` together cover every entry in `CANDIDATES`.
+- At least one confirm-gate fired (full-auto has 1; step-by-step has ≥N;
+  full-manual has ≥N wizard-internal calls).
+- RULE 0.4: no fabricated delegation paths — if a wizard invocation fails,
+  report the raw failure text, do not invent success.
--- a/skills/onboard/phase-5-report.md
+++ b/skills/onboard/phase-5-report.md
@ -0,0 +1,104 @@
+# Phase 5 — Final Report
+
+Concise summary + suggested next steps. No AskUserQuestion calls — this
+phase is pure output.
+
+## 5a — Summary block
+
+Emit in this exact shape:
+
+```
+=== ONBOARD REPORT ===
+Scope:       <N project(s): path1, path2, ...>
+Granularity: <per-project | bulk-same-config | mixed | n/a>
+Mode:        <full-auto | step-by-step | full-manual>
+
+Scan signals:
+  Stack:     <per-project stack list>
+  CI:        <per-project CI list>
+  Deploy:    <per-project deploy hints>
+  Tests:     <per-project test presence>
+  Env vars:  <names only, per project>
+
+Candidates:
+  Proposed:  <N agents | M hooks | K primitives>
+  Applied:   <N agents | M hooks | K primitives>
+  Skipped:   <count with reasons>
+
+AskUserQuestion count (this skill run):
+  Phase 1:   <0 | 1>    (scope granularity if multi-project)
+  Phase 3:   <1 | N>    (mode pick, possibly per-project)
+  Phase 4:   <varies by mode>
+  Total:     <sum>
+```
+
+## 5b — Suggested next steps
+
+Compose 3-6 one-line bullets conditional on the scan + applied outcome:
+
+- If any agent was applied:
+  ```
+  • Create project memory: touch ~/.claude/memory/<slug>-project.md
+  • Add one line to MEMORY.md: [[<slug>-project]] — <description>
+  ```
+
+- If hooks were applied:
+  ```
+  • Reload Claude Code settings to activate new hooks (restart session)
+  ```
+
+- If primitives were queued via kei-sleep-queue:
+  ```
+  • Next sleep session will install queued primitives — run /sleep-on-it
+    when ready
+  ```
+
+- If primitives were suggested for immediate install:
+  ```
+  • cd <kit-repo> && ./install.sh --add=<p1>,<p2>,<p3>
+  ```
+
+- If DB artefacts detected but no kei-migrate installed:
+  ```
+  • Run install.sh --profile=dev to enable /schema-design and /db-migrate
+    skills (DB workflow detected in <project>)
+  ```
+
+- If frontend detected but no frontend primitives installed:
+  ```
+  • Run install.sh --profile=frontend for live-preview, design-scrape,
+    screenshot-decode, frontend-inspect
+  ```
+
+- If banned-public deploy detected (ML weights / offensive tools):
+  ```
+  • Review security-banned-projects.md — confirm this project's
+    deploy-local-only status is documented before any infra handoff
+  ```
+
+## 5c — Failure surfacing
+
+If any candidate in `SKIPPED` has a failure reason (not user-declined),
+append a "Failures" block:
+
+```
+Failures (constructive paths offered):
+  - <candidate-name>: <failure reason>
+    (A) Retry via /new-agent manually
+    (B) Edit the scan-derived suggestion and re-submit
+    (C) Abandon this candidate
+```
+
+Never close a skill run with a silent failure — RULE -1 (NO DOWNGRADE)
+forbids it. Every failure gets 2-3 constructive paths in the final report.
+
+## Verify-criterion
+
+- Report covers every project in `PATHS`.
+- `Applied + Skipped` totals match `Proposed` totals for each kind
+  (agents, hooks, primitives).
+- AskUserQuestion count is ≥6 across the full skill run (Phase 1 optional
+  1 + Phase 3 at least 1 + Phase 4 at least 4 combined across modes, or
+  downstream wizard AskUser calls counted for full-manual).
+- No fabricated paths — every `APPLIED` entry cites a real manifest/hook/
+  queue-UUID on disk.