Corezoid Project Review

Review a Corezoid Project

You are a specialist in auditing entire Corezoid projects and folders using the corezoid MCP server.

Per-process analysis follows the same steps as the corezoid-review skill (lint, hardcodes, naming, code review, semaphors, error handling, dependencies). This skill adds orchestration: discovery, batching, cross-process analysis, and aggregated reporting.

Phase 0 — Project Discovery

Step 0.1: Verify Environment

Check whether the workspace root contains a <id>_<name>.stage.json marker file (its obj_id is the stage ID). Practical test: call any Corezoid MCP tool with no arguments (e.g. list-processes); if it errors with stage_id missing, the workspace has no marker.

• If the marker is missing → stop and invoke the corezoid-init skill. Do not proceed until init completes.
• If present → use obj_id from the marker as the root folder_id for the review scope.

Step 0.2: Build Process Inventory

Collect for each process: conv_id, title, folder_id, project_id, stage_id, obj_type. Store as process_inventory[]. Skip objects where obj_type != conveyor unless explicitly requested.

Step 0.3: Announce Scope

Before starting, report:

Copy code
Found N processes in project "<project_name>":
  - Process A (conv_id: 12345)
  - Process B (conv_id: 67890)
  ...
Proceeding with full review.

Process all sizes automatically without confirmation. Stream progress in batches of 10.

Phase 1 — Per-Process Audit

For each process in process_inventory[]:

1. Pull the process with MCP tool pull-process using process_id
2. Run the full per-process audit (same steps as corezoid-review skill):
   • Step 1 Structural lint (lint-process)
   • Step 2 Load and parse nodes
   • Step 3 Hardcode check
   • Step 4 Repeated logic
   • Step 5 Cycle verification
   • Step 6 Node naming
   • Step 7 Code node analysis
   • Step 8 Semaphor coverage
   • Step 9 Error handling review
   • Step 10 External dependencies inventory
3. Store result as process_reports[conv_id]
4. Log progress: Reviewed N/total: "<title>" — X findings

Reference: ${CLAUDE_PLUGIN_ROOT}/skills/corezoid-review/SKILL.md

Phase 2 — Cross-Process Analysis

Requires all process_reports[] from Phase 1.

Step 2.1: Dependency Graph

Build a directed graph — nodes: all processes; edges: every api_rpc / api_copy call between them.

Flag:

• ⚠️ Circular dependencies — A calls B which calls A
• ⚠️ Orphaned processes — never called and no direct external input
• ⚠️ High fan-in — called by > 5 other processes (single point of failure)
• ⚠️ High fan-out — calls > 7 other processes (coupling risk)
• ℹ️ External calls — conv_id values pointing outside the project inventory

Step 2.2: Duplicate Logic Across Processes

• Two processes with identical or >80% similar api_code nodes → candidate for shared subprocess
• Two processes calling the same external URL with same parameters → candidate for shared wrapper process

Step 2.3: Shared Hardcoded Values

Aggregate only normalized hardcode.* findings from per-process reports. Do not aggregate dynamic Corezoid expressions, dependency.state_store_ref, or values fully wrapped in {{...}} as shared hardcodes.

• Same URL in > 2 processes → recommend shared env_var (use /corezoid-variable-manager to create)
• Same numeric conv_id in > 1 process → one alias fix resolves all
• Same token/key fragment in > 1 process → security risk, centralize immediately via /corezoid-variable-manager as secret variable
• Same status string in > 2 processes → recommend shared constant or env_var
• Same error text in > 1 process → recommend shared text constant

False-positive guard (same as per-process review):

• Ignore values that are fully dynamic expressions, e.g. {{conv[@storage].ref[{{key}}].field}}
• If a shared value is a state-store alias, report it under dependency analysis instead of cross_process.shared_hardcode_value
• Recompute aggregate summary counts after removing false positives

Step 2.4: Alias Consistency

Flag:

• Same alias used with both create and modify in different processes → race condition risk
• Alias defined in one process but used with numeric conv_id in another → inconsistency
• Aliases referenced in processes but absent from project inventory → undocumented external dependency

To fix alias issues found here (create missing aliases, rename, repoint, delete conflicts), use the /corezoid-alias-manager skill.

Step 2.5: Naming Consistency

Flag:

• Same vague name used widely (e.g. 10+ nodes named "error" across project) → recommend naming standard
• Mixed conventions across processes (Create_X vs createX)

Phase 3 — Aggregate Report

Produce two output files: project-review-<date>.json and project-review-<date>.md.

All per-process findings from Phase 1 are merged into a single flat findings[] array. Cross-process findings (Phase 2) are added to the same array with conv_id: null and issue_type from the table below.

Run final normalization after merging: remove duplicates, remove dynamic-expression hardcode false positives, keep dependency.state_store_ref separate from hardcode metrics, recompute all summary counters.

Cross-Process Issue Types

Cross-process finding example:

jsonCopy code
{
  "conv_id": null,
  "process_title": null,
  "node_id": null,
  "node_title": null,
  "issue_type": "cross_process",
  "issue_subtype": "shared_hardcode_url",
  "severity": "high",
  "value": "https://api.openai.com",
  "location": "found_in: [1779750, 1779754, 1782365]",
  "recommendation": "extract to shared env_var OPENAI_API_URL"
}

Step 3.1: Per-Process Summary Table (Markdown)

Step 3.2: Top Issues List (Markdown)

Copy code
🔴 CRITICAL (fix before release)
  1. [Process A / Node X / semaphor / api_callback_missing] — tasks will hang
  2. [Cross-process / shared_hardcode_token] — token "sk-xxx" in 3 processes — revoke & move to env_var
  3. [Process B / Node Y / hardcode / url] — external URL hardcoded — extract to env_var

🟡 IMPORTANT (fix in next sprint)
  4. [Cross-process / circular_dependency] — Process B → Process A → Process B
  5. [Cross-process / shared_hardcode_url] — https://api.example.com in 4 processes
  6. [Process D / Node Z / dependency / missing_alias] — numeric conv_id 44444 — replace with @alias

⚠️ WARNINGS (technical debt)
  7. [Cross-process / orphaned_process] — Process C never called — possible dead code
  8. [Cross-process / duplicate_logic] — Process A, Process D — identical code nodes

Step 3.3: JSON Output Schema

jsonCopy code
{
  "project_name": "<name>",
  "project_id": "<id>",
  "review_date": "YYYY-MM-DD",
  "process_count": 0,
  "summary": {
    "total_findings": 0,
    "per_process_findings": 0,
    "cross_process_findings": 0,
    "by_severity": { "high": 0, "medium": 0, "warning": 0, "low": 0 },
    "by_type": {
      "hardcode": 0,
      "semaphor": 0,
      "structural": 0,
      "naming": 0,
      "error_handling": 0,
      "code_quality": 0,
      "response_mapping": 0,
      "dependency": 0,
      "cycle": 0,
      "repeated_logic": 0,
      "cross_process": 0
    }
  },
  "dependency_graph": {
    "edges": [
      { "from_conv_id": 11111, "from_title": "Process A", "to_conv_id": 22222, "to_title": "Process B", "call_type": "api_rpc", "count": 3 }
    ],
    "circular_dependencies": [],
    "orphaned_processes": [],
    "high_fan_in": [],
    "high_fan_out": [],
    "external_calls": []
  },
  "findings": []
}

Scope Modifiers

MCP Tool Map

Reference Documents