Dx Step Build

---

name: dx-step-build description: Build and deploy to local dev environment, fix errors iteratively until the build passes. Use after code changes to verify everything compiles and deploys correctly. when_to_use: "Use after code changes to build and deploy to local dev environment. Trigger on 'build', 'compile', 'mvn install', 'build and deploy', 'run the build', or when verifying code compiles correctly." argument-hint: "[optional: build command override]" context: fork allowed-tools: ["read", "edit", "search", "write", "agent"]

You build and deploy the project, diagnose any failures, fix them, and repeat until the build passes.

Flow

digraph step_build {
    "Discover build command" [shape=box];
    "Run build" [shape=box];
    "Build passed?" [shape=diamond];
    "Attempt < 6?" [shape=diamond];
    "Find error + read file" [shape=box];
    "Diagnose + fix" [shape=box];
    "Re-run build" [shape=box];
    "Report PASS" [shape=doublecircle];
    "Report FAIL (6 attempts exhausted)" [shape=doublecircle];

    "Discover build command" -> "Run build";
    "Run build" -> "Build passed?";
    "Build passed?" -> "Report PASS" [label="yes"];
    "Build passed?" -> "Attempt < 6?" [label="no"];
    "Attempt < 6?" -> "Find error + read file" [label="yes"];
    "Attempt < 6?" -> "Report FAIL (6 attempts exhausted)" [label="no"];
    "Find error + read file" -> "Diagnose + fix";
    "Diagnose + fix" -> "Re-run build";
    "Re-run build" -> "Build passed?";
}

Node Details

Discover build command

If the user provided an argument, use that as the build command.

Otherwise, read from .ai/config.yaml. Choose the right command based on context:

Config key	When to use	Example
build.deploy	Quick rebuild during fix loops, FE verification, iterative development	mvn clean install -PautoInstallPackage -DskipTests
build.command	Final pipeline build, when tests must run	mvn clean install -PautoInstallPackage

Default: Use build.deploy if available (faster — skips tests). Fall back to build.command if build.deploy is not configured.

Exception: When called from the main pipeline build phase (dx-agent-all Phase 5), use build.command to include tests. The caller can override by passing an explicit argument.

If neither is found, read CLAUDE.md and README.md to find the project's build-and-deploy command. Look for a command that both builds and deploys to a local dev environment.

Print: Using build command: \``

Run build

Execute the build command using the Bash tool:

• Append 2>&1 to capture both stdout and stderr
• Use timeout 300000ms (5 minutes)

Re-run build

Same as Run build above — execute the same build command again.

Build passed?

Scan the output for success/failure indicators:

• Success markers: BUILD SUCCESS, Compiled successfully, Done in, exit code 0
• Failure markers: BUILD FAILURE, ERROR, FAILED, error:, non-zero exit code

Attempt < 6?

Track attempt count starting at 1. Increment after each fix attempt. Maximum 6 attempts total.

Find error + read file

Find the error Scan the build output for the first actionable error. Look for:

• Compilation errors with file path and line number
• Build tool errors (failed goals, missing dependencies)
• XML/config parsing errors
• Frontend build errors (webpack, tsc, etc.)
• Test failures with class name + assertion message

Extract: file path, line number, error message.

Read the broken file Use the Read tool to open the file. If a line number was reported, focus on that area.

Diagnose + fix

Diagnose Determine the root cause. Common causes:

• Syntax errors (unclosed tags, invalid attributes, encoding issues)
• Missing imports
• Wrong property names or type mismatches
• Missing test dependencies or mock registrations
• Incompatible method signatures

Fix Use the Edit tool to correct the specific issue. Make the minimal change needed.

Report PASS

Print:

Build & deploy passed.

Done. Stop here.

Report FAIL (6 attempts exhausted)

STOP and print:

Build failed after 6 fix attempts.

**Command:** `<build command>`
**Last error:**
<the specific error message>

**Files modified during fix attempts:**
- <list of files edited>

Run `/dx-step-fix` to continue debugging, or fix manually and re-run `/dx-step-build`.

AEM Projects — Frontend vs Maven Deployment

If the project is AEM (check .ai/config.yaml for aem: section):

• Frontend builds (npm run build, webpack, etc.) compile frontend code but do NOT auto-deploy to local AEM. The built artifacts land in the project's build output directory but are not installed on the AEM instance.
• Maven builds (mvn clean install -PautoInstallSinglePackage, etc.) compile AND deploy to local AEM. Only a Maven build makes changes visible on the running AEM instance.

When local AEM testing is needed, always use the Maven build command (from build.command in config) — not just a frontend build.

Success Criteria

• Build command exits with code 0 (or output contains BUILD SUCCESS)
• No new lint errors introduced (if lint runs as part of build)
• Build completes within 6 fix attempts if errors occur

Examples

Standard build

/dx-step-build

Reads build command from .ai/config.yaml build.command, runs it. If it passes, prints "Build & deploy passed." If it fails, enters fix loop.

Custom build command

/dx-step-build mvn clean install -pl core

Uses the provided command instead of config. Useful for building a specific module.

Fix loop in action

/dx-step-build

Build fails with missing import → fixes it → rebuilds → passes. Up to 6 fix attempts before giving up.

Troubleshooting

Build fails after 6 attempts

Cause: The error is too complex for automatic fixing, or each fix introduces a new error. Fix: Run /dx-step-fix for deeper diagnosis, or fix manually and re-run.

"No build command found"

Cause: .ai/config.yaml doesn't have build.command and no CLAUDE.md build instructions exist. Fix: Run /dx-init to configure the build command, or pass it directly: /dx-step-build mvn clean install.

Frontend build passes but changes not visible on AEM

Cause: Frontend builds compile to dist/ but don't deploy to AEM. Only Maven builds auto-deploy. Fix: Use the Maven build command (from build.command) for local AEM verification.

Anti-Rationalization

Common excuses for bad build-fix habits — and why they're wrong:

False Logic	Reality Check
"I'll suppress the warning with a flag"	Warnings become errors in the next upgrade. Fix the root cause.
"Single-pass is faster — I'll fix all errors at once"	Feels faster until fix #3 undoes fix #1. One error at a time.
"I'll refactor while fixing the build"	Build fixes must be minimal. Refactoring during fix loops introduces new failures.
"The test is flaky, I'll skip it"	Flaky tests mask real regressions. Fix the test or mark it blocked, never skip.
"It works on my machine"	Build must pass with the project's configured command, not a custom variant.
"I'll add @SuppressWarnings / // @ts-ignore"	Suppression hides bugs. Fix the type or logic error the compiler found.

Rules

• Minimal fixes only — don't refactor or improve code, just fix the build error
• One error at a time — fix the first error, re-build, then tackle the next
• Don't mask errors — never suppress warnings/errors with flags like -q or --silent
• Preserve intent — if a fix would change the feature's behavior, STOP and ask the user