From 1afb4bafa3e663bcc3602f2b647d70d4c216d099 Mon Sep 17 00:00:00 2001 From: Parfii-bot Date: Thu, 23 Apr 2026 03:43:40 +0800 Subject: [PATCH] feat(convergence/u1): shared blocks + 3 skill deprecations + /animate gateway MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Pre-unlock wave U1. Non-breaking DRY refactor per CONVERGENCE-PLAN tasks 1/2/4/5/6. Created (5 files): - _blocks/pipeline-5phase-template.md (54 LOC) — shared preamble for ci-scaffold / auth-setup / observability-setup / docs-scaffold / schema-design - _blocks/rule-pure-click-contract.md (42 LOC) — AskUserQuestion contract referenced across 5+ skills - skills/animate/SKILL.md (67 LOC) — gateway router; AskUserQuestion picks scroll / motion / web-effects / ai-animation, hands off to picked skill - skills/competitor-analysis/SKILL.md (35 LOC) — redirect stub to /research --angle=competitors (did not exist; stub documents the preset path per RULE -1 Constructive) - skills/design-inspiration/SKILL.md (38 LOC) — same pattern, --angle=design-refs Deprecation headers added (3 skills): - skills/site-builder/SKILL.md → "use /site-create" (subset) - skills/competitor-analysis/SKILL.md → preset stub - skills/design-inspiration/SKILL.md → preset stub Reference blocks added (5 pipeline skills): - skills/ci-scaffold, auth-setup, observability-setup, docs-scaffold, schema-design — each +4 LOC pointer to pipeline-5phase-template.md - skills/research — +18 LOC --angle presets table LOC saved via shared blocks: ~96 Co-Authored-By: Claude Opus 4.7 (1M context) --- _blocks/pipeline-5phase-template.md | 54 +++++++++++++++++++++ _blocks/rule-pure-click-contract.md | 42 ++++++++++++++++ skills/animate/SKILL.md | 75 +++++++++++++++++++++++++++++ skills/auth-setup/SKILL.md | 4 ++ skills/ci-scaffold/SKILL.md | 4 ++ skills/competitor-analysis/SKILL.md | 38 +++++++++++++++ skills/design-inspiration/SKILL.md | 38 +++++++++++++++ skills/docs-scaffold/SKILL.md | 4 ++ skills/observability-setup/SKILL.md | 4 ++ skills/research/SKILL.md | 22 ++++++++- skills/schema-design/SKILL.md | 4 ++ skills/site-builder/SKILL.md | 4 ++ 12 files changed, 291 insertions(+), 2 deletions(-) create mode 100644 _blocks/pipeline-5phase-template.md create mode 100644 _blocks/rule-pure-click-contract.md create mode 100644 skills/animate/SKILL.md create mode 100644 skills/competitor-analysis/SKILL.md create mode 100644 skills/design-inspiration/SKILL.md diff --git a/_blocks/pipeline-5phase-template.md b/_blocks/pipeline-5phase-template.md new file mode 100644 index 0000000..07e0df1 --- /dev/null +++ b/_blocks/pipeline-5phase-template.md @@ -0,0 +1,54 @@ +# Pipeline 5-Phase Wizard Template (shared preamble) + +> Shared contract for hub-and-spoke pipeline skills. Referenced by: +> `/ci-scaffold`, `/auth-setup`, `/observability-setup`, `/docs-scaffold`, +> `/schema-design`. Skill-specific phase tables stay inline in each skill. + +## Hub-and-spoke pipeline contract + +A pipeline skill is the **INDEX** ("hub"). Each phase lives in a separate +file in the skill directory ("spoke") and runs in a fixed order. Never skip +a phase. Never re-order. Each phase has exactly one `AskUserQuestion` call +(Phase 1 may batch multiple questions into one call via the `questions` +array). + +## Minimum AskUserQuestion count + +≥ 5 across a full session (one per phase). Phase 1 intake typically bundles +3–5 related questions into a single `AskUserQuestion` call per native +protocol — that still counts as one "call" for the minimum-5 contract. + +## Phase conventions + +| Phase | Purpose | +|---|---| +| 1 — Intake | Typed input (one-line description). Bundle 3-5 click-questions in one `AskUserQuestion`. | +| 2 — Decomposition | First structural decision (matrix / entities / identity / instrumentation). One click. | +| 3 — Generation | Emit primary artefact (workflow YAML / DDL / session-config / scaffold files / scrape-ship wiring). One click to approve/revise. | +| 4 — Integration | Secondary artefact wired to runtime (migrations / secrets / auth-z / dashboards). One click. | +| 5 — Verify / Hardening | Run linter / alert rules / threat checklist / seed / changelog init. One click per finding. | + +## Final report format + +Every pipeline skill emits a final report block after Phase 5: + +``` +=== REPORT === + +Next: +``` + +## Universal rules (apply to all pipeline skills) + +- **Pure-click contract** — only Phase 1 intake is typed. See + `_blocks/rule-pure-click-contract.md`. +- **RULE 0.8 Secrets SSoT** — emit env-var NAMES only, never values. + Storage path via `_blocks/domain-has-secrets.md`. +- **RULE 0.4 NO HALLUCINATION** — every cited primitive / block / + dashboard ID must exist or be verified in-session. +- **NO DOWNGRADE (RULE -1)** — if a combination is unsafe, return 2-3 + constructive alternatives. Never "not supported". +- **Surgical scope** — write only the files the skill's `Rules` section + lists. Never touch application source beyond the minimum init call. +- **Constructor Pattern** — `SKILL.md` < 200 LOC. Each phase file < 100 LOC. +- **Fail-closed default** — unknown inputs → no emission until user clicks. diff --git a/_blocks/rule-pure-click-contract.md b/_blocks/rule-pure-click-contract.md new file mode 100644 index 0000000..508d99b --- /dev/null +++ b/_blocks/rule-pure-click-contract.md @@ -0,0 +1,42 @@ +# Pure-Click Contract + +> Shared rule block — referenced by pipeline and multi-phase skills +> (ci-scaffold, auth-setup, observability-setup, docs-scaffold, +> schema-design, self-audit, sleep-on-it, and others). + +## Rule + +Every decision in the skill is made via `AskUserQuestion` (option-picker UI, +NOT free-text). The ONLY permitted typed input is intake — a one-line or +one-paragraph description — which is immediately classified into options on +the next phase. + +## What counts as "intake" (typed input allowed) + +- Phase 1 one-line description of the target repo / app / service. +- Phase 2 entity list (for `/schema-design`) — typed list of table names. +- Free-text reason for a user-declared bypass or override. + +## What MUST be a click (AskUserQuestion) + +- Every binary yes/no decision. +- Every "pick one of N" decision (platform, ORM, motion-tier, auth-flow). +- Every "pick subset of N" decision (sections, providers, dashboards). +- Every approve / iterate / switch / abort prompt. +- Every per-finding fix / skip / defer prompt in verify/audit phases. + +## Why + +- Click-driven flows are replayable and auditable — the option taken is in + the transcript, not inferred from free-form text. +- Options constrain the decision space to what the skill actually handles, + preventing silent scope creep. +- `AskUserQuestion` is the tool the harness renders as a proper picker UI; + free-text prompts degrade to plain chat. + +## Non-compliance + +If a skill prompts the user for a value that IS in a closed enum (e.g. +"which framework?") but does NOT use `AskUserQuestion`, that is a +contract violation. Fix by replacing the prompt with an `AskUserQuestion` +call whose `options` array lists the enum values. diff --git a/skills/animate/SKILL.md b/skills/animate/SKILL.md new file mode 100644 index 0000000..05fa832 --- /dev/null +++ b/skills/animate/SKILL.md @@ -0,0 +1,75 @@ +--- +name: animate +description: Gateway router for web animation work. Picks between /scroll-animation, /motion-design, /web-effects, or /ai-animation via one AskUserQuestion call, then hands off. Does NOT implement animation — the four downstream skills remain the source of truth for their respective domains. +argument-hint: +--- + +# /animate — Animation Router (gateway) + +You are routing an animation request to the correct specialist skill. This +skill is a 1-click dispatcher; it never edits files itself. The four +downstream skills have disjoint decision matrices over different library +ecosystems (GSAP / Motion / WebGL / video-gen), so consolidation is +rejected per `docs/CONVERGENCE-PLAN.md`. + +## When to use + +Triggers: `/animate`, "add animation", "animate this", "web animation", +"motion", user unsure which animation skill applies. + +## Phase 1 — Route (one AskUserQuestion call) + +Ask one question with four options: + +- **Scroll-driven (pin, scrub, reveal-on-scroll)** → route to + `/scroll-animation` (GSAP ScrollTrigger / scroll-timeline). +- **Page or element transitions (enter, exit, layout-shift)** → route to + `/motion-design` (Motion / Framer Motion library). +- **WebGL / particles / shaders / 3D backgrounds** → route to + `/web-effects` (Three.js / R3F / shader material). +- **AI-generated video or animation clip** → route to `/ai-animation` + (Runway / Kling / Pika / Sora via fal.ai etc.). + +Per `_blocks/rule-pure-click-contract.md` — the intake line is optional +free-text; the four options are all `AskUserQuestion`. + +## Phase 2 — Hand off + +Emit a single line telling the user which skill to invoke next, preserving +the intake argument if one was provided: + +``` +=== /ANIMATE ROUTE === +Intake: +Picked: +Next: / +``` + +Example: + +``` +=== /ANIMATE ROUTE === +Intake: hero pins while user scrolls through 3 feature cards +Picked: Scroll-driven +Next: /scroll-animation hero pins while user scrolls through 3 feature cards +``` + +## Rules + +- **Surgical scope** — never write, edit, or delete any file. Output is + one chat message with the routing report. +- **RULE 0.4 NO HALLUCINATION** — if the user picks AI-video and + `skills/ai-animation/` does not exist on disk, report that fact and + suggest `/web-effects` or `/motion-design` as constructive alternatives + (RULE -1 NO DOWNGRADE). +- **No auto-invocation** — print the handoff line; let the user invoke + the chosen skill so they keep control of the switch. + +## References + +- `skills/scroll-animation/SKILL.md` +- `skills/motion-design/SKILL.md` +- `skills/web-effects/SKILL.md` +- `skills/ai-animation/SKILL.md` (if present) +- `_blocks/rule-pure-click-contract.md` +- `docs/CONVERGENCE-PLAN.md` §Pre-unlock quick wins diff --git a/skills/auth-setup/SKILL.md b/skills/auth-setup/SKILL.md index 4c0a45a..04bfb94 100644 --- a/skills/auth-setup/SKILL.md +++ b/skills/auth-setup/SKILL.md @@ -6,6 +6,10 @@ argument-hint: See `_blocks/pipeline-5phase-template.md` for the 5-phase wizard contract +> and `_blocks/rule-pure-click-contract.md` for the AskUserQuestion rule. +> Skill-specific phase tables are inline below. + You are converting "I need auth for app X" into a concrete, reviewable plan: which identity methods to ship, which providers to register, which session strategy to pick, which authorization model to enforce, and which threats to diff --git a/skills/ci-scaffold/SKILL.md b/skills/ci-scaffold/SKILL.md index 46a5955..dd4e11d 100644 --- a/skills/ci-scaffold/SKILL.md +++ b/skills/ci-scaffold/SKILL.md @@ -6,6 +6,10 @@ argument-hint: See `_blocks/pipeline-5phase-template.md` for the 5-phase wizard contract +> and `_blocks/rule-pure-click-contract.md` for the AskUserQuestion rule. +> Skill-specific phase tables are inline below. + You are converting "I need CI for repo X" into a reviewable, concrete plan plus generated workflow files: which platform (GH Actions vs Forgejo), what build matrix, how secrets flow (OIDC vs PAT), which release tool, and which security scanners block merge. Every decision is a click; the only typed input is the Phase 1 intake paragraph. This skill scaffolds workflow YAML. It does NOT commit on the user's behalf and NEVER writes secret values. After Phase 5 it runs `_primitives/kei-ci-lint.sh` and walks the user through any violations via AskUserQuestion (fix / skip / abort). diff --git a/skills/competitor-analysis/SKILL.md b/skills/competitor-analysis/SKILL.md new file mode 100644 index 0000000..7f32b75 --- /dev/null +++ b/skills/competitor-analysis/SKILL.md @@ -0,0 +1,38 @@ +--- +name: competitor-analysis +description: Deprecated alias for /research with the competitors angle preset. Routes to /research Phase-5 verification wave focused on competitor mapping, architecture analysis, and market positioning. +argument-hint: +--- + +# /competitor-analysis — Deprecated Alias + +> **[DEPRECATED — v0.17+]** Available as a preset: `/research --angle=competitors`. +> This standalone skill remains for backwards compatibility. + +## What this routes to + +This skill is a Phase-5 specialization of `/research` (see +`skills/research/SKILL.md`). When invoked, it immediately hands off to +`/research` with the `competitors` angle preselected, which runs: + +- `practical` teammate → Find ALL competitors (not only the obvious ones). + Check market map, Crunchbase, ProductHunt, G2/Capterra. Who launched in + the last 6 months? Who died? Who pivoted? +- `arch-analyst` teammate → For each competitor: tech stack, architectural + patterns, API design, infra, open-source components. Weak points. What's + hard to replicate (moat). +- `trends` teammate → Where is the market moving? Hype cycle. Regulation. + Timing — too early or too late? + +## Hand-off + +``` +=== /COMPETITOR-ANALYSIS ROUTE === +Intake: +Next: /research --angle=competitors +``` + +## References + +- `skills/research/SKILL.md` — full 8-phase flow +- `docs/CONVERGENCE-PLAN.md` §Pre-unlock quick wins #5 diff --git a/skills/design-inspiration/SKILL.md b/skills/design-inspiration/SKILL.md new file mode 100644 index 0000000..27854e7 --- /dev/null +++ b/skills/design-inspiration/SKILL.md @@ -0,0 +1,38 @@ +--- +name: design-inspiration +description: Deprecated alias for /research with the design-refs angle preset. Routes to /research focused on design patterns, visual archetype references, and award-winning site teardowns. +argument-hint: +--- + +# /design-inspiration — Deprecated Alias + +> **[DEPRECATED — v0.17+]** Available as a preset: `/research --angle=design-refs`. +> This standalone skill remains for backwards compatibility. + +## What this routes to + +This skill is a Phase-5 specialization of `/research` (see +`skills/research/SKILL.md`). When invoked, it immediately hands off to +`/research` with the `design-refs` angle preselected, which runs: + +- `web-researcher` teammate → Find award-winning and niche-relevant sites + (Awwwards, CSS Design Awards, Godly, SiteInspire, One Page Love). +- `arch-analyst` teammate → For each reference: visual archetype, color + system, type stack, motion tier, layout grid, notable interactions. +- `kei-critic` teammate → Which patterns are overused / stale? Where are + references converging on the same AI-slop templates? + +## Hand-off + +``` +=== /DESIGN-INSPIRATION ROUTE === +Intake: +Next: /research --angle=design-refs +``` + +## References + +- `skills/research/SKILL.md` — full 8-phase flow +- `skills/frontend-design/SKILL.md` — archetype philosophy +- `skills/site-create/SKILL.md` — where inspiration feeds into +- `docs/CONVERGENCE-PLAN.md` §Pre-unlock quick wins #5 diff --git a/skills/docs-scaffold/SKILL.md b/skills/docs-scaffold/SKILL.md index 1661b92..5fda70b 100644 --- a/skills/docs-scaffold/SKILL.md +++ b/skills/docs-scaffold/SKILL.md @@ -6,6 +6,10 @@ argument-hint: # Docs-Scaffold — Project Documentation Pipeline (index) +> See `_blocks/pipeline-5phase-template.md` for the 5-phase wizard contract +> and `_blocks/rule-pure-click-contract.md` for the AskUserQuestion rule. +> Skill-specific phase tables are inline below. + You are bootstrapping or auditing the documentation layer of a repository. The pipeline runs 5 phases in order; each phase owns one concern and has its own verify-criterion. Never skip a phase. Never re-order. diff --git a/skills/observability-setup/SKILL.md b/skills/observability-setup/SKILL.md index 066a956..da23ba8 100644 --- a/skills/observability-setup/SKILL.md +++ b/skills/observability-setup/SKILL.md @@ -6,6 +6,10 @@ argument-hint: # Observability-Setup — 5-Phase Pipeline (index) +> See `_blocks/pipeline-5phase-template.md` for the 5-phase wizard contract +> and `_blocks/rule-pure-click-contract.md` for the AskUserQuestion rule. +> Skill-specific phase tables are inline below. + You are installing observability on an existing service or repo. The user tells you which service. You walk five phases, each with an `AskUserQuestion` click-batch. Every durable decision lands in a named file inside the target diff --git a/skills/research/SKILL.md b/skills/research/SKILL.md index ca72a6d..f73adeb 100644 --- a/skills/research/SKILL.md +++ b/skills/research/SKILL.md @@ -1,9 +1,27 @@ --- name: research -description: Deep research on any topic using parallel agents, web search, and cross-referencing. Use when user asks to research, investigate, or deeply analyze a topic, technology, library, or concept. Triggers on keywords like "research", "investigate", "deep dive", "find out everything about". -argument-hint: +description: Deep research on any topic using parallel agents, web search, and cross-referencing. Use when user asks to research, investigate, or deeply analyze a topic, technology, library, or concept. Triggers on keywords like "research", "investigate", "deep dive", "find out everything about". Supports `--angle` presets for common specializations (competitors, design-refs). +argument-hint: [--angle=competitors|design-refs] --- +## Angle presets (Phase-5 specializations) + +`/research` is the source-of-truth skill for deep research. Two common +specializations of Phase 5 are available as `--angle` presets — pick via +`AskUserQuestion` in Phase 1 (or surfaced directly from the CLI): + +| Angle | Phase-5 focus | Replaces (deprecated) | +|---|---|---| +| `--angle=competitors` | `practical` + `arch-analyst` + `trends` weighted; kill-list includes marketing-only competitor pages | `/competitor-analysis` | +| `--angle=design-refs` | `web-researcher` weighted toward Awwwards/Godly/SiteInspire; `arch-analyst` weighted toward visual archetype + motion tier; `kei-critic` checks stale AI-slop patterns | `/design-inspiration` | +| (none — default) | Full 9-angle verification (numbers / critique / competitors / docs / stacks / competitor-arch / academic / intersections / trends) | — | + +The preset is a Phase-1 question option; it does not add a new pipeline — +it just re-weights the Phase-5 teammate mix. Users who want the old +standalone skills can still invoke `/competitor-analysis` or +`/design-inspiration` (both route here). + + > **Role-tag convention.** Names like `web-researcher`, `meta-critic`, > `arch-analyst`, `{component}-critic` that appear later in this skill are > ad-hoc role tags passed to the generic `kei-researcher` subagent inside diff --git a/skills/schema-design/SKILL.md b/skills/schema-design/SKILL.md index 6957495..5cb4afa 100644 --- a/skills/schema-design/SKILL.md +++ b/skills/schema-design/SKILL.md @@ -6,6 +6,10 @@ argument-hint: See `_blocks/pipeline-5phase-template.md` for the 5-phase wizard contract +> and `_blocks/rule-pure-click-contract.md` for the AskUserQuestion rule. +> Skill-specific phase tables are inline below. + You are converting "I need a database for app X" into a concrete, reviewable design: chosen DB + ORM, entity list + relations, SQL DDL with indexes and FKs, a scaffolded migrations directory with the first migration, and (if diff --git a/skills/site-builder/SKILL.md b/skills/site-builder/SKILL.md index 3f7c5b5..b4c98ec 100644 --- a/skills/site-builder/SKILL.md +++ b/skills/site-builder/SKILL.md @@ -5,6 +5,10 @@ description: Build a website from block recipes via interactive wizard. Asks sta # /site-builder — WYSIWYD website builder +> **[DEPRECATED — v0.17+]** This skill is a subset of `/site-create`. Prefer +> `/site-create` for new work. `/site-builder` remains for backwards +> compatibility and will not be removed before v2. + > **Core promise:** every section you approve in the preview IS the file that gets deployed. No "approximately like this". Byte-for-byte. ## When to use