VividKit Crystal clear AI coding
VI
Choose Your Setup Get Started with AgentKit Continue with ClaudeKit Migrate from ClaudeKit to AgentKit Clean cutover from ClaudeKit What Is AgentKit? How AgentKit Works AgentKit Kits, Skills, Agents & Hooks AgentKit Runtime Support AgentKit Desktop App AgentKit Configuration AgentKit CLI Quick Reference AgentKit Skills Cheatsheet AgentKit Workflows AgentKit Statusline Update AgentKit CLI & Kits AgentKit Helper Clean reinstall of AgentKit AgentKit Troubleshooting What is ClaudeKit? ClaudeKit CLI Guide Command Finder Commands Cheat Sheet Workflow Recipes CLI Quick Reference Claude Mechanics Permission Modes ClaudeKit Hooks Coexistence ClaudeKit x Codex CK → Other coding tools How ClaudeKit Works Inside ClaudeKit Finding Your Unknowns Session Recovery Fix from Logs UI/UX Guide Accounts Switcher IDE Config Remote Control Codex App System Diagramming UI Review Gate Promotions Support VividKit

Quick Ref / Command

Engineer Kit

/ak:loop

Autonomous Metric Loop

Run sequential atomic experiments against a mechanical metric, commit before verifying, keep improvements, revert regressions, log loop-results.tsv, and stop when stuck or unsafe.

01

Confirm metric fit

02

Parse or ask config

03

Safety-screen Verify

04

Run preconditions

Rule 01

Constraint + mechanical metric + fast verification enables autonomous improvement.

Rule 02

One atomic change per iteration keeps learning interpretable.

Rule 03

Git commits are loop memory; revert preserves history when a trial loses.

Execution Map

Core lanes from input to output, aligned with the command's real execution path.

01

Start

Input, scope, route

  1. 1 Confirm metric fit Use ak:loop only for a measurable objective where repeated trials can be judged by one numeric Verify output.
  2. 2 Parse or ask config Collect required Goal, Scope, and Verify plus optional Guard, Iterations, Noise, Min-Delta, and Direction; ask missing fields in one batched ask_user call.
  3. 3 Safety-screen Verify Before dry-running Verify, refuse destructive or fetch-and-execute commands and warn or re-prompt for outbound writes, embedded credentials, sudo, chmod 777, or unsafe ownership changes.
02

Work

Agent / skill execution

  1. 4 Run preconditions Abort unless the workspace is a clean git repository on a named branch, has no stale loop lock, Scope matches files, Verify prints a number, Guard passes if present, and baseline metric is logged.
  2. 5 Review loop memory Before each iteration, inspect recent git history, the last diff, and loop-results.tsv to learn which targets helped or failed.
  3. 6 Ideate one change Choose exactly one atomic experiment, exploiting successful patterns, avoiding repeated failures, and splitting any idea that needs “and”.
03

Verify

Gate, review, validation

  1. 7 Modify within Scope Edit only files matched by Scope, never modify files referenced by Guard, and keep the change minimal enough to attribute the metric movement.
  2. 8 Commit before Verify Commit the atomic change with a loop(iter-N) message before running Verify because git is the loop’s memory and rollback mechanism.
  3. 9 Verify, guard, decide Run Verify and optional Guard; keep only Direction/Min-Delta improvements that pass Guard, otherwise prefer git revert and treat crashes, no-number output, and timeouts as failures.
04

Close

Report, handoff, artifact

  1. 10 Log and stop Append iter, timestamp, metric, delta, kept, and description to loop-results.tsv, shift strategy after 5 consecutive discards, and stop after the iteration cap, interruption, timeout, or 10 discards.

Syntax, arguments, subcommands

How to invoke the skill: syntax, positional arguments, shared options, then each subcommand with its own syntax and outcome.

Syntax

/ak:loop [Goal/Metric description] or inline config block

Arguments

Goal: Required

Goal

Human-readable metric outcome and target to improve. Subjective cleanup goals are rejected; use ak:cook for those.

/ak:loop Goal: Reduce TypeScript errors in src/api to zero
Scope: Required

Editable scope

Glob or search-files patterns for files the loop may edit. The Skill does not widen this scope or edit files owned by the Guard command.

/ak:loop Scope: src/api/**/*.ts
Verify: Required

Metric command

Shell command that exits successfully and prints exactly one numeric metric quickly enough to run every iteration.

/ak:loop Verify: npx tsc --noEmit 2>&1 | grep -c '^src/api/.*error TS' || true

Shared options

Guard:

Regression guard

Optional command that must exit 0 for a trial to be kept. Its files are treated as read-only for the loop.

/ak:loop Guard: npm test
Iterations:

Iteration cap

Maximum trial count; defaults to 10 when omitted.

/ak:loop Iterations: 12
Direction:

Metric direction

Whether higher or lower metric values are better; defaults to higher.

/ak:loop Direction: lower
Noise:

Measurement noise

Measurement treatment: low, medium, or high. Use it to decide repeat and aggregation behavior, not to hide regressions.

/ak:loop Noise: low
Min-Delta:

Minimum progress

Smallest improvement that counts as progress; defaults to 0.

/ak:loop Min-Delta: 1

Don't skip the required step

Each item contrasts a tempting shortcut with the required approach.

Tempting shortcut

“Make it cleaner” can be optimized by taste.

Do this instead

Subjective goals belong to ak:cook or interactive work, not ak:loop.

Tempting shortcut

Run Verify first, then commit if it passes.

Do this instead

Commit before Verify so the loop has memory and can revert losing trials.

Tempting shortcut

Guard files failed; edit them.

Do this instead

Guard files are read-only for the loop.

Sample Prompt

Concrete invocations for each flag, subcommand, mode, or route available in the live workflow.

Coverage loop Recommended 
/ak:loop Goal: Increase test coverage in src/utils from ~60% to 80% Scope: src/utils/**/*.ts Verify: npx jest tests/utils --coverage
Use when:
Use only when a mechanical metric can drive repeated trials.
Expected:
Asks for any missing Goal/Scope/Verify fields, then runs atomic git-backed trials, commits before verify, keeps gains, reverts losses, and appends loop-results.tsv.
Bundle size 
/ak:loop Goal: Reduce main bundle size below 200KB Scope: src/**/*.ts Direction: lower
Use when:
Use when lower is better and Verify can print one number in under 30 seconds.
Expected:
Screens the Verify command for unsafe patterns, refuses dirty/non-git trees, then loops until min-delta, iteration cap, or stuck detection.
Lint errors to zero 
/ak:loop Goal: Drive ESLint error count to zero in src/api Scope: src/api/**/*.ts Direction: lower Iterations: 20
Use when:
Use for countable lint/error metrics inside a declared Scope.
Expected:
Never edits Guard-scoped files; after 10 consecutive discards it stops and reports findings instead of inventing a subjective cleanup.

Handled Scope

  • Coverage, lint, performance, and bundle-size optimization
  • Metric-driven experiment loops
  • Git-backed keep/discard decisions
  • Verify-command safety screening
  • Stuck detection

Artifacts Produced

Loop results

Pattern

loop-results.tsv plus final kept/discarded summary, best metric, blockers, and masked logs.

The report must mask secrets and explain why changes were kept or reverted.

Next