5uck1ess · 5uck1ess · Apr 9, 2026 · Apr 9, 2026 · Apr 9, 2026 · Apr 9, 2026
diff --git a/README.md b/README.md
@@ -310,7 +310,7 @@ devkit/
 ├── skills/            # 18 context-activated skills
 ├── agents/            # 6 agents (reviewer, researcher, improver, ...)
 ├── hooks/             # 10 hooks (safety, security, quality gates)
-├── workflows/         # 15 YAML workflow definitions
+├── workflows/         # 16 YAML workflow definitions
 ├── resources/rules/   # Language-specific coding rules
 ├── presets/            # Reserved for future use
 ├── src/               # Go CLI harness

diff --git a/ROADMAP.md b/ROADMAP.md
@@ -12,7 +12,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)
-- **15 YAML workflows** — Portable workflow definitions (feature, bugfix, refactor, research, deep-research, autoloop, self-*, tri-*)
+- **16 YAML workflows** — Portable workflow definitions (feature, bugfix, refactor, research, deep-research, autoloop, self-*, tri-*)
 - **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
@@ -34,6 +34,6 @@ Items below were on the roadmap but determined to be unnecessary — either alre
 | Stop hook redesign | Still fires every turn, but exits early with `approve` when no files are changed — near-instant on clean trees, so the performance concern is moot. Revisit only if it causes measurable latency. |
 | Cost event hooks | Budget enforcement already exists in the Go engine via `overBudget()` + `addCost()` callbacks with hard limits |
 | Execution registry | Step tracking already handled by SQLite via `lib.DB` with status, cost, and timing per step |
-| Preset library | The 15 YAML workflows and 18 skills already serve this purpose |
+| Preset library | The 16 YAML workflows and 18 skills already serve this purpose |
 | Framework-specific review checklists | `lang-review.sh` covers language-level patterns; framework-specific rules are better added per-project via hookify |
 | Conditional hook firing | Hooks already self-filter internally (extension checks, changed-file checks); a generic condition system adds complexity for no current need |
diff --git a/commands/self-improve.md b/commands/self-improve.md
@@ -1,104 +1,27 @@
 ---
-description: Self-recursive improvement loop — automated refactoring with test gate. Uses native improver agent in worktree isolation. Propose → measure → keep/discard → repeat.
+description: Metric-gated improvement loop — run command, fix issues, repeat until passing.
 ---
 
-# Self-Improve Loop
+# Self-Improve
 
-Autonomous, iterative improvement of a target file or directory. Each iteration: propose change → run metric → keep if better → discard if worse → repeat.
+Deterministic improvement loop: run metric → fix issues → gate check → repeat until exit code 0.
 
-## Parameters
+## Invoke
 
-1. **Target** — file or directory to improve (required)
-2. **Metric** — shell command that exits 0 on success (required)
-3. **Objective** — what to optimize for (required)
-4. **Iterations** — max cycles (default: 10)
-5. **Budget** — max USD (default: $2)
-
-## Budget & Early Exit
-
-- **Token budget:** ~300k tokens. If approaching limit, reduce remaining iteration count.
-- **Early exit:** Stop the loop immediately if the metric output contains the objective target (e.g., "0 errors", "100%", or a user-specified success string).
-- **Stuck detection:** If 3 consecutive iterations fail (revert), stop the loop and report. Don't keep trying the same failing approach. See the `stuck` skill.
-
-## Step 1: Establish Baseline
-
-```bash
-git checkout -b self-improve/$(date +%Y%m%d-%H%M%S)
-BASELINE=$({metric_command} 2>&1)
-echo "$BASELINE" > /tmp/self-improve-baseline.txt
-echo "$BASELINE" > /tmp/self-improve-best.txt
-```
-
-## Step 2: Run the Loop
-
-For each iteration, spawn the `improver` agent as a native background task with worktree isolation:
-
-```
-Task: Improve {target} toward objective: {objective}
-Agent: improver
-Context:
-  - Iteration history: (cat /tmp/self-improve-log.txt)
-  - Current best metric: (cat /tmp/self-improve-best.txt)
-  - Target file(s): {target}
-```
-
-The improver agent:
-1. Reads the target and iteration history
-2. Proposes ONE focused change
-3. Applies it
-
-Then the orchestrator:
-```bash
-RESULT=$({metric_command} 2>&1)
-EXIT_CODE=$?
-
-if [ $EXIT_CODE -eq 0 ]; then
-  echo "ITERATION $i: SUCCESS" >> /tmp/self-improve-log.txt
-  echo "$RESULT" > /tmp/self-improve-best.txt
-  git add -A && git commit -m "self-improve: iteration $i — passed"
-else
-  echo "ITERATION $i: FAILED — reverting" >> /tmp/self-improve-log.txt
-  git checkout -- .
-fi
 ```
-
-## Step 3: Report
-
+devkit workflow run self-improve "{metric_command}"
 ```
-## Self-Improve Report
-
-**Target:** {target}
-**Objective:** {objective}
-**Iterations:** {completed} / {total}
-
-### Baseline → Final
-{baseline} → {final}
 
-### Log
-| # | Result | Change |
-|---|--------|--------|
-| 1 | PASS   | Refactored validation |
-| 2 | FAIL   | Caching — broke tests |
-| 3 | PASS   | Extracted helper |
+If `devkit workflow` is not available, follow this manually:
 
-### Next Steps
-- Review: `git diff main...HEAD`
-- Merge: `git checkout main && git merge self-improve/{branch}`
-- Discard: `git checkout main && git branch -D self-improve/{branch}`
-```
-
-## Presets
-
-```
-/self:improve --target src/ --metric "npm test" --objective "fix failing tests"
-/self:improve --target train.py --metric "python train.py" --objective "minimize val_bpb" --iterations 50
-```
+1. **Baseline** — Run the metric command and capture output
+2. **Improve loop** — Analyze failures, make targeted fixes, re-run metric; stop when passing (max 10 iterations)
+3. **Verify** — Run metric one final time
+4. **Summary** — Report what was fixed, iteration count, final metric status
 
 ## Rules
 
-- Uses native `improver` agent with worktree isolation (token-efficient)
-- Always branches first — never modifies main
-- One change per iteration
-- Discard on failure — `git checkout -- .`
-- Never modify the metric command
-- Human merges at end — never auto-merges
+- Only change what's needed to improve the metric
+- Don't refactor unrelated code
+- One group of related fixes per iteration
+- The metric command must exit non-zero when improvement is still needed
diff --git a/commands/self-lint.md b/commands/self-lint.md
@@ -1,96 +1,27 @@
 ---
-description: Self-improvement loop targeting lint and type errors. Iteratively fixes issues until zero remain or iterations exhausted.
+description: Run linter, fix violations deterministically, repeat until clean.
 ---
 
-# Self-Improve: Lint / Type Errors
+# Self-Lint
 
-Automated loop that runs your linter or type checker, fixes issues one at a time, and verifies no regressions.
+Deterministic lint-fix loop: run linter → fix violations → gate check → repeat until exit code 0.
 
-## Parameters
+## Invoke
 
-1. **Lint command** — command that reports lint/type errors (required)
-2. **Target** — file or directory scope (default: entire project)
-3. **Iterations** — max cycles (default: 20)
-4. **Budget** — max USD (default: $2)
-
-## Budget & Early Exit
-
-- **Token budget:** ~200k tokens. Lint fixes are usually cheap.
-- **Early exit:** Stop immediately when error count reaches 0.
-- **Stuck detection:** If 3 consecutive iterations show no improvement (error count doesn't decrease), stop and report. See the `stuck` skill.
-
-## Step 1: Establish Baseline
-
-```bash
-git checkout -b self-lint/$(date +%Y%m%d-%H%M%S)
-BASELINE=$({lint_command} 2>&1)
-ERRORS=$(echo "$BASELINE" | grep -cE '(error|warning)')
-echo "Baseline: $ERRORS issues" > /tmp/self-lint-log.txt
-echo "$BASELINE" > /tmp/self-lint-baseline.txt
-```
-
-## Step 2: Run the Loop
-
-For each iteration, spawn the `improver` agent:
-
-```
-Task: Fix lint/type errors in {target}.
-Agent: improver
-Context:
-  - Iteration: {i} of {max}
-  - Remaining errors: {error_count}
-  - Current lint output: {lint_output}
-  - Iteration history: (cat /tmp/self-lint-log.txt)
 ```
-
-The improver agent:
-1. Reads the lint output
-2. Picks the highest-priority error
-3. Fixes ONE issue (or a group of related issues in one file)
-
-Then the orchestrator:
-```bash
-RESULT=$({lint_command} 2>&1)
-NEW_ERRORS=$(echo "$RESULT" | grep -cE '(error|warning)')
-
-if [ $NEW_ERRORS -lt $PREV_ERRORS ]; then
-  echo "ITERATION $i: PASS — $PREV_ERRORS → $NEW_ERRORS issues" >> /tmp/self-lint-log.txt
-  git add -A && git commit -m "self-lint: iteration $i — $NEW_ERRORS remaining"
-  PREV_ERRORS=$NEW_ERRORS
-else
-  echo "ITERATION $i: FAIL — no improvement or regression, reverting" >> /tmp/self-lint-log.txt
-  git checkout -- .
-fi
+devkit workflow run self-lint "{lint_command}"
 ```
 
-Stop early if zero errors remain.
+If `devkit workflow` is not available, follow this manually:
 
-## Step 3: Report
-
-```
-## Self-Lint Report
-
-**Lint command:** {lint_command}
-**Errors:** {baseline_count} → {final_count}
-**Iterations:** {completed} / {total}
-
-### Log
-| # | Result | Errors | Fix |
-|---|--------|--------|-----|
-| 1 | PASS   | 12→10  | Fixed unused imports in api.ts |
-| 2 | PASS   | 10→8   | Added missing return types |
-| 3 | FAIL   | 8→8    | Reverted — no improvement |
-
-### Next Steps
-- Review: `git diff main...HEAD`
-- Merge: `git checkout main && git merge self-lint/{branch}`
-```
+1. **Baseline** — Run the lint command and capture output
+2. **Fix loop** — Fix one group of related lint/type issues at a time; re-run linter after each fix; stop when clean (max 20 iterations)
+3. **Verify** — Run linter one final time
+4. **Summary** — Report what was fixed and what remains
 
 ## Rules
 
-- Uses `improver` agent with worktree isolation
-- Always branches first
-- Error count must strictly decrease to keep a change
-- Discard on regression or no improvement
-- Stop early at zero errors
+- Prioritize errors over warnings
+- Fix one group of related issues at a time
+- Don't change code behavior — only fix lint issues
 - Never disable lint rules — fix the underlying issue
diff --git a/commands/self-migrate.md b/commands/self-migrate.md
@@ -1,113 +1,27 @@
 ---
-description: Self-improvement loop for incremental codebase migrations. Iteratively migrates code with tests as the safety gate.
+description: Incremental migration loop — migrate code one piece at a time with tests as safety gate.
 ---
 
-# Self-Improve: Migration
+# Self-Migrate
 
-Automated, incremental migration loop. Each iteration migrates a small piece, runs tests, keeps if green, reverts if red.
+Deterministic migration loop: run tests → migrate one piece → gate check → repeat until gate exits 0.
 
-## Parameters
-
-1. **Target** — file or directory to migrate (required)
-2. **Test command** — command that validates correctness (required)
-3. **Migration** — what to migrate to (required, e.g., "TypeScript", "React hooks", "Python 3.12", "ES modules")
-4. **Iterations** — max cycles (default: 20)
-5. **Budget** — max USD (default: $3)
-
-## Budget & Early Exit
-
-- **Token budget:** ~400k tokens. Migrations can touch many files.
-- **Early exit:** Stop when all target files are migrated — don't run remaining iterations.
-- **Stuck detection:** If 3 consecutive iterations fail (tests break after migration), stop and report. The remaining files may need manual intervention. See the `stuck` skill.
-
-## Step 1: Establish Baseline
-
-```bash
-git checkout -b self-migrate/$(date +%Y%m%d-%H%M%S)
-{test_command} 2>&1 > /tmp/self-migrate-baseline.txt
-```
-
-All tests must pass before starting. Abort if baseline fails.
-
-## Step 2: Run the Loop
-
-For each iteration, spawn the `improver` agent:
-
-```
-Task: Migrate {target} toward {migration}.
-Agent: improver
-Context:
-  - Iteration: {i} of {max}
-  - Migration objective: {migration}
-  - Iteration history: (cat /tmp/self-migrate-log.txt)
-  - Remaining unmigrated files: {file_list}
-  - Target: {target}
-```
-
-The improver agent:
-1. Identifies the next file or component to migrate
-2. Performs ONE migration step (one file or one closely-related group)
-3. Updates imports/references as needed
-
-Then the orchestrator:
-```bash
-RESULT=$({test_command} 2>&1)
-EXIT_CODE=$?
-
-if [ $EXIT_CODE -eq 0 ]; then
-  MIGRATED=$(git diff --name-only)
-  echo "ITERATION $i: PASS — migrated $MIGRATED" >> /tmp/self-migrate-log.txt
-  git add -A && git commit -m "self-migrate: iteration $i — ${migration}"
-else
-  echo "ITERATION $i: FAIL — reverting" >> /tmp/self-migrate-log.txt
-  git checkout -- .
-fi
-```
-
-Stop early if all target files are migrated.
-
-## Step 3: Report
+## Invoke
 
 ```
-## Self-Migrate Report
-
-**Target:** {target}
-**Migration:** {migration}
-**Iterations:** {completed} / {total}
-
-### Migrated Files
-- src/utils.js → src/utils.ts ✓
-- src/api.js → src/api.ts ✓
-- src/parser.js → (failed, reverted)
-
-### Log
-| # | Result | File(s) |
-|---|--------|---------|
-| 1 | PASS   | utils.js → utils.ts |
-| 2 | PASS   | api.js → api.ts |
-| 3 | FAIL   | parser.js — type errors |
-
-### Next Steps
-- Review: `git diff main...HEAD`
-- Merge: `git checkout main && git merge self-migrate/{branch}`
+devkit workflow run self-migrate "{test_command}"
 ```
 
-## Presets
+If `devkit workflow` is not available, follow this manually:
 
-```
-/self:migrate --target src/ --test "npm test" --migration "TypeScript strict mode"
-/self:migrate --target app/ --test "pytest" --migration "Python 3.12 syntax (match statements, tomllib)"
-/self:migrate --target components/ --test "npm test" --migration "React class components to hooks"
-/self:migrate --target lib/ --test "go test ./..." --migration "Go 1.22 range-over-func"
-```
+1. **Baseline** — Run tests to confirm green starting point
+2. **Migrate loop** — Migrate one file or closely-related group per iteration; update imports/references; re-run gate command after each step (max 20 iterations). To detect migration completeness, use a gate command that exits non-zero until all files are converted (e.g., `npm test && ! grep -r 'require(' src/`).
+3. **Verify** — Run tests one final time
+4. **Summary** — Report which files were migrated and what remains
 
 ## Rules
 
-- Uses `improver` agent with worktree isolation
-- Always branches first
 - One file or closely-related group per iteration
 - Tests must pass to keep — no exceptions
-- Discard on any test failure
 - Preserve existing behavior — migration, not refactoring
 - Update imports and references in the same iteration
-- Stop when all target files are migrated