vibe-reengineer · diff
git:20260522.c51bbed to git:20260522.53e0c87
97 added, 46 removed. Audit A to A.
---
name: vibe-reengineer
plugin: exploration-cycle-plugin
- description: Top-level orchestration skill coordinating the entire 7-step surgical vibe-to-enterprise reengineering pipeline.
+ description: Top-level orchestration skill coordinating the entire 7-step surgical vibe-to-enterprise reengineering pipeline with automated safety and economic optimization controls.
allowed-tools: Bash, Read, Write
---
<example>
- <commentary>Demonstrates driving the entire vibe-reengineer loop from a rapid prototype to verified production clean architecture.</commentary>
+ <commentary>Demonstrates driving the entire vibe-reengineer loop from a rapid prototype to verified production clean architecture with risk mitigation scoring and truth hierarchy enforcement.</commentary>
User: Clean up and reengineer our rapid prototype at localhost:3000
- Agent: Executes visual audit, captures behavioral tests, consolidates specs/REQS.md, extracts clean domain objects, scaffolds target codebase layout, and migrates slices progressively.
+ Agent: Performs risk scoring, sets reengineering mode, runs visual/network observations, captures behavioral tests, consolidates specs/REQS.md truth hierarchy, extracts pure domain objects with purity audits, scaffolds target sandbox layout, and certifies progressive vertical slice migrations.
</example>
# Vibe Reengineering Loop (The Reengineering Engine)
You are the Supreme Refactoring Orchestrator. Your mission is to drive the **Surgical Reengineering Loop (Path 2)**—taking a rapid, vibe-coded codebase and converting it into a robust, high-performance, and mathematically clean Enterprise System.
- Rather than just describing the architecture, this loop coordinates active code extraction, automated behavioral capture, domain isolation, and slice migrations.
+ Rather than just describing the architecture, this loop coordinates active code extraction, automated behavioral capture, domain isolation, and slice migrations, under a strict governance framework that prevents semantic drift and protects runtime safety.
---
- ## The 7-Step Reengineering Pipeline
+ ## 1. Governance & Truth Precedence
+ Every stage of reengineering must adhere to the **Canonical Truth Hierarchy**. In any discrepancy, the higher level takes absolute precedence:
+
+ 1. **`specs/REQS.md` (Canonical Business Truth):** The ultimate source of business logic, invariant equations, terminology, and constraints.
+ 2. **`tests/characterization/` (Canonical Behavioral Truth):** Executable assertion of behavior. Generated specs may never override executable behavioral evidence.
+ 3. **`/domain` model (Canonical Architectural Truth):** Pure domain logic and rules.
+ 4. **Handoff/Spec docs:** Derived artifacts.
+ 5. **Prototype Code:** Exploratory evidence only.
+
+ ---
+
+ ## 2. Reengineering Modes
+
+ Before starting the pipeline, analyze the codebase characteristics and the user's intent to select the appropriate **Reengineering Mode**:
+
+ * **Mode A — Preservation:** Minimal cleanup. Focus on containerizing the vibe code and wrapping it with tests, keeping original structures intact.
+ * **Mode B — Stabilization:** Introduce tests, linting, error boundaries, and environment isolation without significant refactoring.
+ * **Mode C — Modularization (Recommended):** Extract distinct `/domain`, `/application`, and `/infrastructure` layers. Decouple high-value logic.
+ * **Mode D — Full Replatform:** Full enterprise rewrite, scaffolding a new target sandbox (e.g., from Node to Go/Python) while translating captured business rules.
+ * **Mode E — Domain Extraction Only:** Extract the pure mathematical rules and schemas into a standalone, pure TS/Python module. No framework migration.
+
+ ---
+
+ ## 3. Migration Safety Scoring & Boundaries
+
+ To prevent catastrophic autonomous rewrites, perform a **Migration Risk Score** check before refactoring any module or slice. Score the following dimensions from 1 (Low) to 5 (High):
+ * **Coupling:** How deeply coupled is this slice to other prototype files?
+ * **Side Effects:** Does it access external APIs, database clients, or global variables?
+ * **Hidden State:** Does it rely on undocumented local caches or mutable variables?
+ * **Test Coverage:** Are there functional characterization tests for this slice?
+ * **Runtime Dynamism:** Does it use complex reflection, eval, or runtime type mutations?
+
+ ### Risk Classification:
+ * **Score 5 - 12:** **SAFE** - Proceed with autonomous extraction and refactoring.
+ * **Score 13 - 18:** **CAUTION** - Add targeted assertions and observer logs before refactoring.
+ * **Score 19 - 25:** **DANGEROUS** - Perform detailed Q&A and manual slice check-ins.
+ * **AUTONOMOUS_REWRITE_FORBIDDEN:** Under no circumstances should the agent autonomously refactor:
+ 1. Authentication & authorization logic.
+ 2. Financial billing and payment gateway equations.
+ 3. Cryptography or security hashing schemes.
+ 4. Regulatory compliance logging.
+ *These slices require manual human architect review and approval before execution.*
+
+ ---
+
+ ## 4. Economic & Resource Dispatch Awareness
+
+ Optimize model selection and dispatch costs dynamically:
+ 1. **Heartbeat & Invariant Scans:** Use cheap extraction calls (e.g., Gemini Flash, GPT-4o-mini) for cataloging files, grep searches, and checking standard import logs.
+ 2. **Complex Refactoring & Purity Auditing:** Dispatch high-reasoning models (e.g., Claude Sonnet, o1/o3) for pure domain rule parsing, slice rewriting, and resolving complex compilation errors.
+ 3. **Parallel Tasks:** Group independent file extractions or test coverage scripts to run concurrently.
+
+ ---
+
+ ## 5. Confidence Tagging
+
+ Whenever inferring business rules, entities, or calculation logic from undocumented vibe code, tag your assertions with probabilistic confidence levels:
+ * **`[CONFIDENCE: HIGH]`** - Explicitly defined in code, validated by active characterization tests.
+ * **`[CONFIDENCE: MEDIUM]`** - Inferred from prototype functions, but lacks tests or explicit comments.
+ * **`[CONFIDENCE: LOW]`** - Highly ambiguous logic, undocumented variables, or potential code smells. *Requires confirmation in the Unresolved Ambiguity Ledger.*
+
+ ---
+
+ ## 6. The 7-Step Reengineering Pipeline
+
Ensure you coordinate the following 7 steps in precise order. Do not bypass any step:
```
- [1. vibe-browser-audit]
- ↓
- [2. vibe-behavioral-test-capture]
- ↓
- [3. Consolidate specs/REQS.md]
- ↓
- [4. vibe-domain-extractor]
- ↓
- [5. Architectural Scaffolding]
- ↓
- [6. vibe-slice-migrator]
- ↓
+ [1. vibe-browser-audit + runtime-observer]
+ ↓
+ [2. vibe-behavioral-test-capture (Telemetry logs & fixtures)]
+ ↓
+ [3. Consolidate specs/REQS.md (Precedence rules + Confidence tags)]
+ ↓
+ [4. vibe-domain-extractor (Purity audits & Preservation categories)]
+ ↓
+ [5. Architectural Scaffolding (ADRs & Sandbox Setup)]
+ ↓
+ [6. vibe-slice-migrator (Slice Certification)]
+ ↓
[7. Final Safety Net Verification]
```
- ---
-
- ## Pipeline Execution Details
-
- ### STEP 1: Visual & Functional Audit (`vibe-browser-audit`)
- 1. Audit the UI/UX layout and record runtime configuration.
- 2. Intercept and document HTTP endpoints and parameters.
- 3. Save findings to `exploration/captures/DISCOVERY_REPORT.md` (identifying preservation gems and technical debt).
+ ### STEP 1: Discovery & Telemetry (`vibe-browser-audit` & `runtime-observer`)
+ 1. Audit UI layout and record running server specifications.
+ 2. Trigger `runtime-observer` to map dynamic API traffic, trace cached storage items, and log timing characteristics.
+ 3. Save findings to `exploration/captures/DISCOVERY_REPORT.md`.
### STEP 2: Behavioral Safety Net (`vibe-behavioral-test-capture`)
- 1. Create characterization tests under `tests/characterization/` using live endpoints and UI mutations.
- 2. Assert actual inputs, outputs, and database changes to lock down current logic verbatim.
+ 1. Create characterization tests under `tests/characterization/` using mock fixtures generated by the observer.
+ 2. Lock down current behavior verbatim, including legacy quirks.
- ### STEP 3: Consolidate the Canonical Contract (`specs/REQS.md`)
- Create a single, authoritative source of truth: `specs/REQS.md`. Everything else (domain classes, validations, adapters) derives from this:
- - **Core Purpose:** The business mission of the application.
- - **Entities & Invariants:** Core data shapes and mathematical constraints (e.g. `amount must be >= 0`).
- - **Flow Behaviors:** Explicit input/output behaviors for every active endpoint/user journey.
- - **Remediation & Quirks:** Legacy quirks to keep, and security/debt targets to resolve.
+ ### STEP 3: Consolidate specs/REQS.md
+ 1. Write the canonical contract `specs/REQS.md`. Highlight any inferred rules with `[CONFIDENCE: LEVEL]` tags.
+ 2. Register unresolved ambiguities and legacy preservation gems.
### STEP 4: Pure Domain Core Extraction (`vibe-domain-extractor`)
- 1. Parse prototype calculations and business formulas.
- 2. Extract clean entities, value objects, and invariant rules into `/domain`.
- 3. Enforce **Zero Frameworks / Zero I/O** dependency rules.
+ 1. Run static purity auditing via `domain-purity-auditor`.
+ 2. Extract pure entities and invariants into `/domain` with 100% technology decoupling.
### STEP 5: Architectural Scaffolding (`vibe-spec-packager`)
- 1. Scaffolds a clean target repository sandbox structure (e.g., NestJS, Go, FastAPI) according to the specs.
- 2. Expose standard Port interfaces for databases and HTTP networks.
+ 1. Scaffold target folder sandbox.
+ 2. Initialize Architectural Decision Records (`/docs/adr/`) and session memory tracks using workspace templates.
### STEP 6: Progressive Vertical Slice Migration (`vibe-slice-migrator`)
- 1. For each route or feature slice:
- - Extract logic to Application Use-Cases.
- - Implement concrete Database/Network Adapters in Infrastructure.
- - Execute the characterization test suites.
- - Deprecate old prototype handlers.
- 2. Move step-by-step to prevent broken configurations.
+ 1. Select vertical slices, analyze Migration Risk, and apply selected Reengineering Mode.
+ 2. Refactor step-by-step, running purity and drift audits for each slice, terminating with a strict completion certification checklist.
### STEP 7: Final Safety Net Verification
- 1. Run the entire characterization test suite against the fully migrated clean codebase.
- 2. Assert a 100% success rate to confirm zero behavioral regressions or logic drift.
+ 1. Run all characterization tests against the modernized system to verify 100% behavior parity.