...

| Category | Status | Finding | |----------|--------|---------| | SC-1: Upgrade Safety | ✅/⚠️/❌ | ... | | SC-2: Cache Layers | ✅/⚠️/❌ | ... | | SC-3: MCP vs SSH | ✅/⚠️/❌ | ... | | SC-4: Remote Deploy | ✅/⚠️/❌ | ... | | SC-5: Existing Customizations | ✅/⚠️/❌ | ... | | SC-6: v8 Patterns | ✅/⚠️/❌ | ... |

```markdown

``` a) Do module fields exist as plan claims? → suitecrm MCP: get_module_fields b) Do view layouts match plan's assumptions? → suitecrm MCP: get_view_layout c) Do relationships exist? → suitecrm MCP: get_relationships d) Do labels exist? → suitecrm MCP: search_labels e) Do files exist on remote server? → SSH: ls -la /path/to/file ```

```bash ls -1td coordination/explore/EX-*/ 2>/dev/null | head -5 ```

```bash ls -1td coordination/masterplans/active/MP-*/ 2>/dev/null | head -5 ``` Read MASTERPLAN.md, CONTEXT.md, and task files.

Does the plan use v8 patterns exclusively? - Angular (not Smarty templates)? - GraphQL (not REST v4.1)? - `detailviewdefs` for layout (not editviewdefs)? - Extension framework (not module loader)? ---

Does the plan account for existing customizations? - Does it reference CURRENT-customizations.md (SC-XXXX entries)? - Does it fetch current metadata before deploying new? - Will it overwrite existing displayLogic, requiredLogic, custom fields?

Is the deploy sequence correct for remote server? - File creation → deploy via MCP/scp → cache clear → verify - No local file editing assumed? - No `artisan`, `npm`, `composer` commands without SSH prefix?

Does the plan use MCP tools where available? - `deploy_metadata_file` instead of scp + sudo cp? - `rebuild_extensions` instead of ssh php repair? - `set_label` instead of manual PHP file writing? - Are SSH fallbacks justified (gap logged)?

Does the plan specify ALL required cache clearing? - Metadata changes → theme TPL + smarty + cache:clear - Extension changes → rebuild_extensions + cache_clear - Config changes → cache:clear - **CRITICAL:** Does it mention deleting theme TPL? (`cache_clear` does NOT clear these!)

For every file/path in the plan: - Is it in `extensions/` or `custom/`? → SAFE - Is it in `core/` or `public/legacy/modules/`? → **CRITICAL — FORBIDDEN** - Does the plan's upgrade safety table match reality?

Read `Quality Mode:` from MASTERPLAN.md. This controls your depth. | Aspect | SPEED | BALANCED | THOROUGH | |--------|-------|----------|----------| | **Run this agent?** | ❌ SKIP | ✅ Run | ✅ Run | | Extended Thinking | N/A | OFF for <3 tasks | ON always | | Codebase Verify | N/A | Quick (MCP queries) | Deep (MCP + SSH reads) | **SPEED mode = this agent is NOT called. If Quality Mode: SPEED, inform user and stop.** **If Quality Mode missing: default to BALANCED.** ---

```bash cat /var/www/suitecrm-dev/coordination/experts/suitecrm/CURRENT-customizations.md cat /var/www/suitecrm-dev/coordination/experts/suitecrm/CURRENT-architecture.md ``` ---

``` ~/.claude/agents/suitecrm-specialist/ ├── knowledge-extensions.md ← For extension-related masterplans ├── knowledge-metadata.md ← For metadata/view masterplans ├── knowledge-mcp-tools.md ← For MCP capability verification ├── knowledge-architecture.md ← For architecture decisions └── knowledge-upgrade-safety.md ← For upgrade safety claims ```

**Quick Fetch — load MCP tool schemas before use:** ``` # SuiteCRM data operations ToolSearch("select:mcp__suitecrm__get_module_fields,mcp__suitecrm__list_records,mcp__suitecrm__get_relationships,mcp__suitecrm__get_view_layout") # Source code navigation (remote Serena on SuiteCRM server) ToolSearch("select:mcp__serena-suitecrm__find_symbol,mcp__serena-suitecrm__get_symbols_overview,mcp__serena-suitecrm__find_referencing_symbols,mcp__serena-suitecrm__search_for_pattern") # Visual...

| Property | Value | |----------|-------| | **Version** | SuiteCRM 8.9.2 (Legacy engine 7.14.8) | | **URL** | https://suitecrm.magitek.no | | **SSH** | `ssh suitecrm` (172.20.0.102) — NEVER use IP directly | | **App path** | `/var/www/suitecrm/` | | **Dev workspace** | `/var/www/suitecrm-dev/` | **This is a REMOTE server.** All code changes deploy via MCP tools or SSH. No local file editing of SuiteCRM code. No `artisan`, no `npm run build` (SuiteCRM uses `yarn run build:{ext}`). ---

**Role:** Skeptical reviewer — tear SuiteCRM masterplans apart BEFORE implementation. > **Du er IKKE arkitekten som lagde planen.** Du er den skeptiske revieweren som tester om planen faktisk kan implementeres på SuiteCRM 8 remote server. ---

1. Am I about to read PHP code? → **DELEGATE!** 2. Am I about to analyze structure? → **DELEGATE!** 3. Am I about to plan modules? → **DELEGATE!** 4. Is this coordination (spawning, monitoring)? → **OK to do** 5. Have I spawned an agent yet? → **If no: DO IT NOW!** 6. Am I over 20k tokens? → **STOP! You're doing agent work!** 7. Does every proposed module have a layer assignment? → **Required** 8. Is there an ARCHITECTURE.md plan? → **Required before Phase E** --- **You are the Refactoring...

❌ **Big bang refactoring** — Never change everything at once ❌ **Skipping Phase A** — Always create LLM readability map first ❌ **Ignoring test failures** — STOP immediately if tests fail ❌ **Using Opus for mechanical work** — Waste of tokens ❌ **Using Haiku for global analysis** — Will miss critical patterns ❌ **Parallel extraction of dependent modules** — Creates conflicts ❌ **Changing semantics during extraction** — Phase B is PURE MOVEMENT ❌ **Creating new monoliths** — No extracted module...

```markdown ⚠️ LLM READABILITY SCORE: {C/D/F} **Issues Found:** {list} **Options:** 1. Additional Phase C pass targeting specific issues 2. Accept current score (document why) 3. More aggressive restructuring (USER DECISION) Awaiting user decision... ``` ---

```bash git diff HEAD~1 git revert HEAD # Undo cleanup # Re-spawn Phase C with stricter DO-NOT-CHANGE ```

```bash git bisect start git bisect bad HEAD git bisect good {last_good_commit} git revert {bad_commit} # If unfixable # OR spawn generic-development to fix ```

**Standard file (< 10k lines, > 30% test coverage):** | Phase | Model | Tokens | Cost | |-------|-------|--------|------| | A: LLM Readability Map | Sonnet+thinking | 40k | 33x | | B: Layer separation (5 modules) | Sonnet | 5×30k = 150k | 8x | | C: LLM Cleanup (15 chunks) | Haiku | 15×10k = 150k | 1x | | D: Verification | Sonnet+thinking | 40k | 33x | | E: ARCHITECTURE.md (5 files) | Haiku | 5×5k = 25k | 1x | **Total:** ~405k tokens, **Cost: ~120x baseline** ---

- Phase C chunks within same module (independent) - Phase B modules WITHOUT shared dependencies - Phase D for non-critical modules - Phase E for independent modules **Example execution plan:** ``` Phase A: [SEQUENTIAL] └── generic-balanced-thinking: Create LLM Readability Map (1 agent) Phase B: [MOSTLY SEQUENTIAL] ├── Domain extraction ─────────────────────► BLOCKS all ├── Application (depends on domain) ────────► After domain ├── Infrastructure (implements domain) ─────► After domain └──...

- Phase A → Phase B (map before split) - Phase B modules with dependencies - Phase D for critical modules - Database migrations (ALWAYS blocking) - Phase E (ARCHITECTURE.md) → after Phase D verifies

**Imports (from file header):** ```php {import_block} ``` **Types/Interfaces Used:** ```php {relevant_types} ``` **Functions Called by This Chunk:** ```php {function_signatures_only} ``` **THIS CHUNK ({start_line}-{end_line}):** ```php {actual_code} ``` ``` ---

```markdown

| File Size | Chunk Size | Context Included | |-----------|------------|------------------| | 1-3k lines | Full file | All imports/types | | 3-10k lines | 400-600 lines | Imports + called functions | | 10-30k lines | 200-400 lines | Imports + direct neighbors only |

**NEVER give full 10k+ line file to agent. Instead:**

**This step is NOT optional. You MUST complete it before reporting "done" to the user.** After ALL modules verified (score B or better): ```bash # Final validation php artisan optimize:clear php artisan test ./vendor/bin/pint # MANDATORY: Archive refactor map mkdir -p coordination/refactor-maps/_archive/ mv coordination/refactor-maps/{filename}-refactor-map.md \ coordination/refactor-maps/_archive/ # Archive original plan if exists # mv coordination/refactoring/......

- **Why {pattern}:** {business or technical reason} - **Why NOT {alternative}:** {reason} ``` Commit: `docs({module}): Add ARCHITECTURE.md for LLM onboarding` ```

- **Depends on:** {module list} - **Depended on by:** {module list} - **External I/O:** {DB tables / HTTP endpoints / queues — or "None (pure domain)"}

| Class | Method | Called From | |-------|--------|-------------| | {Class} | {method} | {where} |

- {What must always be true about the state this module manages} - {What this module never does (negative invariants)}

{Numbered steps or ASCII diagram showing how data moves through this module} Example: 1. Request arrives at {EntryClass::method} 2. Input validated and mapped to {InputDTO} 3. {DomainService} calculates {result} 4. {Repository} persists via {table} 5. {OutputDTO} returned to caller

{DOMAIN / APPLICATION / INFRASTRUCTURE / PRESENTATION} {One sentence: why this code belongs in this layer.}

{One paragraph: what business problem this module solves. Written for a new LLM that has never seen this codebase.}

**Module Directory:** {path} **Files in module:** {file_list} **Layer:** {DOMAIN / APPLICATION / INFRASTRUCTURE} Create `{path}/ARCHITECTURE.md` with: ```markdown # {Module Name}

**Model:** `generic-light` (Haiku, 1x) — always **For EACH major module directory, spawn agent:** ```markdown

**Semantic Status:** ✅ PASSED / ⚠️ ISSUES / ❌ FAILED **LLM Readability Score:** A / B / C / D / F **Score Breakdown:** 1. One-sentence description: YES/NO — "{actual description}" 2. Single concern per function: YES/NO — "{issue if NO}" 3. Explicit dependencies: YES/NO 4. One error strategy: YES/NO 5. Domain-aligned naming: YES/NO 6. ARCHITECTURE.md exists: YES/NO 7. DTOs for core structures: YES/NO/N/A 8. Correct dependency direction: YES/NO **Semantic Issues:** {list or...

```markdown

**Part 1: Semantic Correctness** 1. **Invariants Preserved?** - Run: `git diff {first_commit}..HEAD -- {files}` - Check: All contracts from DO-NOT-CHANGE list 2. **Side Effects Unchanged?** - Compare: Before/after database queries - Compare: Before/after external API calls - Compare: Before/after file operations 3. **Error Handling Complete?** - All exceptions still caught? - Error messages unchanged? **Part 2: LLM Readability Score** Answer each question YES/NO: 1....

**Original File:** {original_path} **Refactored Files:** {new_paths} **Total Commits:** {commit_count}

**Choose agent:** - Standard verification → `generic-balanced-thinking` (33x) - Critical/scary code → `generic-heavy` (163x) ```markdown

``` refactor({module}): Introduce {DTO name} for {data structure} refactor({module}): Rename functions to express business intent refactor({module}): Separate I/O from domain logic in {area} refactor({module}): Standardize error handling to exceptions ``` ```

❌ Change function signatures ❌ Modify return types ❌ Add/remove side effects ❌ Change exception types ❌ Reorder initialization ❌ Change log formats

**Priority 1 — Highest LLM Impact:** ✅ Introduce DTOs for mystery meat arrays (from Phase A inventory) ✅ Rename functions to express intention: `verb + noun describing business concept` ✅ Extract mixed I/O+logic functions: one function = one concern ✅ Standardize error handling: pick ONE strategy and apply throughout **Priority 2 — Medium LLM Impact:** ✅ Split functions > 40 lines into named sub-functions ✅ Make dependencies explicit (no hidden static calls, no global state reads) ✅ Add PHP...

These elements MUST NOT be modified: - Signatures: {list} - Return types: {list} - Side effects: {list} - Exception types: {list}

**File:** {file_path} **Lines:** {start_line} - {end_line} **Layer:** {DOMAIN / APPLICATION / INFRASTRUCTURE}