ADR-029: AI-Powered Plan Mode (Vibe Mode)

Status

Proposed

Date

2025-12-07

Deciders

• Norbert Bede
• Claude (AI Assistant)

Context and Problem Statement

iDempiere consultants spend significant time analyzing client requirements, designing Application Dictionary structures, and manually creating AD elements in the correct order. This process is:

1. Time-consuming (days for complex modules)
2. Error-prone (missing dependencies, wrong order)
3. Undocumented (no ADRs, no implementation guides)
4. Hard to estimate (no structured breakdown)

We need a CLI mode that lets consultants describe what they need in natural language and get a production-ready, executable implementation plan with documentation.

Reference: Inspired by Claude Code's plan mode and "vibe coding" approach.

Decision Drivers

• Consultant productivity: Reduce analysis time from days to minutes
• Best practices: Encode iDempiere patterns (document types, workflows)
• Reproducibility: Executable plan.json, not manual steps
• Documentation: Auto-generate ADRs, specs, guides
• clig.dev compliance: No required prompts, fully scriptable
• Error prevention: Pre-flight validation (ADR-028)

Considered Options

1. Wizard-based - Interactive step-by-step prompts
2. Template-based - Pre-defined plugin templates
3. AI Plan Mode - Natural language to executable plan

Decision Outcome

Chosen option: "AI Plan Mode", because it combines the flexibility of natural language input with the rigor of structured, validated execution plans. It follows clig.dev guidelines by being fully scriptable while optionally interactive.

Confirmation

• idempiere-cli plan "description" generates executable plan
• Plan executes step-by-step with pre-flight validation
• Documentation (ADR, specs) auto-generated
• Resume from checkpoint on failure

The Vibe Mode Workflow

┌─────────────────────────────────────────────────────────────────┐
│                         VIBE MODE                               │
│                                                                  │
│   INPUT (natural language)                                      │
│   "equipment maintenance with work orders and parts tracking"   │
│                                                                  │
│         ↓ AI Analysis (LangChain4j)                             │
│                                                                  │
│   UNDERSTAND                                                    │
│   ├── Domain: Maintenance Management                            │
│   ├── Entities: Equipment, WorkOrder, Part, Technician          │
│   ├── Patterns: Document (WorkOrder), Master (Equipment, Part)  │
│   └── Relationships: Equipment→WorkOrder→WorkOrderLine→Part     │
│                                                                  │
│         ↓ Plan Generation                                       │
│                                                                  │
│   GENERATE                                                      │
│   ├── docs/adr/XXX-maintenance-module.md                        │
│   ├── docs/FUNCTIONAL_SPEC.md                                   │
│   ├── docs/IMPLEMENTATION_PLAN.md                               │
│   ├── plan/plan.json (executable steps)                         │
│   └── plan/todo.md (human checklist)                            │
│                                                                  │
│         ↓ Execution                                             │
│                                                                  │
│   EXECUTE (step-by-step)                                        │
│   [1/47] Creating AD_Element: XX_Equipment_ID    ✔              │
│   [2/47] Creating AD_Element: XX_WorkOrder_ID    ✔              │
│   [3/47] Creating AD_Table: XX_Equipment         ✔              │
│   [4/47] Creating AD_Table: XX_WorkOrder         ✘ Pre-flight   │
│          → Skip / Retry / Abort / Force                         │
│                                                                  │
│         ↓ Output                                                │
│                                                                  │
│   DISTRIBUTE                                                    │
│   ├── 2pack/Maintenance_1.0.0.zip                               │
│   └── migration/maintenance_001.sql                             │
└─────────────────────────────────────────────────────────────────┘

Command Interface

Create Plan (non-interactive, scriptable)

# From text
idempiere-cli plan "equipment maintenance with work orders"

# From file
idempiere-cli plan --input requirements.txt

# With options
idempiere-cli plan "sales order module" \
  --prefix XX \
  --entity-type com.example \
  --output ./my-project

Review Plan

# Show plan summary
idempiere-cli plan --show maintenance-module

# Show full plan
idempiere-cli plan --show maintenance-module --verbose

# Export plan
idempiere-cli plan --export maintenance-module --format json

Execute Plan

# Execute all steps
idempiere-cli plan --execute maintenance-module

# Dry-run (preview without changes)
idempiere-cli plan --execute maintenance-module --dry-run

# Execute with auto-skip existing
idempiere-cli plan --execute maintenance-module --skip-existing

# Resume from checkpoint
idempiere-cli plan --resume maintenance-module

Full Scriptable Flow (CI/CD)

# One-liner for automation
idempiere-cli plan "sales order" \
  --output ./plan \
  --execute \
  --skip-existing \
  --format pack \
  --json

Generated Artifacts

.idempiere/plans/maintenance-module/
├── plan.json              # Executable steps with dependencies
├── state.json             # Execution checkpoint (resume support)
├── todo.md                # Human-readable checklist
├── estimate.md            # Effort breakdown
│
├── docs/
│   ├── adr.md             # Architecture decision record
│   ├── functional-spec.md # Client-facing: what it does
│   └── implementation.md  # Technical: how to build
│
└── output/
    ├── 2pack/             # Ready-to-deploy package
    └── migration/         # SQL scripts

Plan.json Structure

{
  "name": "maintenance-module",
  "description": "Equipment maintenance with work orders",
  "created": "2025-12-07T10:30:00Z",
  "prefix": "XX",
  "entityType": "D",

  "analysis": {
    "domain": "Maintenance Management",
    "patterns": ["document", "master-data", "transaction-line"],
    "entities": ["Equipment", "WorkOrder", "WorkOrderLine", "Part"]
  },

  "steps": [
    {
      "id": 1,
      "type": "element",
      "action": "create",
      "name": "XX_Equipment_ID",
      "description": "Equipment unique identifier",
      "status": "pending",
      "depends": [],
      "command": "dict element add --column-name XX_Equipment_ID --name Equipment --type ID",
      "validation": {
        "pre": "SELECT COUNT(*) = 0 FROM AD_Element WHERE ColumnName = 'XX_Equipment_ID'",
        "post": "SELECT AD_Element_ID FROM AD_Element WHERE ColumnName = 'XX_Equipment_ID'"
      }
    },
    {
      "id": 2,
      "type": "table",
      "action": "create",
      "name": "XX_Equipment",
      "description": "Equipment master data",
      "status": "pending",
      "depends": [1],
      "command": "dict table add --name XX_Equipment --type master --columns standard,uuid",
      "validation": {
        "pre": "SELECT COUNT(*) = 0 FROM AD_Table WHERE TableName = 'XX_Equipment'",
        "post": "SELECT AD_Table_ID FROM AD_Table WHERE TableName = 'XX_Equipment'"
      }
    },
    {
      "id": 3,
      "type": "column",
      "action": "create",
      "name": "XX_Equipment.Name",
      "status": "pending",
      "depends": [2],
      "command": "dict column add --table XX_Equipment --column Name --type String --mandatory"
    }
  ],

  "summary": {
    "totalSteps": 47,
    "elements": 8,
    "tables": 4,
    "columns": 28,
    "windows": 2,
    "processes": 1
  }
}

AI Analysis Patterns

The AI recognizes iDempiere patterns from natural language:

Integration with Existing ADRs

Implementation Architecture

src/main/java/org/idempiere/cli/
├── commands/
│   └── PlanCommand.java           # Main plan command
├── plan/
│   ├── PlanService.java           # Orchestration
│   ├── PlanAnalyzer.java          # AI analysis (LangChain4j)
│   ├── PlanGenerator.java         # Generate plan.json
│   ├── PlanExecutor.java          # Step-by-step execution
│   ├── PlanCheckpoint.java        # State management
│   └── model/
│       ├── Plan.java              # Plan record
│       ├── PlanStep.java          # Step record
│       └── PlanAnalysis.java      # AI analysis result
├── docs/
│   └── DocumentGenerator.java     # Generate ADR, specs, guides
└── ai/
    └── PlanAnalyzerAgent.java     # LangChain4j agent for analysis

Pros and Cons of the Options

Option 1: Wizard-based

Interactive step-by-step prompts.

• Good, because guides user through process
• Bad, because violates clig.dev "never require prompt"
• Bad, because not scriptable/automatable
• Bad, because no documentation output

Option 2: Template-based

Pre-defined plugin templates.

• Good, because fast for known patterns
• Good, because no AI dependency
• Bad, because inflexible for custom requirements
• Bad, because limited to pre-defined templates

Option 3: AI Plan Mode (Chosen)

Natural language to executable plan.

• Good, because handles any requirement description
• Good, because fully scriptable (clig.dev compliant)
• Good, because generates documentation automatically
• Good, because validates with pre-flight checks
• Good, because supports resume on failure
• Neutral, because requires AI/LLM (can use local Ollama)

More Information

Target Users

Effort Estimation

Plan includes step count which maps to effort:

Formula: estimated_hours = (elements * 0.03) + (tables * 0.08) + (columns * 0.03) + (windows * 0.17) + (processes * 0.25)

Related ADRs

• ADR-004 - Table creation
• ADR-005 - Migration scripts
• ADR-013 - LangChain4j integration
• ADR-028 - Error handling and pre-flight

References

• Command Line Interface Guidelines
• iDempiere Application Dictionary
• iDempiere Table and Column
• 2Pack Documentation