5uck1ess · 5uck1ess · Apr 9, 2026 · Apr 9, 2026 · Apr 9, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,19 +1,26 @@
 # Contributing to Devkit
 
-## Adding a Slash Command (deterministic workflow)
+## Adding a Workflow
+
+Most command logic lives in YAML workflows executed by the Go engine. Only 8 slash commands remain as tab-completable entry points.
+
+1. Create `workflows/my-workflow.yml` with steps, model assignments, and loop/gate definitions
+2. Test with `devkit workflow run my-workflow "input"`
+3. Optionally add a context-activated skill in `skills/` to auto-trigger it
+
+See `skills/creating-workflows/SKILL.md` for YAML schema reference.
+
+### Adding a Slash Command (rare — only for top-level entry points)
 
-Slash commands appear in tab-completion and run step-by-step workflows.
+Only add a command if it needs tab-completion. Most workflows are invoked via `devkit workflow run` or context-activated skills.
 
 1. Create `commands/my-command.md` with YAML frontmatter:
    ```markdown
    ---
    description: What this command does.
    ---
-   # Command Title
-   Step-by-step workflow with numbered steps.
+   Run `devkit workflow run my-workflow` to execute.
    ```
-2. Include Budget & Early Exit section if the command loops
-3. Include `[PARALLEL]` markers if steps run concurrently
 
 The command name is derived from the filename: `commands/my-command.md` becomes `/devkit:my-command`.
 

diff --git a/README.md b/README.md
@@ -306,7 +306,7 @@ Self-Improvement (self:* commands)
 
 ```
 devkit/
-├── commands/          # 24 slash commands
+├── commands/          # 8 slash commands (tab-completable entry points)
 ├── skills/            # 19 context-activated skills
 ├── agents/            # 6 agents (reviewer, researcher, improver, ...)
 ├── hooks/             # 10 hooks (safety, security, quality gates)

diff --git a/ROADMAP.md b/ROADMAP.md
@@ -2,7 +2,8 @@
 
 ## Implemented
 
-- **24 slash commands** — Lifecycle workflows, self-improvement loops, multi-agent dispatch, project health audit, post-PR monitoring, AST repo mapping, autoresearch-inspired self-audit, autoloop, setup-rules
+- **8 slash commands** — Tab-completable entry points (tri-review, tri-debug, tri-security, pr-ready, pr-monitor, status, setup-rules, workflow); 16 former commands now context-activated via skills or invoked directly via `devkit workflow run`
+- **Deterministic workflow conversion** — All command logic moved from LLM-interpreted markdown to Go-engine-driven YAML workflows; ~3,600 lines of inline logic removed
 - **19 context-activated skills** — 9 auto-trigger workflows (test-gen, doc-gen, changelog, onboard, research, deep-research, scrape, autoloop, adr) + 6 coding principles (executing, clean-code, DRY, YAGNI, dont-reinvent, stuck) + 2 tools (gcli, creating-workflows) + 1 iteration memory (scratchpad) + 1 orchestration (mega-pr)
 - **6 agents** — Scoped tool access, worktree isolation, model assignment
 - **10 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)

diff --git a/commands/audit.md b/commands/audit.md
diff --git a/commands/autoloop.md b/commands/autoloop.md
diff --git a/commands/bugfix.md b/commands/bugfix.md
diff --git a/commands/decompose.md b/commands/decompose.md
diff --git a/commands/deep-research.md b/commands/deep-research.md
diff --git a/commands/feature.md b/commands/feature.md
diff --git a/commands/pr-ready.md b/commands/pr-ready.md
@@ -2,31 +2,4 @@
 description: Full PR preparation pipeline — validate branch, DRY review, lint, test, security, changelog, create PR.
 ---
 
-# PR Ready
-
-Deterministic PR preparation: validate → necessity check → DRY review → lint → test → security → changelog → create PR.
-
-## Invoke
-
-```
-devkit workflow run pr-ready
-```
-
-If `devkit workflow` is not available, follow this manually:
-
-1. **Validate branch** — Confirm not on main/master, check for uncommitted changes, verify remote tracking
-2. **Necessity check** — Review each changed file: is it needed? Remove unnecessary additions, debug artifacts, or unrelated changes.
-3. **DRY review** — Check for duplicated logic across changed files. Extract shared code if 3+ repetitions.
-4. **Lint** — Run project linter on changed files. Fix violations.
-5. **Test** — Run full test suite. Fix failures.
-6. **Security quick-check** — Scan for: hardcoded secrets, SQL injection, XSS, command injection, path traversal, insecure dependencies
-7. **Generate changelog** — Create changelog entry from git diff summarizing what changed and why
-8. **Create PR** — Push branch, create PR with title + summary + test plan
-
-## Rules
-
-- Every step must pass before proceeding to the next
-- Remove unnecessary changes before reviewing code quality
-- Fix lint and test failures — don't skip them
-- Security check is not optional
-- Changelog should explain WHY, not just WHAT
+Run `devkit workflow run pr-ready` to execute the deterministic PR preparation workflow.
diff --git a/commands/refactor.md b/commands/refactor.md
diff --git a/commands/repo-map.md b/commands/repo-map.md
diff --git a/commands/self-audit.md b/commands/self-audit.md
diff --git a/commands/self-improve.md b/commands/self-improve.md