Evolve CLI Subsystem (@huutq88/evolve)

Purpose: Production-grade Command-Line Interface for initializing Evolve Multi-Agent SDLC, auditing architecture boundaries, managing lifecycle gates (G0 - G7), bootstrapping isolated POCs, and executing safe version upgrades.

Installation & Quick Start

Run via npx (No installation needed)

npx @huutq88/evolve init

Install Globally

npm install -g @huutq88/evolve

Command Reference

1. evolve init

Initializes a target repository with the full Evolve Multi-Agent SDLC framework:

• Creates .evolve/project.yaml and .evolve/baseline.yaml
• Installs 5 Multi-Agent Roles (.agents/agents/{architect,implementer,reviewer,critic,verifier})
• Installs Evolve Workflows (.agents/workflows/evolve.md, etc.) and Skill (.agents/skills/evolve/SKILL.md)
• Installs 9 Core Architecture Rules (.agents/rules/*.md)
• Creates Root AGENTS.md engineering protocol
• Prepares task documentation directories (docs/adr, docs/plans, docs/requirements, docs/reviews)

# Initialize current directory
evolve init

# Specify project name and target directory
evolve init --name my-project --target /path/to/repo

# Overwrite existing initialization
evolve init --force

2. evolve status

Displays the real-time project lifecycle status, visual checklist of Gates (G0 - G7), and determines the active Operating Mode.

evolve status

Example Output:

=== Evolve SDLC Status ===

Project:   my-app
Version:   1.0.0
Stage:     requirements
Spec Ver:  v2

── Architecture Gate Matrix ──
  ✔ G0 Requirements      [PASSED]  → REQUIREMENTS.md
  ✔ G1 Boundary Skeleton [PASSED]  → ARCHITECTURE-SKELETON.md
  ○ G2 Risk Analysis     [PENDING] → RISK-ANALYSIS.md
  ○ G3 POC Plan          [PENDING] → POC-PLAN.md
  ○ G4 POC Evidence      [PENDING] → POC-REPORT.md
  ○ G5 Production Arch   [PENDING] → PRODUCTION-ARCHITECTURE.md
  ○ G6 Baseline Lock     [PENDING] → ARCHITECTURE-BASELINE.md
  ○ G7 Evolution Gate    [PENDING] → IMPACT-ANALYSIS.md

── Operating Mode Assessment ──
ℹ Recommended Mode: RISK → Evaluate technical risk (Gate G2)

3. evolve check

Validates .evolve manifests, checks that all 5 multi-agent roles exist, and performs AST/source code scans under src/ to detect forbidden boundary violations (e.g. src/core directly importing vendor SDKs or DB drivers).

evolve check

4. evolve audit

Runs an automated architecture health audit across 5 dimensions:

1. Multi-Agent Setup & Governance Rules (20 pts)
2. Evolve Manifests & Baseline Lock (20 pts)
3. Clean Layer Boundary Separation (20 pts)
4. Task Artifacts & Documentation (20 pts)
5. Test Seams & Verification Infrastructure (20 pts)

Computes the Architecture Health Score (0 - 100) and assigns an evolution readiness Tier (A, B, C, D).

evolve audit

5. evolve poc --name <experiment-name>

Bootstraps an isolated Proof of Concept workspace under poc/<experiment-name>/ with a pre-configured POC-PLAN.md template (Gate G3) and marks Gate G3 in_progress.

evolve poc --name mobile-clip-search

6. evolve productionize

Transitions passed POC findings into production architecture readiness (Gate G5):

• Prepares layer topology directories in src/ (core, contracts, providers, application, ui)
• Generates PRODUCTION-ARCHITECTURE.md
• Marks Gates G3 & G4 as passed and Gate G5 as in_progress.

evolve productionize

7. evolve upgrade <version>

Initializes a major version evolution workflow (e.g. V1 → V2 / V3) at Gate G7:

• Generates docs/plans/upgrade-<version>-impact.md with the 8 Rewrite Protection Criteria.
• Generates docs/plans/upgrade-<version>-migration.md with the 7-step incremental migration plan.
• Prepares dual-run / adapter compatibility markers.

evolve upgrade v2