Skip to content

feat(skills): deterministic dispatch for every devkit workflow - #71

Merged
5uck1ess merged 2 commits into
mainfrom
feat/deterministic-skill-dispatch
Apr 11, 2026
Merged

feat(skills): deterministic dispatch for every devkit workflow#71
5uck1ess merged 2 commits into
mainfrom
feat/deterministic-skill-dispatch

Conversation

@5uck1ess

Copy link
Copy Markdown
Owner

Summary

Every devkit workflow now has a natural-language trigger skill so keyword-driven invocation is deterministic. Saying "build me a feature", "tri review", "deep research X", "self-lint this", etc., reliably dispatches to the matching workflow via CC's Skill tool → devkit_start → engine. Closes the entry-gate gap where 11/18 workflows had no natural-language path at all.

  • 14 new trigger skills: feature, bugfix, refactor, audit, tri-review, tri-debug, tri-security, tri-dispatch, self-audit, self-improve, self-lint, self-migrate, self-perf, self-test. Each is ~15 lines — keyword-rich frontmatter + a one-line devkit_start body. No duplication of workflow logic.
  • 3 new workflow YAMLstest-gen.yml, doc-gen.yml, onboard.yml — so the existing test-gen, doc-gen, onboard skills have engine-enforced step machines to dispatch to instead of 60–100-line honor-system step content.
  • 3 content skill rewritestest-gen, doc-gen, onboard shrunk to ~14 lines each (thin dispatchers), net −225 lines.
  • Guard fixsrc/cmd/guard.go command+hard and prompt+hard allowlists now include Skill, so a nested "do tri-review" inside an active feature workflow actually loads the trigger skill instead of being silently blocked. Two new pinning test rows.
  • Engine sanity testsrc/engine/new_workflows_test.go walks every workflows/*.yml through ParseFile + Validate so a malformed workflow fails in CI rather than at first devkit_start.
  • Reference hygieneskills/creating-workflows description relabelled REFERENCE ONLY so the matcher can't fire it on natural-language task requests. It's schema docs for writing workflow YAML, not a runnable.
  • Docs — README workflow count 18→21, skill count 22→36, rewrote Skills section with a per-workflow trigger table. ROADMAP updated accordingly.

Why

Before this PR: the devkit engine was 100% deterministic once devkit_start fired, but only 4 of 18 workflows had natural-language triggers (research, deep-research, pr-ready, autoloop). The other 14 could only be fired via slash command or by the agent inferring intent from context — which is probabilistic and routinely drifted. The engine's determinism guarantee stopped at the entry gate.

After this PR: every workflow has a keyword path. The entry gate is ~99% deterministic (skill matching is LLM-decision but descriptions are tight enough that natural phrasing reliably matches). Once devkit_start fires, the existing guard + stop-guard guarantee remains unchanged — step order, no skipping, no early exit. The net effect is end-to-end determinism: you say the keyword, the workflow runs every step.

The honest 1% left: novel phrasings no description anticipates. Recommended fallback is the slash commands (/devkit:tri-review, /devkit:tri-debug, /devkit:tri-security, /devkit:workflow) which bypass the matcher entirely via CC's exact-string resolver.

mega-pr intentionally stays as a skill (not a workflow) because its "steps" are "fire two external skills in parallel" which doesn't fit the engine's step model.

Test plan

  • go test ./... — all 5 packages green including new Skill policy rows
  • go test ./engine/... -run TestParseAllShippedWorkflows — 21/21 workflow YAMLs parse + validate
  • bash hooks/hooks_test.sh — 52/52 pass
  • go vet ./... + gofmt -l — clean
  • CI green across lint / go test / hooks smoke / cross-platform matrix
  • Manual: in a fresh CC window after plugin upgrade, say "build me a feature for red color support" and confirm the feature skill fires and devkit_start feature is called without the user having to type the slash command
  • Manual: verify nested skill dispatch — start a feature workflow, then mid-run say "do tri-review on the diff", confirm the tri-review skill loads (previously blocked by the guard)

Every workflow now has a thin trigger skill so natural-language keyword
invocation deterministically dispatches to the engine. Prior to this,
only 4 of 18 workflows had trigger skills; the rest could only be fired
via slash commands or by the agent inferring intent.

Added (14 trigger skills): feature, bugfix, refactor, audit, tri-review,
tri-debug, tri-security, tri-dispatch, self-audit, self-improve,
self-lint, self-migrate, self-perf, self-test.

Converted 3 content skills to thin triggers backed by new workflow YAMLs:
- test-gen: analyze → generate via test-writer agent → run-fix loop → report
- doc-gen:  analyze → generate via documenter agent → write
- onboard:  analyze → architect via researcher agent → write guide

Guard fix: added Skill to the command+hard and prompt+hard allowlists in
src/cmd/guard.go so a mid-workflow keyword (e.g. "do tri-review" during a
feature run) can load its trigger skill instead of being silently blocked.
Two new policy-matrix test rows pin the contract.

Reference hygiene: skills/creating-workflows frontmatter relabelled
REFERENCE ONLY so CC's matcher cannot fire it on natural-language task
requests — it is schema docs for writing workflow YAML, not a runnable.

Engine sanity test: src/engine/new_workflows_test.go walks workflows/*.yml
through ParseFile + Validate so a malformed YAML (existing or new) fails
in CI rather than at first devkit_start on the user's box.

Verified:
- go test ./... — all packages green, new Skill rows pass
- bash hooks/hooks_test.sh — 52/52 pass
- TestParseAllShippedWorkflows — 21/21 workflow YAMLs parse + validate
- go vet + gofmt — clean
- README: workflow count 18→21 (added test-gen, doc-gen, onboard),
  skill count 22→36, new trigger skill table listing every keyword
  → workflow mapping.
- ROADMAP: skill count 22→36 with full categorization, new bullet
  for deterministic dispatch closing the entry-gate gap.

Runs as part of pr-ready doc-check step before changelog so the doc
changes land in this PR alongside the code.
@5uck1ess
5uck1ess merged commit 33952f8 into main Apr 11, 2026
6 checks passed
@5uck1ess
5uck1ess deleted the feat/deterministic-skill-dispatch branch April 11, 2026 06:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant