Saltar a contenido

RE-Wizard

Plugin de ingenieria inversa cientifica de software para Claude Code. Analiza cualquier codebase y produce documentacion estructurada — desde el reconocimiento inicial hasta Feature Specs compatibles con ATL Inteliside. Dirigido a equipos que necesitan reimplementar, extraer modulos o mejorar proyectos open-source sin documentacion previa.

Prerequisitos

  • Claude Code instalado
  • Acceso de lectura al codebase objetivo
  • GitHub CLI autenticado (solo necesario en Phase 4, si se crean milestones/issues)
  • Engram conectado como plugin (para persistencia entre fases)
  • Para pipeline completo RE a ATL: plugin atl-inteliside habilitado
# Plugin individual
claude --plugin-dir ./plugins/re-wizard

# Con ATL para pipeline completo (RE -> ATL)
claude --plugin-dir ./plugins/re-wizard --plugin-dir ./plugins/atl-inteliside

Skills

RE-Wizard expone un unico skill que orquesta todo el pipeline de analisis. El skill opera en modo context: fork para no contaminar la conversacion principal, usa modelo opus para razonamiento profundo, y requiere invocacion manual (disable-model-invocation: true).

Skill Descripcion Invocacion Tools permitidos
reverse-engineer Ingenieria inversa cientifica con 3 modos: Full RE, Module Extraction, Fork & Enhance. Genera documentacion por fases y Feature Specs ATL. /reverse-engineer [path-to-codebase] Read, Glob, Grep, Bash, Write, Edit, Agent

Agentes

RE-Wizard delega el trabajo pesado de cada fase a 5 agentes especializados. Cada agente opera en aislamiento, con herramientas restringidas y un limite de turnos para prevenir loops. Los agentes de analisis (fases 0-3) son de solo lectura; el agente de sintesis (fase 4) tambien escribe los documentos finales y persiste a Engram.

Agente Rol Modelo Tools maxTurns
re-wizard-recon Phase 0: Reconocimiento. Escanea estructura, detecta stack, cuenta LOC, inventaria dependencias. sonnet Read, Glob, Grep, Bash 40
re-wizard-structure Phase 1: Analisis estructural. Dependencias entre modulos, modelo de datos, endpoints API, patrones de diseno. sonnet Read, Glob, Grep, Bash 50
re-wizard-functional Phase 2: Analisis funcional. Features, user flows, reglas de negocio, roles y permisos. sonnet Read, Glob, Grep, Bash 50
re-wizard-domain Phase 3: Analisis de dominio. Proposito del sistema, NFRs, deuda tecnica, oportunidades de mejora. sonnet Read, Glob, Grep, Bash 40
re-wizard-synthesis Phase 4: Sintesis. Consolida todo en Master Spec, guias y Feature Specs ATL. Persiste a Engram. opus Read, Glob, Grep, Write, Bash 60

Notas sobre agentes:

  • re-wizard-recon usa isolation: worktree (sandbox aislado de git).
  • re-wizard-synthesis tiene memory: user — aprende patrones de analisis previos para mejorar Feature Specs futuros.
  • El README actual del plugin NO menciona los 5 agentes; esta documentacion refleja el estado real.

Flujo de trabajo

El pipeline sigue un orden secuencial de 5 fases mas seleccion de modo y entrega final:

  1. Step 1 — Seleccion de modo: El usuario elige entre 3 modos:
  2. Mode 1 (Full RE): Codebase completo sin documentacion, para reimplementar o refactorizar.
  3. Mode 2 (Module Extraction): Extraer un modulo especifico para adaptar a otro proyecto.

  4. Mode 3 (Fork & Enhance): Mejorar proyecto MIT/open-source con atribucion.

  5. Phase 0 — Reconnaissance (agente re-wizard-recon): Escaneo de directorio, deteccion de stack, inventario de dependencias, localizacion de docs y tests, metricas de LOC. Output: 00-RECONNAISSANCE.md.

  6. Phase 1 — Structural Analysis (agente re-wizard-structure): Arquitectura, capas, modelo de datos, endpoints API, patrones de diseno, auth, middleware. Output: 01-ARCHITECTURE.md, 02-DATA-MODEL.md, 03-API-SPEC.md.

  7. Phase 2 — Functional Analysis (agente re-wizard-functional): Features, user flows, reglas de negocio, validaciones, roles, procesos background. Output: 04-FEATURES.md, 05-USER-FLOWS.md, 06-BUSINESS-RULES.md.

  8. Phase 3 — Application Analysis (agente re-wizard-domain): Dominio de negocio, stakeholders, NFRs inferidos, decisiones arquitectonicas, deuda tecnica, limitaciones. Output: 07-SYSTEM-OVERVIEW.md.

  9. Phase 4 — Specification Synthesis (agente re-wizard-synthesis): Consolidacion de todo en documentos finales segun modo:

  10. Mode 1: 08-MASTER-SPEC.md, 09-REIMPLEMENTATION-GUIDE.md
  11. Mode 2: 08-MODULE-SPEC.md, 09-ADAPTATION-GUIDE.md
  12. Mode 3: 08-MASTER-SPEC.md, 09-ENHANCEMENT-PLAN.md

  13. Todos: 10-ATL-FEATURE-SPECS/feat-*.md, 11-ATL-MILESTONE-PLAN.md

  14. Step 7 — Final Delivery: Resumen con estadisticas, lista de documentos, proximos pasos para ATL.

Todos los documentos se generan en ./re-wizard-output/ por defecto.

Contratos de datos

Engram

RE-Wizard usa el mismo proyecto Engram que el resto del ecosistema ({nombre-proyecto}-dev). Los topic keys propios usan prefijo re-wizard/{analysis-id}/, y los de handoff a ATL usan project/* con formato identico a SDD-Wizards.

Topic keys propios (duracion del analisis):

topic_key Writer Contenido
re-wizard/{id}/config Step 1 Modo, paths, goals, stack target
re-wizard/{id}/recon Phase 0 Stack, estructura, metricas
re-wizard/{id}/architecture Phase 1 Patron arquitectonico, capas, patrones
re-wizard/{id}/data-model Phase 1 Modelo de datos, relaciones, indices
re-wizard/{id}/api-spec Phase 1 Endpoints con metodos, params, auth
re-wizard/{id}/features Phase 2 Inventario de features con complejidad
re-wizard/{id}/user-flows Phase 2 Roles, permisos, flujos por feature
re-wizard/{id}/business-rules Phase 2 Reglas con trazabilidad file:line
re-wizard/{id}/system-overview Phase 3 Dominio, NFRs, deuda, ADRs
re-wizard/{id}/synthesis-status Phase 4 Resumen: features procesadas, specs generados

Topic keys de handoff a ATL (compatibilidad total con SDD-Wizards):

topic_key Writer Leido por
project/features/{feature-name} Phase 4 ATL sdd-from-github
project/features-index Phase 4 ATL, SDD-Intake
project/github-context Phase 4 (si crea milestones) ATL sdd-from-github
project/stack Phase 0 ATL sdd-init

Reglas de convivencia: RE-Wizard nunca escribe a prefijos sdd/, team/, legacy/, intake/. Si project/features/{name} ya existe (de SDD-Wizards), no sobreescribe — pide confirmacion al usuario.

GitHub

RE-Wizard interactua con GitHub solo en Phase 4 (Synthesis), y solo tras confirmacion explicita del usuario. Crea labels, milestones e issues con Feature Specs siguiendo las mismas convenciones que SDD-Wizards para compatibilidad total con ATL.

Labels creados (idempotentes):

Label Color Proposito
feature-spec #1d76db Issue contiene Feature Spec
atl-ready #0e8a16 Feature lista para ATL
re-wizard #7057ff Generado por RE-Wizard (trazabilidad)

Milestones: Formato feat-{kebab-case-name}, creados por wave segun 11-ATL-MILESTONE-PLAN.md.

Issues: Titulo Feature Spec: {Name}, labels feature-spec,atl-ready,re-wizard, body con contenido del Feature Spec completo.

Contrato completo en plugins/re-wizard/docs/github-re-wizard-contract.md.

Configuracion para proyectos

Agregar al CLAUDE.md del proyecto que recibira output de RE-Wizard:

## ATL Inteliside

engram_project: "{project-name}-dev"
github_owner: "{org-or-user}"
github_repo: "{repo-name}"

Despues del analisis, los Feature Specs en ./re-wizard-output/10-ATL-FEATURE-SPECS/ son input directo para ATL:

# 1. Revisar documentacion generada
# 2. Crear milestones en GitHub segun 11-ATL-MILESTONE-PLAN.md
# 3. Ejecutar ATL por feature
/sdd-from-github feat-{name}

Template completo en plugins/re-wizard/examples/CLAUDE.md.

Integracion con Doc-Gen

Despues de completar la ingenieria inversa y generar Feature Specs, se recomienda correr doc-gen para mantener la documentacion del proyecto actualizada.

Cuando Comando
Despues de completar el analisis RE /doc-gen:doc-proyecto
Verificacion periodica /doc-gen:doc-sync

Limitaciones conocidas

  1. Soporte de lenguajes limitado: Las guias de lenguaje actuales cubren solo JavaScript/TypeScript y Python. Las guias de framework cubren solo Next.js y Django. Otros stacks funcionan pero sin heuristicas especializadas.

  2. Codebase muy grandes: RE-Wizard recomienda acotar el alcance o cambiar a Mode 2 (Module Extraction) para codebases de mas de 500K LOC.

  3. Solo codigo fuente: RE-Wizard necesita acceso al codigo fuente. Binarios compilados o proyectos sin fuente no son compatibles.

  4. No modifica codigo: El plugin es estrictamente de lectura sobre el codebase analizado. Solo escribe en el directorio de output.

  5. Metodologia academica: Basado en Chikofsky & Cross (IEEE 1990), Horseshoe Model (Kazman et al., SEI/CMU 1998), 5 Abstraction Levels (Koschke et al.) e IEEE 8-step RE process.

Inventario de archivos de referencia

El skill reverse-engineer incluye 26 archivos de referencia organizados en subcarpetas:

  • references/methodology.md — Fundamento cientifico
  • references/modes.md — Comportamiento por modo
  • references/phase-0-recon.md a references/phase-4-synthesis.md — Instrucciones detalladas por fase
  • references/language-guides/ — javascript-ts.md, python.md
  • references/framework-guides/ — nextjs.md, django.md
  • references/output-templates/ — 12 templates (00-reconnaissance a 11-atl-milestone-plan)
  • scripts/ — 5 scripts helper: scan-project.sh, detect-stack.sh, extract-schemas.sh, extract-routes.sh, generate-mermaid.sh