How to Configure Build Error Resolution in ECC: Complete Guide to the Build-Error-Resolver Agent

Enable the build-error-resolver agent in the Everything Claude Code (ECC) framework to automatically diagnose TypeScript and JavaScript build failures and apply minimal fixes through a standardized five-step workflow defined in the repository's agent configuration files.

The Everything Claude Code (ECC) repository ships with a dedicated Build-Error-Resolver agent that eliminates the need for manual debugging scripts when builds fail. When you configure build error resolution in ECC, you leverage automated diagnostic collection, intelligent error prioritization, and surgical code edits that restore compilation with minimal churn. The agent's behavior is controlled through its markdown configuration file located at agents/build-error-resolver.md in the affaan-m/ECC source tree.

Understanding the Agent Configuration Structure

The build-error-resolver agent's configuration resides in agents/build-error-resolver.md and defines the diagnostic commands, fix patterns, and success metrics used during resolution. According to the affaan-m/ECC source code, this file contains the complete workflow logic that transforms raw compiler output into actionable edits.

Key configuration components include:

• Diagnostic Commands: The specific npx tsc, npm run build, and eslint invocations used to surface errors
• Common Fixes Table: A reference of minimal edit patterns for TypeScript type errors and import resolutions
• Success Metrics: Exit code requirements (npx tsc --noEmit returning 0) that define resolution completion
• Quick Recovery Procedures: Nuclear options for cache corruption scenarios

The Five-Step Error Resolution Workflow

When invoked, the agent executes a standardized workflow designed to resolve build errors efficiently and deterministically.

1. Execute Diagnostic Commands

The agent first runs specific diagnostic commands defined in the Diagnostic Commands section of agents/build-error-resolver.md to capture the full error surface:

npx tsc --noEmit --pretty          # Surface all TypeScript type errors

npm run build                      # Attempt full compilation

npx eslint . --ext .ts,.tsx,.js,.jsx  # Identify syntax and lint violations

These commands must complete (even if failing) before the agent proceeds to analysis.

2. Categorize and Prioritize Errors

In the Workflow section of agents/build-error-resolver.md, the agent categorizes errors into three severity tiers:

• Critical build breakage (compilation halting)
• Type inference failures (TypeScript-specific)
• Warnings and style issues

This prioritization ensures the agent addresses blocking issues before cosmetic fixes.

3. Apply Minimal Code Fixes

The agent consults the Common Fixes table in agents/build-error-resolver.md to propose surgical edits. According to the source implementation, typical fixes include:

• Adding ?: optional chaining operators to nullable properties
• Inserting missing async keywords on functions
• Correcting import paths to match tsconfig.json path aliases
• Adding explicit type annotations where inference fails

The agent uses the Read tool to examine failing files and the Edit tool to apply changes incrementally.

4. Verify Build Success

After applying fixes, the agent re-runs diagnostics until npx tsc --noEmit exits with code 0 and npm run build completes successfully, as defined in the Success Metrics section of the agent file.

5. Iterate Until Green

If new errors surface during verification, the agent repeats steps 1-4 automatically, ensuring comprehensive error resolution without manual intervention.

Invoking the Build-Error-Resolver Agent

Manual Invocation

To configure build error resolution in ECC for immediate use, invoke the agent within a Claude Code session:

/agent build-error-resolver

Upon invocation, the agent automatically executes the diagnostic workflow and proposes fixes through the ECC interface until the build passes.

CI Pipeline Integration

Embed the agent's diagnostic pattern into continuous integration workflows. The following GitHub Actions configuration demonstrates how to implement the ECC build check pattern:

// .github/workflows/build-check.yml
{
  "name": "ECC Build Check",
  "on": ["push", "pull_request"],
  "jobs": {
    "build": {
      "runs-on": "ubuntu-latest",
      "steps": [
        { "uses": "actions/checkout@v4" },
        { "uses": "actions/setup-node@v4", "with": { "node-version": "20" } },
        { "run": "npm ci" },
        {
          "run": "npx tsc --noEmit --pretty || true",
          "continue-on-error": true
        },
        {
          "run": "npm run build || true",
          "continue-on-error": true
        },
        {
          "run": "echo 'If the build failed, invoke the ECC build‑error‑resolver agent manually.'"
        }
      ]
    }
  }
}

The || true and continue-on-error directives ensure the workflow captures all errors before manual resolution.

Quick Recovery Commands for Corrupted Builds

When dependency caches or build artifacts corrupt the development environment, the agent provides "nuclear option" commands documented in the Quick Recovery block of agents/build-error-resolver.md:

# Clear Next.js cache and rebuild

rm -rf .next node_modules/.cache && npm run build

# Fresh dependency installation

rm -rf node_modules package-lock.json && npm install

# Auto-fix lintable violations

npx eslint . --fix

These commands bypass incremental compilation issues when the standard workflow fails due to corrupted state.

Customizing Agent Configuration

To modify how ECC configures build error resolution, edit agents/build-error-resolver.md directly. The file contains customizable diagnostic command lists and editable fix patterns for TypeScript-specific errors. For international teams, localized variants exist in docs/*/agents/build-error-resolver.md, such as the Chinese documentation.

You can also create wrapper scripts that pre-run diagnostics. The following TypeScript utility mimics the agent's initial behavior:

// scripts/fix-build.ts
import { execSync } from "child_process";

function run(cmd: string) {
  try {
    execSync(cmd, { stdio: "inherit" });
  } catch {
    // Errors swallowed; agent will propose fixes
  }
}

// Initial diagnostic pass
run("npx tsc --noEmit --pretty");
run("npm run build");

// Re-verify after manual agent intervention
run("npx tsc --noEmit --pretty");
run("npm run build");

Key Configuration Files

Understanding the ECC build error resolution ecosystem requires familiarity with these source files:

File	Purpose	Location
agents/build-error-resolver.md	Core agent definition including workflow and fixes	agents/build-error-resolver.md
AGENTS.md	Master registry of all available ECC agents	AGENTS.md
package.json	Build script definitions (npm run build)	package.json
tsconfig.json	TypeScript configuration affecting module resolution	tsconfig.json

Summary

• The build-error-resolver agent in affaan-m/ECC automates TypeScript and JavaScript build error resolution through a five-step workflow defined in agents/build-error-resolver.md.
• Configure build error resolution in ECC by invoking /agent build-error-resolver or integrating diagnostic commands (npx tsc --noEmit, npm run build) into CI pipelines.
• The agent prioritizes critical errors, applies minimal fixes (optional chaining, type annotations, import corrections), and verifies success via exit code checks.
• Customize behavior by editing the agent's markdown configuration or using wrapper scripts that pre-execute diagnostics.
• Use Quick Recovery commands (rm -rf .next node_modules/.cache) when dependency corruption causes persistent build failures.

Frequently Asked Questions

How do I enable automatic build error fixing in ECC?

Enable automatic resolution by typing /agent build-error-resolver in your Claude Code session. The agent automatically executes diagnostics from agents/build-error-resolver.md, categorizes errors by severity, and proposes minimal edits using the Read and Edit tools until npx tsc --noEmit returns exit code 0.

Can I customize the diagnostic commands used by the build-error-resolver?

Yes. Edit the agents/build-error-resolver.md file to modify the Diagnostic Commands section. You can add project-specific commands (like npm run lint:strict) or adjust TypeScript compiler flags. For team-wide changes, commit the modified agent file to your repository; for personal workflows, create a wrapper script that calls your diagnostics before invoking the agent.

What types of fixes does the ECC build-error-resolver apply?

The agent applies surgical fixes defined in the Common Fixes table of its configuration, including adding ?: optional chaining to nullable properties, inserting missing async keywords, correcting import paths to match tsconfig.json aliases, and adding explicit type annotations. It avoids structural refactors, focusing only on compilation-blocking changes.

Where are the build-error-resolver agent's quick recovery commands documented?

Quick recovery commands reside in the Quick Recovery block of agents/build-error-resolver.md. These include cache clearing (rm -rf .next node_modules/.cache), dependency reinstallation (rm -rf node_modules package-lock.json && npm install), and auto-fixing lint violations (npx eslint . --fix), providing nuclear options when incremental builds fail due to corruption.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}