auto-optimize

name	auto-optimize
description	Automate analysis, evaluation, design and optimization of target projects. Integrate VibeGuard as a baseline scan, the remediation process adheres to VibeGuard specifications, and a compliance check is run at the end. Support auto-run-agent autonomous execution.

Auto-Optimize: Autonomous optimization process

Integrate the project autonomous optimization workflow of the VibeGuard guard system.

When to Activate

• The user asks for repository optimization discovery and implementation.
• A project needs a rotating scan across security, quality, reliability, performance, and maintainability.
• Existing guard or audit findings should be converted into prioritized implementation work.
• The task needs an optimization report before deciding which fixes to execute.
• The task is already routed to executable optimization work, not open-ended discovery.
• A planning handoff selected this workflow and supplied lane ownership plus stop conditions.
• The user explicitly asks for autonomous optimization across quality, reliability, security, or DX dimensions.

Red Flags

• The workflow starts from clarify_first or plan_first without a completed handoff.
• Delegated lanes share writable files or lack explicit ownership.
• A finding is repaired before it has evidence, classification, and a verification command.

Checklist

• Confirm routing readiness and lane ownership before execution.
• Classify every finding as FIX, SKIP, or DEFER with evidence.
• Run VibeGuard deterministic checks before and after implemented fixes.

Routing Contract Integration

Auto-Optimize follows the canonical router in workflows/references/routing-contract.md.

Start autonomous optimization only when both conditions are true:

• readiness already resolved to executable work (execute_direct, or a planning handoff selected this workflow)
• lane_map assigns clear ownership for every delegated lane used by the run

Do not start autonomous execution when:

• readiness is clarify_first
• readiness is plan_first and no execution handoff exists yet
• delegation ownership is missing, shared, or contradictory

When Auto-Optimize consumes a planning handoff, it must honor:

• mode
• artifacts
• runtime_pinning_snapshot
• verification_owner
• stop_conditions
• lane_map

Workflow-local judgment does not replace the shared readiness or delegation contract in workflows/references/delegation-contract.md.

Core principles (extracted from 30+ practical sessions)

1. Not repairing is more important than repairing indiscriminately — Each finding must be classified as FIX / SKIP / DEFER, and SKIP must be accompanied by a reason
2. Scan Dimension Rotation — Don’t just look for the same type of problems every time, rotate scans by dimension.
3. Atomic Verification — Each fix is independently verified and is not run until the end.
4. Experience Persistence — Write the pitfalls you have stepped on into MEMORY.md to avoid repeated mistakes across sessions
5. Guard Priority — Run VibeGuard deterministic guard first to obtain the baseline, and then use LLM deep scanning

Scan dimensions (rotate by round)

Round	Dimension	Scan Target
1	Bug	Logic errors, deadlocks, TOCTOU, panic paths, boundary conditions
2	Architecture	Naming conflicts, confusion of responsibilities, module coupling, type design defects
3	Duplication	Code duplication, extractable common logic, copy-paste traces
4	Performance	Unnecessary clone/alloc, O(n2) paths, blocking calls
5	Testing	Missing coverage, fragile assertions, missing edge cases
6	API	Functional gaps, usability issues, and lack of documentation in competing products
7	Consistency	Multi-entry data path convergence, environment variable unification, configuration default value alignment, shared state schema consistency

The user can specify the dimensions, otherwise the most needed dimensions will be automatically selected based on the current status of the project.

Complete process

Phase 1: Exploration and Assessment (Integrating VibeGuard)

1. Confirm the target project path (user-provided or current directory)
2. In-depth exploration project:
   • Read README, CLAUDE.md and other project specifications
   • Analyze project structure, technology stack, and dependencies
   • Read the core source code and understand the architecture
   • Check TODO/FIXME, #[allow(dead_code)] and other tags
3. Run VibeGuard to get a baseline (select by project language):

   # Directly call the guard script
   for guard in guards/python/check_*.sh; do bash "$guard" /path/to/project; done
   for guard in guards/rust/check_*.sh; do bash "$guard" /path/to/project; done
   

4. Scan in parallel according to the current dimension only after creating delegation assignments with task_slice, allowed_files, forbidden_files, authority, required_evidence, blocker_conditions, and integration_owner
5. Merge guard results + LLM scan results, output the evaluation report to the user, and confirm the optimization direction

Phase 2: Classification and design (comply with VibeGuard specification)

Classify each finding into three categories:

FIX — Have a clear plan, don’t break the public API, benefits > risks
SKIP — with reasons: breaking change / over-engineering / not a bug / intentional design
DEFER — More information or user decisions are required, logged in the backlog area of TASKS.md

SKIP judgment criteria (load the rules of the corresponding language in the rules/ directory + VibeGuard specifications):

• Breaking public API signature → SKIP (unless user explicitly asks for breaking change)
• Only 1 use of "duplicate" → SKIP (extracting abstractions is over-engineering - VibeGuard Layer 5 minimal changes)
• Similar code with different semantics → SKIP (such as Span inline style vs Text global style)
• Macros can solve it but will reduce readability → SKIP
• Do not search for existing implementations before creating new files/classes/functions → Violates VibeGuard Layer 1, search first and then write

FIX tasks are sorted by dependencies and generate a structured task list:

## High priority
- [ ] [BUG] Description | Documentation | Solution Summary
- [ ] [BUG] ...

## Medium priority
- [ ] [DEDUP] Description | Documentation | Solution Summary
- [ ] [DESIGN] ...

## Architecture review (triggered after high/medium completion)
- [ ] [ARCH] Comprehensively review the rationality of the architecture, and add new tasks if problems are found

## Low priority
- [ ] [STYLE] ...

## Backlog（DEFER）
- [ ] [DEFER] Description | Required information

Phase 3: Create Runner environment

1. Commit the current status and create a new branch in the target project (such as auto-optimize)
2. Create the runner directory structure:

<runner-dir>/
├── memory/
│ ├── TASKS.md # Task list for Phase 2 design
│ ├── CONTEXT.md # Project background, technology stack, specifications, architecture overview
│ └── DONE.md # Automatically generated
├── workspace/ # Soft link to the target project
├── logs/
└── config.yaml

3. CONTEXT.md must contain:

   • Project overview and technology stack
   • Architecture overview (key modules and responsibilities)
   • Project specifications (reference the project's own CLAUDE.md or coding specifications)
   • VibeGuard specification reference (remind workers to abide by the rules of search before writing, naming constraints, minimum changes, etc.)
   • Build and test commands (must be verified after every modification)
   • Commit specifications (if there are DCO requirements, etc.)
   • Current scanning dimensions and round records

4. config.yaml default configuration:

max_iterations: 50
max_cost_usd: 0
max_duration: 6h
consecutive_no_progress: 3
stop_when_empty: true
cooldown_duration: 15s
worker_timeout: 30m
use_git_detection: true

5. Default path of runner directory: ~/<project-name>-runner/

Phase 4: Execution and Verification

Prerequisite Check: The AUTO_RUN_AGENT_DIR environment variable must be set and the directory must exist.

# Detect auto-run-agent
if [[ -z "${AUTO_RUN_AGENT_DIR:-}" ]]; then
  echo "AUTO_RUN_AGENT_DIR is not set, skip Phase 4"
  echo "Setting method: export AUTO_RUN_AGENT_DIR=/path/to/auto-run-agent"
  exit 0
fi

1. Start using auto-run-agent:

cd "${AUTO_RUN_AGENT_DIR}"
./orchestrator --dir <runner-dir> --max-iterations 50 --max-cost 0 --max-duration 6

2. Worker execution rules:
   • Run verification command (read from CONTEXT.md) immediately after each fix is completed
   • Verification failed → Roll back the fix immediately, mark it as DEFER, and continue with the next one
   • Verification passed → commit, marked as DONE, update DONE.md
   • Every time a fix is completed, check whether a new problem is triggered (regression detection)
3. Monitoring commands:
   • tail -f <runner-dir>/logs/orchestrator_*.log — real-time log
   • cat <runner-dir>/memory/DONE.md — View completion records
   • cat <runner-dir>/memory/TASKS.md — View remaining tasks

Note: Phase 1-3 does not depend on auto-run-agent and can be used independently in an agent-less environment (manually execute TASKS.md).

Phase 5: Closing and Learning (VibeGuard Compliance Check)

1. After all FIX are completed, run the full test suite
2. Run VibeGuard Compliance Check:

   bash "${VIBEGUARD_ROOT:-$(dirname "$0")/../..}/scripts/verify/compliance_check.sh" /path/to/project
   

3. Fix the problems found in the compliance check (if any)
4. bump version（patch for fixes, minor for new features）
5. Update the project MEMORY.md to record the patterns and lessons discovered in this round
6. Record the scanning dimensions of this round and automatically switch to the next dimension next time

Rule system

Rule files are located in the rules/ directory and are organized by language. Rules corresponding to the language are automatically loaded during scanning.

auto-optimize/
├── SKILL.md
└── rules/
    ├── universal.md ← Universal rules (applicable to all languages)
    ├── python.md ← Python-specific rules (with VibeGuard cross-references)
    ├── rust.md ← Rust-specific rules
    ├── typescript.md ← TypeScript specific rules
    └── go.md ← Go specific rules

Rule format: Each rule has ID, category, description, and example. Workers refer to these rules to determine FIX/SKIP when scanning and repairing.

Relationship to VibeGuard guards/:

• guards/ = deterministic detection tool (AST script, integrated into CI/pre-commit)
• rules/ = LLM scanning reference (Markdown, guides workers to determine FIX/SKIP/DEFER)
• Overlapping parts (such as PY-02 naked exceptions) are processed through cross-reference and are not merged

User interaction points

• After the completion of Phase 1, the evaluation report (including guard baseline + LLM scan results) must be shown to the user to confirm the optimization direction
• The task list of Phase 2 is displayed to the user for confirmation before creating the file.
• Ask the user before starting: number of iterations, time limit, and whether there is a cost limit
• Users can edit TASKS.md at any time to insert new tasks or adjust priorities

Notes

• AUTO_RUN_AGENT_DIR environment variable specifies the auto-run-agent path, Phase 4 runtime detection
• The target project must be committed cleanly before branching to ensure that it can be rolled back
• Workspace uses soft links and does not copy code
• Multiple projects can run at the same time without affecting each other (note the API rate limit)

Red Flags

• Optimizing without a baseline - improvements cannot be trusted if the current guard/test state was not recorded first.
• Implementing low-priority cleanup first - security and correctness findings take priority over style cleanup.
• Creating tasks from stale notes - old research must be checked against current files before becoming work.
• Skipping user confirmation - optimization direction must be confirmed before files are created or edited.

Checklist

• Record the selected scan dimensions and current baseline.
• Search for existing fixes, plans, and guard coverage before proposing new tasks.
• Prioritize by security, logic, and data integrity before maintainability.
• Show the optimization report before Phase 2 task creation.
• Attach focused verification commands to every implemented finding.