From 293e96af5d41e38a82e36a4c5c1b1b7de849136f Mon Sep 17 00:00:00 2001 From: Parfii-bot Date: Wed, 22 Apr 2026 04:22:20 +0800 Subject: [PATCH] feat(skills): /onboard auto-project-analyze with 3-mode apply (full-auto/step-by-step/full-manual) --- skills/onboard/SKILL.md | 132 +++++++++++++++++++ skills/onboard/phase-1-scan.md | 116 +++++++++++++++++ skills/onboard/phase-2-propose.md | 154 ++++++++++++++++++++++ skills/onboard/phase-3-mode-pick.md | 73 +++++++++++ skills/onboard/phase-4-apply.md | 194 ++++++++++++++++++++++++++++ skills/onboard/phase-5-report.md | 104 +++++++++++++++ 6 files changed, 773 insertions(+) create mode 100644 skills/onboard/SKILL.md create mode 100644 skills/onboard/phase-1-scan.md create mode 100644 skills/onboard/phase-2-propose.md create mode 100644 skills/onboard/phase-3-mode-pick.md create mode 100644 skills/onboard/phase-4-apply.md create mode 100644 skills/onboard/phase-5-report.md diff --git a/skills/onboard/SKILL.md b/skills/onboard/SKILL.md new file mode 100644 index 0000000..4e8ad5d --- /dev/null +++ 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: +--- + +# 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: +Proposed: +Mode: +Applied: +Skipped: +Next: +``` + +--- + +## 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) diff --git a/skills/onboard/phase-1-scan.md b/skills/onboard/phase-1-scan.md new file mode 100644 index 0000000..f5f2113 --- /dev/null +++ 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 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="" + +# 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: +Stack: | Cargo.toml → Rust | pyproject → Python | pubspec → Flutter | go.mod → Go | Package.swift → Swift | NONE_DETECTED> +CI: +Deploy hints: +Tests: +README: +Git activity: +Env vars: +``` + +## 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. diff --git a/skills/onboard/phase-2-propose.md b/skills/onboard/phase-2-propose.md new file mode 100644 index 0000000..3cad134 --- /dev/null +++ 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--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/.sh` or the + Rust binary under `~/.claude/hooks/_rust//`. +- 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=` (one-off) + - `install.sh --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 + +### Agent (1 proposal) +- kei--specialist [confidence: high] + Blocks: baseline, evidence-grading, memory-protocol, rule-pre-dev-gate, + , , + Handoffs: + Rationale: <1-2 lines tied to scan evidence> + +### Hooks (M proposals) +- [high | medium | speculative] + Action: document / enable | delegate to /escalate-recurrence + Rationale: + +### Primitives (K proposals) +- [confidence] + Install: install.sh --add= + Rationale: +``` + +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"). diff --git a/skills/onboard/phase-3-mode-pick.md b/skills/onboard/phase-3-mode-pick.md new file mode 100644 index 0000000..4782a40 --- /dev/null +++ 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. diff --git a/skills/onboard/phase-4-apply.md b/skills/onboard/phase-4-apply.md new file mode 100644 index 0000000..f8f2f24 --- /dev/null +++ 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: (, , ...) +Hooks to apply: (, , ...) +Primitives to queue: (, , ...) +Target projects: , , ... +Estimated delegate calls: +``` + +### 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=, deploy=, paid-apis=, ml=, + secrets=, scrapers=, slug=, description=<1-line>, + path=, gotchas=<3-5 lines from scan>. Proposed name: + `kei--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 ``, severity ``, event ``, + triggers ``." +- 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=` 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-" \ + "install.sh --add= 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": ": — 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=, 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 `` via + `install.sh --add=`? (yes / queue for sleep / skip)" — one + AskUserQuestion per primitive: + +```json +{ + "questions": [ + { + "question": "Primitive: — install mode?", + "header": "Primitive", + "multiSelect": false, + "options": [ + {"label": "Install now", "description": "Print install.sh --add= 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. diff --git a/skills/onboard/phase-5-report.md b/skills/onboard/phase-5-report.md new file mode 100644 index 0000000..c9db043 --- /dev/null +++ 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: +Granularity: +Mode: + +Scan signals: + Stack: + CI: + Deploy: + Tests: + Env vars: + +Candidates: + Proposed: + Applied: + Skipped: + +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: + Total: +``` + +## 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/-project.md + • Add one line to MEMORY.md: [[-project]] — + ``` + +- 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 && ./install.sh --add=,, + ``` + +- 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 ) + ``` + +- 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): + - : + (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.