From 6a591a7cd41cf578d5f9b0ebb11d06f7c56a9c2e Mon Sep 17 00:00:00 2001 From: Tym Rabchuk Date: Sat, 11 Apr 2026 02:01:44 -0400 Subject: [PATCH 1/2] feat(skills): deterministic dispatch for every devkit workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- skills/audit/SKILL.md | 14 +++++ skills/bugfix/SKILL.md | 14 +++++ skills/creating-workflows/SKILL.md | 2 +- skills/doc-gen/SKILL.md | 56 ++--------------- skills/feature/SKILL.md | 14 +++++ skills/onboard/SKILL.md | 96 ++---------------------------- skills/refactor/SKILL.md | 14 +++++ skills/self-audit/SKILL.md | 14 +++++ skills/self-improve/SKILL.md | 14 +++++ skills/self-lint/SKILL.md | 14 +++++ skills/self-migrate/SKILL.md | 14 +++++ skills/self-perf/SKILL.md | 14 +++++ skills/self-test/SKILL.md | 14 +++++ skills/test-gen/SKILL.md | 81 ++----------------------- skills/tri-debug/SKILL.md | 14 +++++ skills/tri-dispatch/SKILL.md | 14 +++++ skills/tri-review/SKILL.md | 14 +++++ skills/tri-security/SKILL.md | 14 +++++ src/cmd/guard.go | 18 ++++-- src/cmd/guard_test.go | 27 +++++++++ src/engine/new_workflows_test.go | 36 +++++++++++ workflows/doc-gen.yml | 54 +++++++++++++++++ workflows/onboard.yml | 91 ++++++++++++++++++++++++++++ workflows/test-gen.yml | 69 +++++++++++++++++++++ 24 files changed, 501 insertions(+), 225 deletions(-) create mode 100644 skills/audit/SKILL.md create mode 100644 skills/bugfix/SKILL.md create mode 100644 skills/feature/SKILL.md create mode 100644 skills/refactor/SKILL.md create mode 100644 skills/self-audit/SKILL.md create mode 100644 skills/self-improve/SKILL.md create mode 100644 skills/self-lint/SKILL.md create mode 100644 skills/self-migrate/SKILL.md create mode 100644 skills/self-perf/SKILL.md create mode 100644 skills/self-test/SKILL.md create mode 100644 skills/tri-debug/SKILL.md create mode 100644 skills/tri-dispatch/SKILL.md create mode 100644 skills/tri-review/SKILL.md create mode 100644 skills/tri-security/SKILL.md create mode 100644 src/engine/new_workflows_test.go create mode 100644 workflows/doc-gen.yml create mode 100644 workflows/onboard.yml create mode 100644 workflows/test-gen.yml diff --git a/skills/audit/SKILL.md b/skills/audit/SKILL.md new file mode 100644 index 0000000..f7faf72 --- /dev/null +++ b/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. diff --git a/skills/bugfix/SKILL.md b/skills/bugfix/SKILL.md new file mode 100644 index 0000000..c4697bc --- /dev/null +++ b/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. diff --git a/skills/creating-workflows/SKILL.md b/skills/creating-workflows/SKILL.md index 824a4d9..24656ea 100644 --- a/skills/creating-workflows/SKILL.md +++ b/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 diff --git a/skills/doc-gen/SKILL.md b/skills/doc-gen/SKILL.md index 215f27b..b23decd 100644 --- a/skills/doc-gen/SKILL.md +++ b/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. diff --git a/skills/feature/SKILL.md b/skills/feature/SKILL.md new file mode 100644 index 0000000..46016f2 --- /dev/null +++ b/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. diff --git a/skills/onboard/SKILL.md b/skills/onboard/SKILL.md index 8bcb137..896c049 100644 --- a/skills/onboard/SKILL.md +++ b/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. diff --git a/skills/refactor/SKILL.md b/skills/refactor/SKILL.md new file mode 100644 index 0000000..0b86360 --- /dev/null +++ b/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. diff --git a/skills/self-audit/SKILL.md b/skills/self-audit/SKILL.md new file mode 100644 index 0000000..470252f --- /dev/null +++ b/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. diff --git a/skills/self-improve/SKILL.md b/skills/self-improve/SKILL.md new file mode 100644 index 0000000..dfdb337 --- /dev/null +++ b/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. diff --git a/skills/self-lint/SKILL.md b/skills/self-lint/SKILL.md new file mode 100644 index 0000000..abd78fa --- /dev/null +++ b/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. diff --git a/skills/self-migrate/SKILL.md b/skills/self-migrate/SKILL.md new file mode 100644 index 0000000..fde6f4f --- /dev/null +++ b/skills/self-migrate/SKILL.md @@ -0,0 +1,14 @@ +--- +name: self-migrate +description: Incremental migration loop — use when asked to migrate, port, upgrade, convert, or modernize a codebase incrementally with tests as a safety gate. Triggers the deterministic self-migrate workflow (baseline → migrate one piece → verify → loop). +--- + +# Self-Migrate + +Deterministic incremental migration loop. Baseline → migrate one piece → verify with tests → loop until done → summary. Tests are the safety gate at every step. + +## Invoke + +Use the `devkit_start` tool with workflow: "self-migrate" 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. diff --git a/skills/self-perf/SKILL.md b/skills/self-perf/SKILL.md new file mode 100644 index 0000000..d013708 --- /dev/null +++ b/skills/self-perf/SKILL.md @@ -0,0 +1,14 @@ +--- +name: self-perf +description: Profile and optimize performance — use when asked to self-perf, optimize performance, profile hot paths, speed this up, or "make it faster". Triggers the deterministic self-perf workflow (baseline → profile → optimize → verify improvement). +--- + +# Self-Perf + +Deterministic performance optimization loop. Baseline → optimize hot paths → verify improvement → summary. + +## Invoke + +Use the `devkit_start` tool with workflow: "self-perf" 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. diff --git a/skills/self-test/SKILL.md b/skills/self-test/SKILL.md new file mode 100644 index 0000000..c349aad --- /dev/null +++ b/skills/self-test/SKILL.md @@ -0,0 +1,14 @@ +--- +name: self-test +description: Run tests and fix failures until green — use when asked to self-test, fix tests, "make tests pass", "fix the failing tests", or "run tests and fix everything". Triggers the deterministic self-test workflow (baseline → fix → verify → loop until passing). +--- + +# Self-Test + +Deterministic test-fix loop. Baseline test run → fix failures → verify → loop until all pass → summary. + +## Invoke + +Use the `devkit_start` tool with workflow: "self-test" 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. diff --git a/skills/test-gen/SKILL.md b/skills/test-gen/SKILL.md index 6346879..7c5b5b7 100644 --- a/skills/test-gen/SKILL.md +++ b/skills/test-gen/SKILL.md @@ -1,85 +1,14 @@ --- name: test-gen -description: Generate tests for code — use when asked to write tests, create a test suite, add test coverage, or generate unit/integration tests for a file or module. +description: Generate tests for code — use when asked to write tests, create a test suite, add test coverage, or generate unit/integration tests for a file or module. Triggers the deterministic test-gen workflow (analyze → generate via test-writer agent → run-fix loop → report). --- # Test Generation -Generate tests for target code, run them, and iterate until they pass. +Deterministic test generation. Analyze target → generate via the test-writer subagent → run tests and iterate up to 3x → report. -## Step 1: Analyze Target +## Invoke -Read the target files and detect: -- Language and test framework (jest, vitest, pytest, go test, cargo test, etc.) -- Existing test patterns and conventions -- Exports, public API, and key code paths -- Edge cases and error conditions +Use the `devkit_start` tool with workflow: "test-gen" and input: "{input}". -If test framework isn't obvious, check `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, etc. - -## Step 2: Generate Tests - -Spawn the `test-writer` agent: - -``` -Task: Generate comprehensive tests for {target}. -Agent: test-writer -Context: - - Target: {target} - - Framework: {detected_framework} - - Existing test patterns: {patterns} - - User instructions: {args} -``` - -The test-writer should: -1. Create test files matching project conventions -2. Cover happy paths, edge cases, error conditions -3. Use descriptive test names -4. Mock external dependencies only when necessary -5. Follow existing test patterns in the repo - -## Step 3: Run and Fix - -```bash -{test_command} 2>&1 -``` - -If tests fail, send failures back to the test-writer agent to fix. Repeat up to 3 times. - -## Step 4: Report - -``` -## Test Generation Report - -**Target:** {target} -**Framework:** {framework} -**Tests created:** {count} -**Status:** all passing ✓ / {n} failing ✗ - -### Files Created -- tests/test_parser.py (12 tests) -- tests/test_api.py (8 tests) - -### Coverage -- Lines: {line_coverage}% -- Branches: {branch_coverage}% - -### Run -{test_command} -``` - -## Presets - -``` -/devkit:test-gen src/parser.ts -/devkit:test-gen lib/ --focus "error handling" -/devkit:test-gen src/api/ --unit-only -``` - -## Rules - -- Match existing test conventions exactly (naming, location, style) -- Never modify source code — only create/edit test files -- Tests must actually run and pass -- Iterate up to 3 times to fix failures -- If a test can't be fixed, skip it and note in report +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. diff --git a/skills/tri-debug/SKILL.md b/skills/tri-debug/SKILL.md new file mode 100644 index 0000000..9cc9e84 --- /dev/null +++ b/skills/tri-debug/SKILL.md @@ -0,0 +1,14 @@ +--- +name: tri-debug +description: Triple-agent debugging — use when asked for tri debug, triple debug, three-way debugging, multi-agent diagnosis, parallel debug, or consensus root-cause analysis. Three model tiers diagnose the bug independently and compare theories. Triggers the deterministic tri-debug workflow. +--- + +# Tri-Debug + +Deterministic three-model diagnosis. smart-diagnosis → general-diagnosis → fast-diagnosis (in parallel) → compare theories → consensus. + +## Invoke + +Use the `devkit_start` tool with workflow: "tri-debug" 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. diff --git a/skills/tri-dispatch/SKILL.md b/skills/tri-dispatch/SKILL.md new file mode 100644 index 0000000..5997f48 --- /dev/null +++ b/skills/tri-dispatch/SKILL.md @@ -0,0 +1,14 @@ +--- +name: tri-dispatch +description: Triple-tier task dispatch — use when asked for tri dispatch, triple dispatch, three-way comparison, "send this to three models", or "compare model approaches". Sends the same task to three model tiers in parallel and compares their approaches. Triggers the deterministic tri-dispatch workflow. +--- + +# Tri-Dispatch + +Deterministic three-tier task dispatch. smart-take → general-take → fast-take (in parallel) → compare approaches. + +## Invoke + +Use the `devkit_start` tool with workflow: "tri-dispatch" 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. diff --git a/skills/tri-review/SKILL.md b/skills/tri-review/SKILL.md new file mode 100644 index 0000000..407904c --- /dev/null +++ b/skills/tri-review/SKILL.md @@ -0,0 +1,14 @@ +--- +name: tri-review +description: Triple-agent code review — use when asked for a tri review, triple review, three-way review, multi-agent review, parallel review, or consensus review. Dispatches Claude/Codex/Gemini in parallel and consolidates findings. Triggers the deterministic tri-review workflow. +--- + +# Tri-Review + +Deterministic three-tier model review. Gather → review-smart → review-general → review-fast (in parallel) → consolidate. Runs under enforce: soft so the gather step can call git diff. + +## Invoke + +Use the `devkit_start` tool with workflow: "tri-review" 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. diff --git a/skills/tri-security/SKILL.md b/skills/tri-security/SKILL.md new file mode 100644 index 0000000..2261676 --- /dev/null +++ b/skills/tri-security/SKILL.md @@ -0,0 +1,14 @@ +--- +name: tri-security +description: Triple-agent security audit — use when asked for tri security, triple security audit, three-way security review, multi-agent vulnerability scan, or parallel security audit. Three-tier parallel review focused on injection, auth, and config. Triggers the deterministic tri-security workflow. +--- + +# Tri-Security + +Deterministic three-tier security audit. Gather → audit-injection → audit-auth → audit-config (in parallel) → consolidate with severity ranking. Runs under enforce: soft so the gather step can call git diff. + +## Invoke + +Use the `devkit_start` tool with workflow: "tri-security" 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. diff --git a/src/cmd/guard.go b/src/cmd/guard.go index 7146182..21b15b8 100644 --- a/src/cmd/guard.go +++ b/src/cmd/guard.go @@ -50,12 +50,18 @@ In PreToolUse mode (default) it reads a tool name and exits 0 to allow or 2 to block. In --stop mode it emits a Stop-hook JSON verdict on stdout ({"decision":"approve"} or {"decision":"block","reason":...}). -The allowlist policy mirrors hooks/devkit-guard.sh exactly: - command step + hard → only devkit MCP + TodoWrite - prompt step + hard → read-only evidence tools + devkit MCP +The allowlist policy: + command step + hard → devkit MCP + TodoWrite + Skill + prompt step + hard → read-only evidence tools + devkit MCP + Skill prompt step + soft → allow with a stderr nudge parallel / unknown → allow (engine is dispatching) - stale session (TTL) → allow with a stderr warning (orphan recovery)`, + stale session (TTL) → allow with a stderr warning (orphan recovery) + +Skill is allowed under both step types so a workflow that's mid-run can +still load a nested skill (e.g. user asks for tri-review during a feature +workflow). The dispatched skill calls devkit_start, which the engine +either accepts (if the current session is reclaimable) or rejects with +a clear error — the guard does not need to second-guess that.`, // Override the root's PersistentPreRunE: the guard hook runs on // every PreToolUse call and must not require a git repo, must not // open the SQLite DB, and must not fail if the host project has no @@ -330,7 +336,7 @@ func runPreToolGuard() { guardExit(0) return } - if isDevkitMCPTool(tool) || tool == "TodoWrite" { + if isDevkitMCPTool(tool) || tool == "TodoWrite" || tool == "Skill" { guardExit(0) return } @@ -347,7 +353,7 @@ func runPreToolGuard() { return } switch tool { - case "Read", "Grep", "Glob", "TodoWrite", "NotebookRead": + case "Read", "Grep", "Glob", "TodoWrite", "NotebookRead", "Skill": guardExit(0) return } diff --git a/src/cmd/guard_test.go b/src/cmd/guard_test.go index 34ad062..70baab9 100644 --- a/src/cmd/guard_test.go +++ b/src/cmd/guard_test.go @@ -209,6 +209,20 @@ func TestGuardPreToolUse(t *testing.T) { stdin: `{"tool_name":"TodoWrite"}`, wantExit: 0, }, + { + // Mid-workflow skill dispatch must work so a nested + // "do tri-review" inside an active feature workflow + // can load the trigger skill — engine still gates the + // devkit_start it issues, so guard does not need to. + name: "command+hard+Skill → allow", + dataDir: true, + hasSession: true, + session: lib.SessionState{ + Status: "running", StepType: "command", Enforce: "hard", CurrentStep: "build", + }, + stdin: `{"tool_name":"Skill"}`, + wantExit: 0, + }, { name: "command+soft → allow", dataDir: true, @@ -421,6 +435,19 @@ func TestGuardPreToolUse(t *testing.T) { stdin: `{"tool_name":"TodoWrite"}`, wantExit: 0, }, + { + // Mid-workflow skill dispatch under prompt+hard so a + // nested keyword ("do deep research") loads its trigger + // skill instead of being silently blocked. + name: "prompt+hard+Skill → allow", + dataDir: true, + hasSession: true, + session: lib.SessionState{ + Status: "running", StepType: "prompt", Enforce: "hard", CurrentStep: "analyse", + }, + stdin: `{"tool_name":"Skill"}`, + wantExit: 0, + }, { // Fixture parity gap: soft enforcement is supposed to let // write-tier tools through, not just Bash. Pin the contract. diff --git a/src/engine/new_workflows_test.go b/src/engine/new_workflows_test.go new file mode 100644 index 0000000..c8cddf2 --- /dev/null +++ b/src/engine/new_workflows_test.go @@ -0,0 +1,36 @@ +package engine + +import ( + "path/filepath" + "testing" +) + +// TestParseNewWorkflows is a temporary sanity test added while landing +// feat/deterministic-skill-dispatch. It parses every YAML under +// ../../workflows/ through the engine's own parser so a malformed new +// workflow (test-gen / doc-gen / onboard / etc.) fails loudly in CI +// instead of at first `devkit_start` call on the user's box. +// +// Safe to remove once the parse is exercised by an integration harness +// that walks the workflows directory natively. +func TestParseAllShippedWorkflows(t *testing.T) { + matches, err := filepath.Glob("../../workflows/*.yml") + if err != nil { + t.Fatalf("glob workflows: %v", err) + } + if len(matches) == 0 { + t.Fatalf("no workflows found under ../../workflows/*.yml") + } + for _, path := range matches { + path := path + t.Run(filepath.Base(path), func(t *testing.T) { + wf, err := ParseFile(path) + if err != nil { + t.Fatalf("ParseFile(%s): %v", path, err) + } + if err := wf.Validate(); err != nil { + t.Fatalf("Validate(%s): %v", path, err) + } + }) + } +} diff --git a/workflows/doc-gen.yml b/workflows/doc-gen.yml new file mode 100644 index 0000000..1fe3ea8 --- /dev/null +++ b/workflows/doc-gen.yml @@ -0,0 +1,54 @@ +name: Documentation Generation +description: Generate code documentation via the documenter agent — analyze code → spawn documenter → write output + +steps: + - id: analyze + model: general + prompt: | + Target: {{input}} + + 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 + - Existing doc style if docs already exist (match it) + + Output: + - List of public surface items to document + - Existing doc location (if any) + - Doc style to match + + - id: generate + model: smart + prompt: | + Target: {{input}} + Analysis: {{analyze}} + + Spawn the `documenter` agent via the Task tool with the analysis as context. + The agent must produce: + 1. Overview — what the module/package does + 2. API Reference — every public export with signature, params, return type, description + 3. Usage Examples — realistic code snippets (not placeholders) + 4. Configuration — options and defaults if applicable + + Rules: + - Read actual code — don't guess signatures or behavior + - Match existing doc style if docs already exist + - Don't document internal/private code unless asked + - Concise — one line per param, one paragraph per function + + Return the generated content. + + - id: write + model: fast + prompt: | + Generated docs: {{generate}} + + Write to the appropriate location: + - If a `docs/` directory exists, write there + - If a specific output path was requested in {{input}}, use that + - Otherwise, output inline and tell the user where they want it saved + + Report the final file path(s). diff --git a/workflows/onboard.yml b/workflows/onboard.yml new file mode 100644 index 0000000..1182eda --- /dev/null +++ b/workflows/onboard.yml @@ -0,0 +1,91 @@ +name: Codebase Onboarding +description: Generate an onboarding guide for new contributors — analyze structure → spawn researcher → write guide + +steps: + - id: analyze + model: general + prompt: | + Target codebase: {{input}} + + 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 + + Output: + - Project type (language, framework) + - Install/test/dev commands from manifests + - Top-level directory map + - Existing docs to reference + + - id: architect + model: smart + prompt: | + Target codebase: {{input}} + Initial analysis: {{analyze}} + + Spawn the `researcher` agent via the Task tool with the analysis as context. + The agent must identify: + 1. Architecture pattern (monolith, microservices, MVC, layered, etc.) + 2. Key directories and what lives in each + 3. Data flow — how a request/event moves through the system + 4. Core abstractions — important types, interfaces, classes + 5. External dependencies — APIs, databases, services + 6. Build and deploy — how to build, test, and deploy + 7. Non-obvious gotchas a new contributor will hit + + Read actual code, don't guess from file names. + + Return the architectural summary. + + - id: guide + model: smart + prompt: | + Initial analysis: {{analyze}} + Architecture: {{architect}} + + Generate the onboarding guide in this exact shape: + + ## Onboarding: + + ### Quick Start + 1. Install dependencies: + 2. Run tests: + 3. Start dev server: + + ### Architecture + <2-4 paragraphs from {{architect}}> + + ### Directory Map + | Directory | Purpose | + |---|---| + | ... | ... | + + ### Key Files + | File | Why it matters | + |---|---| + | ... | ... | + + ### Data Flow + + + ### Patterns & Conventions + - + - + + ### Gotchas + - + - + + ### Common Tasks + | Task | How | + |---|---| + | Add a new endpoint | ... | + | Add a DB migration | ... | + | Run specific tests | ... | + + Write the guide to `docs/ONBOARDING.md` (create the directory if needed). + Report the final file path. diff --git a/workflows/test-gen.yml b/workflows/test-gen.yml new file mode 100644 index 0000000..9b74e44 --- /dev/null +++ b/workflows/test-gen.yml @@ -0,0 +1,69 @@ +name: Test Generation +description: Generate tests for code, run them, iterate until they pass — analyze → generate via test-writer agent → run-fix loop → report + +steps: + - id: analyze + model: general + prompt: | + Target: {{input}} + + Read the target file(s) and detect: + - Language and test framework (jest, vitest, pytest, go test, cargo test, etc.) + - Existing test patterns and conventions in the repo + - Public exports, key code paths + - Edge cases and error conditions worth covering + + If the test framework isn't obvious, check package.json, pyproject.toml, go.mod, Cargo.toml. + + Output: + - Detected framework + test command + - List of files to test + - List of code paths to cover (happy path, edge cases, errors) + + - id: generate + model: smart + prompt: | + Target: {{input}} + Analysis: {{analyze}} + + Spawn the `test-writer` agent via the Task tool with the analysis as context. + The agent must: + 1. Create test files matching project conventions (naming, location, style) + 2. Cover happy paths, edge cases, error conditions + 3. Use descriptive test names + 4. Mock external dependencies only when necessary + 5. Follow existing test patterns in the repo + 6. NEVER modify source code — only create/edit test files + + Report which files the agent created. + + - id: run-fix + model: general + prompt: | + Test files just created: {{generate}} + + Run the project's test command and check the result. + + If any tests fail: + - Send the failures back to the test-writer agent via Task with the failing output + - Re-run after the agent's fix + - Loop until all pass or you hit the iteration cap + + If all tests pass, say DONE. + loop: + max: 3 + until: DONE + + - id: report + model: fast + prompt: | + Test generation complete. + + Final state: {{run-fix}} + + Produce a short report: + - Target: {{input}} + - Files created (with test counts) + - Pass/fail status + - Iterations needed + - Any tests skipped + reason From a7c3aebceed06b94784c64a108703e49049f7a97 Mon Sep 17 00:00:00 2001 From: Tym Rabchuk Date: Sat, 11 Apr 2026 02:05:01 -0400 Subject: [PATCH 2/2] docs: update README and ROADMAP for deterministic skill dispatch MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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. --- README.md | 46 +++++++++++++++++++++++++++++++++++++--------- ROADMAP.md | 5 +++-- 2 files changed, 40 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 174a42d..6cd7528 100644 --- a/README.md +++ b/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 ""): ``` 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) diff --git a/ROADMAP.md b/ROADMAP.md index 76ee1dc..d1bb5a7 100644 --- a/ROADMAP.md +++ b/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