PANTOUM — How It Works
Interactive guide to the SPFx upgrade workflow
PANTOUM automates SharePoint Framework upgrades by combining the
Microsoft 365 CLI with
AI-powered error resolution.
Use arrow keys or buttons to navigate
Architecture
Three layers with shared core services.
Studio
pantoum-webapp
React 19 + Fluent UI v9
Claude Code
/pantoum-*
Slash commands + skills
▼
Core Services
UpgradeService ·
PatchService ·
ReportService ·
ErrorAnalyzer ·
ClaudeMigrationExecutor
▼
Infrastructure
M365 CLI · Claude Agent SDK · Patch Applier · Git · npm
Upgrade Workflow
For each SPFx solution in the repository:
1. Discover Solutions
Scan for .yo-rc.json files
→
2. M365 CLI Report
m365 spfx project upgrade
→
3. Generate Patches
Pre → Deterministic → Post
▼
4. Apply Patches
Update files, deps, configs
→
5. Build & Test
npm run build
→
6. AI Error Fix
Claude analyzes & fixes
▼
7. Generate Reports
JSON + Markdown
AI-powered step
The Patch System
Every change is tracked as a patch with a unique ID, description, and before/after state.
FN####
M365 CLI Patches
Generated from the official M365 CLI upgrade report.
Dependency updates, config changes, file additions.
M####
Manual Patches
Defined in pantoum.patches.yml.
Package migrations, custom pre/post steps, PnP and MGT upgrades.
C####
Claude AI Patches
AI-generated during migration or error fixing.
Import rewrites, API updates, TypeScript fixes.
Also generated by YAML deterministic steps:
SASS### ·
SCRIPT### ·
ENV### ·
HEFTFIX### ·
FILTER###
Patch Lifecycle
Generate
→
Apply
→
Verify
→
Report
AI Error Resolution
When a build fails, Claude AI analyzes the errors and generates targeted fixes.
1
Build fails with errors
▼
2
Claude reads error output + source files
▼
3
Generates and applies code fixes
▼
4
Re-runs build to verify
▼
?
Still failing? Retry (errors must decrease)
3×
default (configurable 1–10 via --aiMaxRetries)
Three AI Integration Points
Point 1
M365 CLI Errors
Fix parsing issues so the upgrade report can be generated
Point 2
Package Migrations
Rewrite imports and API calls for major version upgrades
Point 3
Build Errors
Fix TypeScript, missing imports, and API compatibility issues
Reporting
Every upgrade produces detailed reports documenting all changes.
JSON Report
Machine-readable · Complete data
All patches with before/after state
AI metrics: tokens, cost, duration
Build results per solution
Third-party dependency updates
Markdown Report
Human-readable · Summary format
Upgrade status per solution
AI fixes with code diffs
Admin actions required
Command used for reproducibility
Report Location
Global: pantoum_run_{runId}/
Per-solution: {solution}/pantoum_run_{runId}/ (optional, --perSolutionReports)
Three Interfaces, Same Core
Pick whichever fits your workflow — the engine underneath is identical.
CLI
pantoum --localPath ./project \
--toVersion 1.22.1 \
--aiFixBuildErrors true
Direct command-line execution
Hierarchical flags (master/sub)
JSON and text output modes
Scriptable for CI/CD pipelines
PANTOUM Studio
npm run webapp
React 19 + Fluent UI v9 webapp
Main + Advanced settings tabs (synced with pantoum.settings.yml)
Solution picker & live upgrade monitoring
Real-time log streaming via WebSocket
Report browser (JSON & Markdown)
Claude Code Plugin
/pantoum-upgrade
/pantoum-analyze
/pantoum-doctor
Slash commands inside Claude Code
Guided upgrade wizard
Post-upgrade analysis with report context
Environment health check
Opens Studio on demand