Vista Legacy

Reverse-engineer an existing codebase into Vista planning artifacts (domain requirements + architecture diagrams), or convert old-format Vista features into the current /arch planning schema.

Invocation

/vista:legacy <feature-name>

Use Cases

• •Onboarding a feature that was built without Vista planning
• •Documenting an existing system for handoff or review
• •Creating a baseline before extending a feature with /vista:add
• •Converting old Vista features that have inline plan JSON sections (uiFlows, dataModels, dataFlow, services) into the new arch/ directory format with native .mmd diagrams

Workflow

Step 1: Scaffold Directory

Create the feature directory if it doesn't exist:

python vista/scripts/setup-feature.py --name $ARGUMENTS

If the directory already exists, proceed. Existing files won't be overwritten.

Step 2: Scan Existing Artifacts and Detect Mode

Check .vista/features/<name>/ for pre-existing documentation:

• •domain-requirements.md — Domain requirements (may be template-only)
• •arch/_arch.json — Architecture manifest (may be empty)
• •arch/*.mmd — Any existing diagrams
• •specs/*.md — Any specification documents
• •IMPLEMENTATION_PLAN.md — Implementation plan (may be template-only)
• •<name>_plan.json — Old-format plan JSON (check for inline architecture sections)
• •<name>_prd.json — Old-format PRD JSON
• •AGENTS.md — Old build agent config (deprecated)

Report what was found.

Detect mode: If the feature directory contains a <name>_plan.json with any of these inline sections — uiFlows, dataModels, dataFlow, services — this is an old-format Vista feature that needs conversion. Follow Path A: Convert Old Vista Feature below.

Otherwise, this is a fresh reverse-engineering task. Follow Path B: Reverse-Engineer from Source Code.

Path A: Convert Old Vista Feature

Use this path when a <name>_plan.json exists with inline architecture sections.

Step A1: Extract Architecture from Plan JSON

Read <name>_plan.json and extract data from the inline sections:

Also read <name>_prd.json if present — it may contain additional context (success criteria, test scenarios, functional requirements) that enriches diagram generation.

Step A2: Generate Architecture Diagrams from Extracted Data

Convert the extracted sections into native Mermaid .mmd files in arch/:

Follow the same Mermaid conventions as /vista:plan Step 3:

• •Use clear, descriptive node labels
• •Include notes where relationships are non-obvious
• •Group related elements with subgraphs where helpful
• •Keep diagrams focused — one concern per diagram

Set all diagram descriptions to note they are "converted from old-format plan JSON" so reviewers know the source.

Step A3: Write Architecture Manifest

Write arch/_arch.json referencing all generated diagrams (conforming to vista/templates/arch-schema.json):

{
  "feature": "<name>",
  "diagrams": [
    {
      "name": "System Architecture",
      "file": "system-architecture.mmd",
      "type": "mermaid",
      "diagramType": "flowchart",
      "category": "architecture",
      "description": "System components and relationships (converted from old-format plan JSON)"
    }
  ]
}

Step A4: Update Plan JSON

Update the <name>_plan.json to reference the new arch directory:

1. •Add an architecture section with "ref": "./arch/_arch.json"
2. •Remove the old inline sections: uiFlows, dataModels, dataFlow, services
3. •Keep meta and implementationPhases intact

The updated plan JSON should conform to vista/templates/plan-schema.json.

Step A5: Clean Up Deprecated Files

Check for and remove deprecated artifacts:

• •AGENTS.md — Old build agent config, no longer used
• •<name>_preview.html — Old preview file (the web dashboard replaces this)

Ask the user before deleting anything.

Step A6: Backfill Domain Requirements (if needed)

If domain-requirements.md is template-only or sparse, enrich it using data from:

1. •PRD JSON (<name>_prd.json) — Extract user stories, success criteria, functional requirements
2. •Plan JSON — Infer requirements from the implementation phases and old inline sections
3. •Source code — Scan the codebase for additional context (same approach as Path B Step 3)

Mark any inferred content as "backfilled from old-format artifacts."

Step A7: Review and Next Steps

Discover the dashboard URL by calling the ralph_providers MCP tool and reading dashboard_url from the response.

Tell the user:

1. •

   Conversion complete — summarize what was converted:

   • •Which diagrams were generated from which plan JSON sections
   • •What was removed from the plan JSON
   • •What deprecated files were cleaned up
2. •

   Review diagrams in the web dashboard:

   code

   <dashboard_url>/project/<project-id>/arch/<feature-name>
   

   Use the AI chat panel to discuss and iterate on diagrams.

3. •

   Pay special attention to:

   • •Whether the converted diagrams accurately represent the original inline data
   • •Missing relationships that were implicit in the old format
   • •Opportunities to add diagrams that the old format didn't capture
4. •

   Next steps:

   • •Edit diagrams and domain-requirements.md to fix inaccuracies
   • •/vista:tdd <name> — Generate TDD diagrams for heavy-logic components
   • •/vista:specs <name> — Generate or regenerate specifications
   • •/vista:add <name> — Extend the feature with new capabilities

Path B: Reverse-Engineer from Source Code

Use this path when no old-format plan JSON exists (or it has no inline architecture sections).

Step B1: Scan Source Code

Use subagents to scan the actual codebase for implementation artifacts. Search for:

Data Models / Entities:

• •Database models, schemas, migrations
• •TypeScript/Python/etc. type definitions and interfaces
• •ORM model classes

Services / Business Logic:

• •Service classes and modules
• •API route handlers
• •Business logic functions
• •External service integrations

UI Components:

• •Page/screen components
• •Form components
• •Navigation and routing definitions
• •State management

Data Flow:

• •API endpoint definitions
• •Event handlers and message queues
• •Database queries and mutations
• •External API calls

Ask the user for guidance on where to look if the codebase structure is unclear.

Step B2: Categorize Findings

Organize discovered code into architectural categories:

1. •Components/Services — Major system components and their responsibilities
2. •Data Model — Entities, fields, relationships discovered from code
3. •User Flows — UI screens, navigation, user journeys
4. •Interaction Flows — Key request/response sequences between components
5. •State Management — Stateful components with their transitions

Present the categorized findings to the user for validation before proceeding.

Step B3: Generate Architecture Diagrams

Generate Mermaid .mmd files in arch/ from the categorized findings:

• •system-architecture.mmd — Flowchart of discovered components and their relationships
• •user-flow.mmd — Flowchart of discovered user journeys
• •data-model.mmd — ER diagram of discovered entities and relationships
• •sequence-{flow}.mmd — Sequence diagrams for key interaction flows
• •state-{component}.mmd — State diagrams for stateful components (if any)

Write arch/_arch.json manifest referencing all generated diagrams (conforming to vista/templates/arch-schema.json).

Set all diagram descriptions to note they are "reverse-engineered from existing codebase" so reviewers know these are inferences.

Step B4: Backfill Domain Requirements

Fill in domain-requirements.md from code analysis:

1. •Infer JTBD and user stories from what the code actually does
2. •Document functional requirements discovered from service logic
3. •Document non-functional requirements from configuration, caching, error handling patterns
4. •Flag TDD candidates — identify components with complex logic that should have been tested

Mark all backfilled content clearly as "reverse-engineered" so reviewers know these are inferences.

Step B5: Review and Next Steps

Discover the dashboard URL by calling the ralph_providers MCP tool and reading dashboard_url from the response.

Tell the user:

1. •

   Review diagrams in the web dashboard:

   code

   <dashboard_url>/project/<project-id>/arch/<feature-name>
   

   Use the AI chat panel to discuss and iterate on diagrams.

2. •

   Or review directly by reading the .mmd files in the terminal.

3. •

   Pay special attention to:

   • •Missing components or flows that exist but weren't detected
   • •Incorrect relationships between entities
   • •Missing service dependencies
4. •

   Next steps:

   • •Edit diagrams and domain-requirements.md to fix inaccuracies
   • •/vista:tdd <name> — Generate TDD diagrams for flagged heavy-logic components
   • •/vista:specs <name> — Generate specifications from the reverse-engineered artifacts
   • •/vista:add <name> — Extend the feature with new capabilities

Output

After legacy import (either path):

.vista/features/<name>/
├── arch/
│   ├── _arch.json              # Diagram manifest
│   ├── system-architecture.mmd # Components and relationships
│   ├── user-flow.mmd           # User journeys
│   ├── data-model.mmd          # Entity-relationship diagram
│   ├── sequence-*.mmd          # Interaction flows
│   └── state-*.mmd             # State machines (if any)
├── specs/                      # Existing or empty (populated by /vista:specs)
├── domain-requirements.md      # Backfilled or enriched
├── progress.txt                # Progress tracking
└── IMPLEMENTATION_PLAN.md      # Template (populated by Ralph loops)

Removed after conversion (Path A only):

• •AGENTS.md — Deprecated build agent config
• •<name>_preview.html — Replaced by web dashboard
• •Inline sections from <name>_plan.json (uiFlows, dataModels, dataFlow, services)