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

Read .env from the current working directory and check for COREZOID_STAGE_ID.

• If COREZOID_STAGE_ID is missing or empty → stop and invoke the corezoid-init skill. Do not proceed until init completes.
• If COREZOID_STAGE_ID is present → use it 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:

Found N processes in project "":
  - 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

1. Store result as process_reports[conv_id]
2. Log progress: Reviewed N/total: "" — 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-.json and project-review-.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

| issuetype | issuesubtype | severity | |------------|---------------|----------| | cross_process | circular_dependency | high | | cross_process | orphaned_process | warning | | cross_process | high_fan_in | warning | | cross_process | high_fan_out | warning | | cross_process | external_call | low | | cross_process | shared_hardcode_url | high | | cross_process | shared_hardcode_token | high | | cross_process | shared_hardcode_value | medium | | cross_process | duplicate_logic | low | | cross_process | alias_conflict | warning | | cross_process | naming_convention | low |

Cross-process finding example:

{
  "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)

| Process | Findings | High | Medium | Warning | Low | |---------|----------|------|--------|---------|-----| | Process A (12345) | 12 | 2 | 3 | 4 | 3 | | Process B (67890) | 5 | 0 | 1 | 2 | 2 | | Cross-process | 4 | 1 | 1 | 2 | 0 | | Total | N | | | | |

Step 3.2: Top Issues List (Markdown)

🔴 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

{
  "project_name": "",
  "project_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

| Request | Behavior | |---------|----------| | "review all processes in folder X" | Phase 0 scoped to folder_id | | "review only stage prod" | Filter process_inventory by stage_id | | "skip cross-process analysis" | Phase 1 only, skip Phase 2 | | "quick review" | Skip code node analysis (Step 7) and duplicate logic (Step 2.2) | | "review only hardcodes" | Hardcode check per process + Step 2.3 only | | "review only N processes" | Prioritize by last modified date |

---

MCP Tool Map

| Step | MCP call | |------|----------| | 0.1 List processes | list folder filter:"conveyor" obj_id: | | 1 Pull process | pull-process process_id: | | 1 Lint process | lint-process process_path: | | 2.1 List & resolve aliases | /corezoid-alias-manager → "Workflow: List aliases" |

---

Reference Documents

| Path | When to read | |------|-------------| | ${CLAUDE_PLUGIN_ROOT}/skills/corezoid-review/SKILL.md | Per-process audit steps (Steps 1–14) | | ${CLAUDE_PLUGIN_ROOT}/docs/nodes/code-node.md | Code node details and available JS libraries | | ${CLAUDE_PLUGIN_ROOT}/docs/nodes/call-process-node.md | Call a Process node, semaphores | | ${CLAUDE_PLUGIN_ROOT}/docs/nodes/api-call-node.md | HTTP API call configuration | | ${CLAUDE_PLUGIN_ROOT}/docs/process/error-handling.md | Error handling patterns | | ${CLAUDE_PLUGIN_ROOT}/docs/variables-guide.md | Variable naming rules and usage examples |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: corezoid
• Source: corezoid/corezoid-ai-plugin
• License: MIT
• Homepage: https://corezoid.com

Install and usage instructions live in the source repository linked above.