feat(skills): deterministic dispatch for every devkit workflow

README.md

@@ -140,7 +140,7 @@ Tasks like "ship this PR" or "submit a PR" auto-activate the `pr-ready` skill 
 
 ### Workflows
 
-All 18 YAML workflows are invoked via the MCP engine. Skills auto-activate for common triggers (e.g., "research X", "fix this bug", "add a feature").
+All 21 YAML workflows are invoked via the MCP engine. Every workflow has a trigger skill so natural-language keywords dispatch deterministically — saying "build a feature", "fix this bug", "tri review", or "deep research X" fires the matching skill, which calls `devkit_start` and the engine takes over.
 
 | Workflow | What it does |
 |---|---|
@@ -162,25 +162,53 @@ All 18 YAML workflows are invoked via the MCP engine. Skills auto-activate for c
 | `tri-debug` | Multi-agent debugging |
 | `tri-security` | Multi-agent security audit |
 | `tri-dispatch` | Send any task to multiple agents |
+| `test-gen` | Generate tests via test-writer agent, iterate until passing |
+| `doc-gen` | Generate docs via documenter agent |
+| `onboard` | Generate codebase onboarding guide via researcher agent |
 
 ---
 
 ## Skills
 
-Skills activate automatically based on context. No slash command needed.
+Skills activate automatically based on context. No slash command needed. Every workflow has a matching trigger skill — saying the keyword dispatches to the engine which then enforces every step.
 
-| Trigger | Skill |
+**Workflow trigger skills** (dispatch to engine-enforced workflows):
+
+| Trigger | Skill → Workflow |
 |---|---|
+| "build a feature", "new feature X" | `feature` |
+| "fix this bug", "this is broken" | `bugfix` |
+| "refactor this", "clean up X" | `refactor` |
+| "audit this project", "project health" | `audit` |
+| "research X" | `research` |
+| "deep research", "validate this" | `deep-research` |
+| "make a PR", "ship this", "create a pull request" | `pr-ready` |
+| "tri review", "triple review" | `tri-review` |
+| "tri debug", "triple debug" | `tri-debug` |
+| "tri security", "triple security audit" | `tri-security` |
+| "tri dispatch", "send to three models" | `tri-dispatch` |
+| "self-audit", "audit the codebase" | `self-audit` |
+| "self-improve", "keep fixing until X passes" | `self-improve` |
+| "self-lint", "fix all lint" | `self-lint` |
+| "self-migrate", "migrate incrementally" | `self-migrate` |
+| "self-perf", "optimize performance" | `self-perf` |
+| "self-test", "fix failing tests" | `self-test` |
+| "autoloop", "run experiments overnight" | `autoloop` |
 | "write tests for X" | `test-gen` |
 | "document this module" | `doc-gen` |
+| "onboard to this codebase" | `onboard` |
+
+**Other skills** (tools, meta-orchestration, content):
+
+| Trigger | Skill |
+|---|---|
 | "generate a changelog" | `changelog` |
-| "explain this codebase" | `onboard` |
-| "research X" | `research` |
-| "deep research", "validate this" | `deep-research` |
+| "create an ADR" | `adr` |
+| "mega PR review" | `mega-pr` (dispatches tri-review + pr-review-toolkit in parallel) |
 | "scrape this URL" | `scrape` |
 | "screenshot this page" | `screenshot` (requires Playwright) |
 | "automate this browser flow" | `browser` (requires Playwright) |
-| "create an ADR" | `adr` |
+| Google Workspace CLI commands | `gcli` |
 
 Coding principles (`clean-code`, `dry`, `yagni`, `dont-reinvent`, `executing`, `stuck`, `scratchpad`) are injected as condensed rules (~120 tokens) per workflow step — not loaded as full skill files.
 
@@ -278,10 +306,10 @@ Terminal usage (devkit workflow <name> "<description>"):
 ```
 devkit/
 ├── commands/          # 6 slash commands (tab-completable entry points)
-├── skills/            # 22 context-activated skills + _principles.yml
+├── skills/            # 36 context-activated skills + _principles.yml
 ├── agents/            # 6 agents (reviewer, researcher, improver, ...)
 ├── hooks/             # 12 hooks (safety, security, quality gates, workflow enforcement)
-├── workflows/         # 18 YAML workflow definitions
+├── workflows/         # 21 YAML workflow definitions
 ├── resources/rules/   # Language-specific coding rules
 ├── src/               # Go engine + MCP server
 │   ├── mcp/           # MCP server (tools, principles loader, session management)

ROADMAP.md

@@ -5,7 +5,8 @@
 - **MCP engine** — Go server exposes `devkit_start`, `devkit_advance`, `devkit_status`, `devkit_list` tools inside Claude Code. Step ordering enforced via MCP tool scoping + PreToolUse hook exit 2. Session state in session.json (hot path, <50ms hook reads) + SQLite (cold history). ~65% token reduction vs old monolithic prompts.
 - **6 slash commands** — Tab-completable entry points for things that need explicit invocation (tri-review, tri-debug, tri-security, status, setup-rules, workflow); 18 former commands now context-activated via skills or invoked via MCP tools (pr-monitor folded into pr-ready workflow; pr-ready is now a natural-language skill)
 - **Deterministic workflow conversion** — All command logic moved from LLM-interpreted markdown to Go-engine-driven YAML workflows; ~3,600 lines of inline logic removed
-- **22 context-activated skills** — 10 auto-trigger workflows (test-gen, doc-gen, changelog, onboard, research, deep-research, scrape, autoloop, adr, pr-ready) + 6 coding principles (executing, clean-code, DRY, YAGNI, dont-reinvent, stuck) + 2 tools (gcli, creating-workflows) + 1 iteration memory (scratchpad) + 1 orchestration (mega-pr) + 2 browser automation (screenshot, browser)
+- **36 context-activated skills** — 21 workflow trigger skills (feature, bugfix, refactor, audit, research, deep-research, pr-ready, autoloop, test-gen, doc-gen, onboard, tri-review, tri-debug, tri-security, tri-dispatch, self-audit, self-improve, self-lint, self-migrate, self-perf, self-test) + 7 coding principles (executing, clean-code, DRY, YAGNI, dont-reinvent, stuck, scratchpad) + 4 tools (gcli, scrape, screenshot, browser) + 1 meta-orchestration (mega-pr) + 2 content (changelog, adr) + 1 reference (creating-workflows)
+- **Deterministic skill dispatch for every workflow** — Every one of the 21 workflows has a natural-language trigger skill with keyword-rich description. Saying "build a feature", "tri review", "deep research X", etc. deterministically invokes the matching skill, which calls `devkit_start` and the engine enforces every step from there. Closes the entry-gate non-determinism where 11/18 workflows previously had no natural-language path. Skill tool added to the guard allowlist so nested mid-workflow skill dispatch works.
 - **6 agents** — Scoped tool access, worktree isolation, model assignment
 - **12 hooks** — Safety (destructive command blocking, edit-time security patterns, PR gate), observability (audit trail, slop detection, post-validation, subagent verification, language-aware code review), optimization (RTK token compression), workflow enforcement (devkit-guard, devkit-stop-guard)
 - **Graceful degradation** — tri:* commands work with 1-3 agents depending on installed CLIs
@@ -14,7 +15,7 @@
 - **Early-exit conditions** — Self-improvement loops stop when goal is met, not just at max iterations
 - **Token budget guidance** — Per-command budget recommendations with model downgrade patterns
 - **RTK token optimization** — Optional PreToolUse hook compresses Bash output via RTK (60-90% savings)
-- **18 YAML workflows** — Portable workflow definitions (feature, bugfix, refactor, research, deep-research, autoloop, self-*, tri-*)
+- **21 YAML workflows** — Portable workflow definitions (feature, bugfix, refactor, research, deep-research, autoloop, self-*, tri-*, test-gen, doc-gen, onboard)
 - **Separate marketplace** — Multi-plugin marketplace at `5uck1ess/marketplace`
 - **Companion ecosystem** — Evaluated official marketplace, documented holistic setup with 7 complementary plugins
 - **Hypothesis-driven perf** — Evidence gathering, ranked hypotheses, one-at-a-time testing replaces blind benchmark loops

skills/audit/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: audit
+description: Audit a project for health — use when asked to audit this project, check project health, run a project audit, look for issues, or assess code/dep/lint/security state. Triggers the deterministic audit workflow (detect ecosystem → deps → lint → security → report).
+---
+
+# Project Audit
+
+Deterministic project health audit. Detect ecosystem → audit deps → lint → security → consolidated report.
+
+## Invoke
+
+Use the `devkit_start` tool with workflow: "audit" and input: "{input}".
+
+Then follow each step the engine returns. Call `devkit_advance` after completing each step. The engine controls step order, gates, and loops. Do NOT skip steps.

skills/bugfix/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: bugfix
+description: Fix a bug end-to-end — use when asked to fix a bug, debug an issue, resolve an error, patch a defect, or "this is broken, fix it". Triggers the deterministic bugfix workflow (triage → reproduce → diagnose → fix → regression test → run tests).
+---
+
+# Bug Fix
+
+Deterministic full-lifecycle bugfix workflow. Triage → reproduce → diagnose → fix → regression-test → run-tests → fix-tests → summary. Includes a fast path for trivial fixes.
+
+## Invoke
+
+Use the `devkit_start` tool with workflow: "bugfix" and input: "{input}".
+
+Then follow each step the engine returns. Call `devkit_advance` after completing each step. The engine controls step order, gates, and loops. Do NOT skip steps.

skills/creating-workflows/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: creating-workflows
-description: How to create devkit workflow YAML files — schema reference, step types, variable interpolation, and examples.
+description: REFERENCE ONLY — schema documentation for authoring devkit workflow YAML files (step types, variable interpolation, loops, parallel groups, examples). NOT a runnable workflow. Load this only when asked to write or modify a workflow YAML, never on natural-language task requests.
 ---
 
 # Writing Workflows

skills/doc-gen/SKILL.md

@@ -1,60 +1,14 @@
 ---
 name: doc-gen
-description: Generate documentation for code — use when asked to document a module, generate API docs, create a README for code, or write reference documentation.
+description: Generate documentation for code — use when asked to document a module, generate API docs, create a README for code, or write reference documentation. Triggers the deterministic doc-gen workflow (analyze → generate via documenter agent → write).
 ---
 
 # Documentation Generation
 
-Analyze code and generate comprehensive documentation.
+Deterministic doc generation. Analyze target → generate via the documenter subagent → write to docs/ or specified path.
 
-## Step 1: Analyze Target
+## Invoke
 
-Read the target files and identify:
-- Public exports, classes, functions, types
-- API surface and interfaces
-- Configuration options
-- Dependencies and relationships
-- Usage patterns from existing code/tests
+Use the `devkit_start` tool with workflow: "doc-gen" and input: "{input}".
 
-## Step 2: Generate Documentation
-
-Spawn the `documenter` agent:
-
-```
-Task: Generate documentation for {target}.
-Agent: documenter
-Context:
-  - Target: {target}
-  - Doc format: {format or "markdown"}
-  - Existing docs: {existing_doc_files}
-  - User instructions: {args}
-```
-
-The documenter should produce:
-1. **Overview** — what the module/package does
-2. **API Reference** — every export with signature, params, return type, description
-3. **Usage Examples** — realistic code snippets
-4. **Configuration** — options and defaults if applicable
-
-## Step 3: Output
-
-Write docs to the appropriate location:
-- If `docs/` directory exists, write there
-- If a specific output path was requested, use that
-- Otherwise, output inline in the conversation
-
-## Presets
-
-```
-/devkit:doc-gen src/api/
-/devkit:doc-gen lib/parser.go --format jsdoc
-/devkit:doc-gen src/ --api-reference-only
-```
-
-## Rules
-
-- Read actual code — don't guess signatures or behavior
-- Include real examples, not placeholder code
-- Match existing doc style if docs already exist
-- Don't generate docs for internal/private code unless asked
-- Keep descriptions concise — one line per param, one paragraph per function
+Then follow each step the engine returns. Call `devkit_advance` after completing each step. The engine controls step order, gates, and loops. Do NOT skip steps.

skills/feature/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: feature
+description: Build a new feature end-to-end — use when asked to add a feature, build X, implement Y, ship a new capability, or "new feature ...". NOT for /feature-dev:feature-dev which is a separate plugin. Triggers the deterministic feature workflow (triage → brainstorm → plan → implement → test → lint → review).
+---
+
+# Feature
+
+Deterministic full-lifecycle feature workflow. Triage → brainstorm → plan → implement → gen-tests → run-tests → lint → review → final-report. Includes a fast path for trivial changes.
+
+## Invoke
+
+Use the `devkit_start` tool with workflow: "feature" and input: "{input}".
+
+Then follow each step the engine returns. Call `devkit_advance` after completing each step. The engine controls step order, gates, and loops. Do NOT skip steps.

skills/onboard/SKILL.md

@@ -1,100 +1,14 @@
 ---
 name: onboard
-description: Generate a codebase onboarding guide — use when asked to explain this codebase, help understand the architecture, give a tour of the repo, or onboard a new contributor.
+description: Generate a codebase onboarding guide — use when asked to explain this codebase, help understand the architecture, give a tour of the repo, or onboard a new contributor. Triggers the deterministic onboard workflow (analyze structure → architect via researcher agent → write guide).
 ---
 
 # Codebase Onboarding
 
-Analyze a codebase and generate an interactive onboarding guide for new contributors.
+Deterministic onboarding guide generation. Analyze structure → architect via the researcher subagent → write guide to `docs/ONBOARDING.md`.
 
-## Step 1: Analyze Structure
+## Invoke
 
-Read and analyze:
-- Directory structure and organization
-- Package manifests (package.json, go.mod, pyproject.toml, Cargo.toml, etc.)
-- Entry points (main files, index files, cmd/ directories)
-- Configuration files
-- CI/CD setup
-- README, CONTRIBUTING, CLAUDE.md if they exist
+Use the `devkit_start` tool with workflow: "onboard" and input: "{input}".
 
-## Step 2: Identify Architecture
-
-Spawn the `researcher` agent:
-
-```
-Task: Analyze the architecture of this codebase.
-Agent: researcher
-Context:
-  - Root directory: {cwd}
-  - Focus areas: entry points, data flow, key abstractions, external dependencies
-```
-
-The researcher should identify:
-1. **Architecture pattern** (monolith, microservices, MVC, etc.)
-2. **Key directories** and what lives in each
-3. **Data flow** — how a request/event moves through the system
-4. **Core abstractions** — the important types, interfaces, classes
-5. **External dependencies** — APIs, databases, services
-6. **Build and deploy** — how to build, test, and deploy
-
-## Step 3: Generate Guide
-
-```
-## Onboarding: {project_name}
-
-### Quick Start
-1. Install dependencies: {install_command}
-2. Run tests: {test_command}
-3. Start dev server: {dev_command}
-
-### Architecture
-{architecture_summary}
-
-### Directory Map
-| Directory | Purpose |
-|-----------|---------|
-| src/api/  | REST API handlers |
-| src/db/   | Database models and migrations |
-| ...       | ... |
-
-### Key Files
-| File | Why it matters |
-|------|---------------|
-| src/server.ts | Entry point — starts HTTP server |
-| src/middleware/auth.ts | Auth middleware — all routes go through this |
-| ... | ... |
-
-### Data Flow
-{request_lifecycle_explanation}
-
-### Patterns & Conventions
-- {pattern_1}
-- {pattern_2}
-
-### Gotchas
-- {gotcha_1}
-- {gotcha_2}
-
-### Common Tasks
-| Task | How |
-|------|-----|
-| Add a new API endpoint | Create handler in src/api/, add route in src/routes.ts |
-| Add a DB migration | ... |
-| Run specific tests | ... |
-```
-
-## Presets
-
-```
-/devkit:onboard
-/devkit:onboard --focus backend
-/devkit:onboard --focus "authentication system"
-```
-
-## Rules
-
-- Read actual code — don't guess from file names alone
-- Focus on what a new contributor needs to be productive
-- Keep it practical — commands, file paths, concrete examples
-- Identify gotchas that aren't obvious from the code
-- Skip boilerplate explanations (don't explain what node_modules is)
+Then follow each step the engine returns. Call `devkit_advance` after completing each step. The engine controls step order, gates, and loops. Do NOT skip steps.

skills/refactor/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: refactor
+description: Refactor code safely — use when asked to refactor, restructure, clean up, reorganize, extract, rename, or modernize a piece of code. Triggers the deterministic refactor workflow (analyze → plan → restructure → verify nothing broke).
+---
+
+# Refactor
+
+Deterministic refactor workflow. Analyze → plan → refactor → run-tests → fix-tests → comparison. Tests are the safety net — the workflow will not exit until they pass.
+
+## Invoke
+
+Use the `devkit_start` tool with workflow: "refactor" and input: "{input}".
+
+Then follow each step the engine returns. Call `devkit_advance` after completing each step. The engine controls step order, gates, and loops. Do NOT skip steps.

skills/self-audit/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: self-audit
+description: Self-audit the codebase — use when asked to self-audit, audit the codebase against its own metrics, run a karpathy-style audit, measure and rank issues by evidence, or "what's wrong with this repo". Triggers the deterministic self-audit workflow (detect → measure quality/security/git → analyze → synthesize).
+---
+
+# Self-Audit
+
+Deterministic codebase audit. Detect ecosystem → measure-quality → measure-security → measure-git (in parallel) → analyze → synthesize actionable plan.
+
+## Invoke
+
+Use the `devkit_start` tool with workflow: "self-audit" and input: "{input}".
+
+Then follow each step the engine returns. Call `devkit_advance` after completing each step. The engine controls step order, gates, and loops. Do NOT skip steps.

skills/self-improve/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: self-improve
+description: Metric-gated improvement loop — use when asked to self-improve, run an improvement loop, fix issues until a metric passes, or "keep fixing until X is green". Triggers the deterministic self-improve workflow (baseline → improve → verify → loop until passing).
+---
+
+# Self-Improve
+
+Deterministic metric-gated improvement loop. Baseline → improve → verify → loop until the gate passes → summary.
+
+## Invoke
+
+Use the `devkit_start` tool with workflow: "self-improve" and input: "{input}".
+
+Then follow each step the engine returns. Call `devkit_advance` after completing each step. The engine controls step order, gates, and loops. Do NOT skip steps.

skills/self-lint/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: self-lint
+description: Run linter and fix violations until clean — use when asked to self-lint, lint and fix, fix lint errors, "make lint pass", or "fix all the lint issues". Triggers the deterministic self-lint workflow (baseline → fix → verify → loop until clean).
+---
+
+# Self-Lint
+
+Deterministic lint-and-fix loop. Baseline lint → fix violations → verify → loop until clean → summary.
+
+## Invoke
+
+Use the `devkit_start` tool with workflow: "self-lint" and input: "{input}".
+
+Then follow each step the engine returns. Call `devkit_advance` after completing each step. The engine controls step order, gates, and loops. Do NOT skip steps.