feat: Multi-agent workflow system for Scribe map automation

.claude/settings.local.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "salesforce": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@salesforce/mcp",
+        "--toolsets", "all",
+        "--orgs", "FullCopy,CCxDEV,FUT,SIT,BST,UAT"
+      ]
+    }
+  }
+}

.gitignore

@@ -6,5 +6,5 @@ backups/
 
 # Log files
 *.log
-mcp-server-v2.log
+logs/
 tests/test_run.log

.mcp.json

@@ -0,0 +1,21 @@
+{
+  "mcpServers": {
+    "salesforce": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--loglevel=error",
+        "@salesforce/mcp",
+        "--toolsets", "all",
+        "--orgs", "FullCopy,CCxDEV,FUT,SIT,BST,UAT"
+      ]
+    },
+    "scribe-v2": {
+      "command": "/Users/ryanmodisette/ScribeAutomation/.venv/bin/python",
+      "args": ["/Users/ryanmodisette/ScribeAutomation/scripts/scribe_mcp_server_v2.py"],
+      "env": {
+        "PYTHONPATH": "/Users/ryanmodisette/ScribeAutomation"
+      }
+    }
+  }
+}

.vscode/mcp.json

@@ -26,7 +26,7 @@
         "--loglevel=error",
         "@salesforce/mcp",
         "--toolsets", "all",
-        "--orgs", "CCxDEV,SIT"
+        "--orgs", "FullCopy,CCxDEV,FUT,SIT,BST,UAT"
       ],
       "env": {},
       "description": "Salesforce MCP server for metadata operations"

CLAUDE.md

@@ -0,0 +1,198 @@
+# Claude Code Instructions for Scribe Automation
+
+## ⚠️ STOP - READ THIS FIRST
+
+**Before attempting ANY fix or starting ANY task**, you MUST:
+
+1. **Read `docs/LLM_CONTEXT.md` COMPLETELY** - This 1600+ line file contains:
+   - Known issues and their DOCUMENTED SOLUTIONS
+   - Anti-patterns that have already been identified
+   - Lessons learned from previous debugging sessions
+
+2. **Search documentation for the issue first** - Many problems have already been solved and documented. Check:
+   - `docs/LLM_CONTEXT.md` - Look for "Anti-Pattern" sections
+   - `docs/SCRIBE_MAP_PATTERNS.md` - Known patterns
+
+3. **Check `examples/` for working references** - Compare your code with working maps like `AccountMap.json`
+
+**WHY THIS MATTERS:** Issues like "UI overlap" and "Ambiguous child pointers" were ALREADY documented with solutions. Skipping documentation wastes time re-discovering known fixes.
+
+---
+
+## MANDATORY PRE-WORK CHECKLIST
+
+Before starting ANY work in this repository:
+
+1. **Read `docs/LLM_CONTEXT.md`** - Complete technical reference (1600+ lines)
+2. **Check `templates/` folder** - Contains reusable patterns and blocks
+3. **Check `examples/` folder** - Reference maps with production patterns
+
+## Critical Files to Check
+
+| When Building Maps | Read These First |
+|-------------------|------------------|
+| Any map | `templates/patterns/*.json`, `templates/blocks/*.json` |
+| Case migration | `examples/CaseMigrationMap.json` (226 blocks) |
+| User migration | `examples/` for similar maps |
+| Flowchart extraction | `docs/FLOWCHART_EXTRACTION_ANALYSIS.md` |
+
+## Templates Folder (ALWAYS CHECK)
+
+```
+templates/
+├── patterns/
+│   ├── cross_ref_lookup.json      # Cross-reference with IfElse
+│   ├── safe_lookup_check.json     # Lookup + null check
+│   ├── cardinality_check.json     # Duplicate detection
+│   ├── global_variable_init.json  # RECNUM() = 1 pattern
+│   ├── error_handling_block.json  # Error logging
+│   └── standard_query_loop.json   # Query → ForEach
+└── blocks/
+    ├── upsert_variable.json       # Lab Variables (has connection ID!)
+    ├── insert_error_log.json      # Error_Log__c structure
+    └── ...
+```
+
+## MCP Servers
+
+Two versions available:
+- `scribe-v2`: FastMCP v2 (25 tools) - **Recommended**
+- `scribe`: Legacy v1 (23 tools)
+
+Vision tools (v2 only):
+- `scribe_extract_flowchart` - Extract from images/PDF
+- `scribe_create_map_from_spec` - Generate from MapSpec
+
+## Session Continuity
+
+For session continuity, use the workflow state system:
+- **List workflows**: `python -m scripts.workflow_state list`
+- **Show workflow**: `python -m scripts.workflow_state show <id>`
+- **Generate handoff**: `python -m scripts.handoff <id>`
+
+State files are stored in `outputs/workflows/`.
+
+## Quick Reference
+
+### Before Building Any Map
+1. Check `templates/patterns/` for applicable patterns
+2. Check `templates/blocks/` for block structures
+3. Check `examples/` for reference implementations
+4. Read `docs/SCRIBE_MAP_PATTERNS.md` for 10 documented patterns
+
+### After Building Any Map (Automatic)
+`to_map_json()` and `save()` now automatically call `finalize()`:
+- Fixes `firstChildBlockId` and sibling links
+- Ensures bidirectional Query↔ForEach linking (critical for UI)
+- Strips x/y coordinates from non-Query blocks (Scribe UI calculates positions)
+
+This prevents:
+- "Ambiguous child pointers" warnings
+- Visual block overlap in Scribe UI
+
+To disable (rare): `to_map_json(..., auto_finalize=False)`
+
+### Before Extracting from Flowcharts
+1. Count all decision diamonds
+2. Count all create/update operations
+3. Map loop nesting levels
+4. List all field references
+5. Verify extraction covers ALL items
+
+### Confirmation Required
+Before ANY work (not just maps), you MUST be able to truthfully state:
+> "I have read the COMPLETE docs/LLM_CONTEXT.md file, searched it for relevant anti-patterns and solutions, checked templates/, and compared with working example maps."
+
+If you encounter an issue:
+1. **FIRST** search LLM_CONTEXT.md for existing documentation
+2. **THEN** compare with working examples in `examples/`
+3. **ONLY THEN** attempt a fix
+
+Do NOT attempt to fix issues without checking if they're already documented.
+
+## Documentation Map
+
+| Document | Purpose |
+|----------|---------|
+| `docs/LLM_CONTEXT.md` | Complete technical reference |
+| `docs/SCRIBE_MAP_PATTERNS.md` | 10 design patterns |
+| `docs/FLOWCHART_EXTRACTION_ANALYSIS.md` | Extraction checklist |
+| `docs/VISION_WORKFLOW.md` | Vision-based generation |
+| `docs/MCP_MIGRATION.md` | MCP v1 → v2 migration |
+| `docs/TESTING.md` | Test infrastructure |
+| `copilot-instructions.md` | Detailed anti-patterns |
+| `agents/AGENTS.md` | Multi-agent system documentation |
+
+---
+
+## Multi-Agent Workflow System
+
+This project includes a multi-agent system for structured map creation workflows.
+
+### Agent Modes
+
+| Mode | Purpose | Prompt Template |
+|------|---------|-----------------|
+| **Orchestrator** | Coordinate workflows, manage checkpoints | Default |
+| **Documentation Review** | Pattern identification, compliance | `agents/prompts/documentation_review.md` |
+| **Data Ingestion** | Flowchart extraction | `agents/prompts/flowchart_extraction.md` |
+| **MapSpec Creation** | Intermediate specification | `agents/prompts/mapspec_creation.md` |
+| **Map Builder** | Generate Scribe JSON | `agents/prompts/map_builder.md` |
+| **Validation Review** | Pre-import validation | `agents/prompts/validation_review.md` |
+
+### Workflows
+
+| Workflow | File | Description |
+|----------|------|-------------|
+| Flowchart to Map | `agents/workflows/flowchart_to_map.md` | Convert image → Scribe map |
+| Modify Existing | `agents/workflows/modify_existing.md` | Change existing map |
+
+### Starting a Workflow
+
+1. **Check MCP servers**:
+   ```bash
+   python -m scripts.ensure_mcp_servers
+   ```
+
+2. **Create workflow**:
+   ```bash
+   python -m scripts.workflow_state create --type flowchart_to_map --description "Build AccountMap"
+   ```
+
+3. **Follow workflow steps** in the workflow documentation
+
+### Workflow State
+
+- Each workflow gets a unique ID: `scribe-<5char>`
+- State saved to: `outputs/workflows/<id>.json`
+- Ledger at: `outputs/workflows/ledger.json`
+
+### Key Commands
+
+```bash
+# List workflows
+python -m scripts.workflow_state list
+
+# Show workflow
+python -m scripts.workflow_state show scribe-a7k2m
+
+# Generate handoff for session continuity
+python -m scripts.handoff scribe-a7k2m
+```
+
+### Human Checkpoints
+
+All workflows have checkpoints requiring approval:
+
+| Checkpoint | Approval Required |
+|------------|-------------------|
+| Extraction Review | "Approved" or feedback |
+| Spec Approval | "Approved" or feedback |
+| **Import Approval** | Exact phrase: `I approve import for map: [Name]` |
+
+### Resuming Workflows
+
+If a session ends mid-workflow:
+
+1. Generate handoff: `python -m scripts.handoff scribe-a7k2m`
+2. In new session: "Resume workflow scribe-a7k2m"