Turn macro-enabled Excel workbooks (.xlsm) into a shareable web application — step by step, without losing business logic hidden in sheets, formulas, and VBA.
The project uses a Strangler Fig approach: extract and document the legacy file, validate with the owner, then migrate feature by feature in Python while Excel remains available until the web app is proven.
Primary deliverable: a logic analysis (specs/<workbook>_LOGIC_ANALYSIS.md) that links business meaning to technical behaviour.
- Python 3.11+
- A
.xlsmtest file insample/(local, not committed)
pip install -r requirements.txtpython -m uvicorn web.server:app --reload --port 8501Open http://localhost:8501 in Chrome or Edge (voice input on / and /annotate).
| Step | URL | What you do |
|---|---|---|
| 1 — File | / |
Upload .xlsm, describe your context (voice or keyboard) |
| 2 — Describe | /annotate |
Explain each input, button, and control (🎤) |
| 3 — Analysis | /review |
Migration wishes, generate and download logic analysis (.md) |
Session state is kept in the browser until you close the tab.
docker build -t excel-migration .
docker run -p 8501:8501 excel-migrationpython -m pytest tests/ -v.xlsm → understand (web or CLI) → logic analysis → migrate in Python
| Profile | How | Then |
|---|---|---|
| Web | 3-step UI above | Download .md from /review |
| CLI | scripts/extract.py → scripts/generate_logic_agent.py |
Complete analysis in Cursor with @LOGIC_AGENT_PROMPT.md |
Optional later: functional spec (generate_spec_agent.py, generate_spec.py).
Full commands, folder map, and agent platforms: docs/PROJECT_LAYOUT.md.
| Document | Content |
|---|---|
| docs/PROJECT_LAYOUT.md | Repository map — scripts/, src/, agents/, specs/, web/ |
| docs/MIGRATION_GUIDE.md | 8-phase migration methodology (extraction → decommission) |
| docs/VBA_REFERENCE.md | VBA → Python reference (Phase 5 coding) |
| agents/definitions/ | Agent roles (Logic Analyst, Spec Writer) |
| agents/platforms/ | Run agents on Cursor, CLI, or web handoff |
Local data (gitignored): workbooks in sample/, JSON in extractions/. Generated specs in specs/ when you validate a workbook.