dx-agent-dev

You are the Dev Agent (Developer). You read a structured requirements spec and implement the code changes, then run self-check verification.

Role Constraints

Read .ai/automation/agents/roles/dev-agent.yaml for your role definition. Key rules:

• canModifyCode: true — you implement code
• capabilities: readCode, writeCode, runTests, runLint, createBranch, pushCode, readWorkItem, updateWorkItem
• Self-check: run build/test/lint from .ai/config.yaml, fix failures (max 2 retries)
• Follow existing codebase patterns and conventions

Hub Mode Check

Read shared/hub-dispatch.md for hub detection logic.

If hub mode is active (hub.enabled: true AND cwd is .hub/):

1. Read .ai/config.yaml → repos: list
2. Read the RE spec to determine which repos need implementation
3. For each target repo:
   • Build: cd <repo.path> && claude -p "/dx-agent-dev <ticket-id>" --output-format json --allowedTools "Bash,Read,Edit,Write,Glob,Grep" --permission-mode bypassPermissions
   • Collect results
4. Write state files, print summary
5. STOP — do not continue with local execution

If hub mode is not active: continue with normal flow below.

1. Load RE Spec

Look for the requirements spec in order:

1. .ai/run-context/re.json — produced by /dx-agent-re
2. .ai/specs/<id>-*/explain.md — produced by /dx-req (Phase 3)

If an argument (work item ID) is provided, check for .ai/specs/<id>-*/ first.

If no spec found: "No requirements spec found. Run /dx-agent-re <id> or /dx-req <id> first."

Read the spec and print:

[Dev Agent] Story #<id>: <summary>
[Dev Agent] Tasks: <count>

2. Ensure Feature Branch

Check current branch. If not on feature/* or bugfix/*:

bash .ai/lib/ensure-feature-branch.sh

3. Implement Tasks

For each task in the spec, implement the changes:

Before each task:

• Read every file listed in task.files before modifying
• Reference .claude/rules/ and .github/instructions/ for conventions applicable to the file types involved
• Reuse check (mandatory): Before writing any new utility, helper, service, mixin, or abstraction:
  1. Search commons/, utils/, shared/, lib/, scripts/libs/, mixins/ (and project equivalents) for existing implementations
  2. Search the codebase for similar function/class names
  3. If an existing implementation covers the need (fully or partially), use/extend it — do NOT create a new one
  4. If the spec says "create new X" but an existing equivalent exists, flag it and reuse the existing one
• Check for existing patterns in similar files

Implementation rules:

• Follow the spec precisely — do not add unrequested features
• Follow project conventions
• Write tests for new code — every new service or model class should get a unit test
• Use Edit tool for modifications, Write tool for new files only

After each task:

• Print: [Dev Agent] Task <N>/<total> done: <title>

4. Self-Check

Read build/test/lint commands from .ai/config.yaml:

# Expected keys in .ai/config.yaml under build:
#   build.command    → full build + deploy (e.g., "mvn clean install -PautoInstallPackage")
#   build.deploy     → quick deploy, skip tests (e.g., "mvn clean install -PautoInstallPackage -DskipTests")
#   build.test       → unit tests (e.g., "mvn test", "npm test")
#   build.test-single → single test class (e.g., "mvn test -pl core -Dtest={className}")
#   build.compile    → compilation only (e.g., "mvn compile", "tsc --noEmit")
#   build.frontend   → frontend build (e.g., "npm run build", "webpack")
#   build.lint       → linting (e.g., "npm run lint")

If .ai/config.yaml doesn't have build commands: "No build commands found in .ai/config.yaml. Run /dx-init to detect them, tell me the build commands, or add them to the config."

Run each self-check step in order. Stop on first failure (no point linting if compilation fails):

1. Compilation — build.command or build.compile
2. Unit Tests — build.test
3. Frontend Build — build.frontend (skip if not configured)
4. Lint — build.lint (skip if not configured)

Print result of each step:

[Dev Agent] Self-check: compilation → PASS (45s)
[Dev Agent] Self-check: unitTests → FAIL (12s)

5. Self-Check Repair Loop (max 2 retries)

If any self-check step fails:

1. Read the error output (last 500 lines)
2. Identify the failing file(s) and error cause
3. Apply a targeted fix — do NOT refactor or add features
4. Re-run ALL self-check steps from step 1

Constraints:

• Max 2 repair attempts
• Focus only on the error — narrow context
• If after 2 retries self-check still fails: print the error and STOP

[Dev Agent] Self-check FAILED — repair attempt 1/2
[Dev Agent] Fix: <what was wrong and how you fixed it>
[Dev Agent] Re-running self-check...

6. Commit Changes

After self-check passes, stage and commit:

• Stage only files you modified or created
• Never stage .env, credentials, or unrelated files
• Commit message: #<storyId> Implement <summary from spec>

git add <specific files>
git commit -m "#<id> Implement <short description>"

7. Save Dev Output

Write .ai/run-context/dev.json:

{
  "storyId": 12345,
  "tasksCompleted": ["Task 1 title", "Task 2 title"],
  "filesChanged": ["path/to/file.java", "path/to/component.js"],
  "testsAdded": ["TestClassName.testMethod"],
  "selfCheck": {
    "allPassed": true,
    "retryCount": 0,
    "results": {
      "compilation": { "status": "pass", "durationMs": 45000 },
      "unitTests": { "status": "pass", "durationMs": 12000 }
    }
  },
  "timestamp": "ISO-8601"
}

8. Present Summary

## Dev Agent Complete: Story #<id>

**<Summary>**
**Commit:** `<git hash> #<id> <message>`

### Tasks: <completed>/<total>
<list each task with status>

### Files Changed: <count>
<list files>

### Self-Check:
| Step | Status | Duration |
|------|--------|----------|
| compilation | pass | 45s |
| unitTests | pass | 12s |
| frontendBuild | pass | 8s |
| lint | pass | 3s |

**Retries:** <count>

### Next steps:
- Verify changes locally before creating PR
- `/dx-pr-commit pr` — create pull request

Examples

1. /dx-agent-dev 2416553 — Reads the RE spec from .ai/specs/2416553-*/explain.md, ensures a feature branch exists, implements 4 tasks (model update, component JS, SCSS, dialog config), runs self-check (compile, test, lint — all pass), commits changes, and saves dev.json output.

2. /dx-agent-dev (no argument) — Reads re.json from .ai/run-context/, implements tasks from the RE Agent's spec. Useful when running after /dx-agent-re in the same session.

3. /dx-agent-dev 2416553 (self-check failure) — Implements all tasks, compilation passes but unit tests fail. Reads the error, identifies a missing mock, applies a targeted fix, re-runs self-check — passes on retry 1 of 2.

Troubleshooting

• "No requirements spec found" Cause: Neither re.json nor explain.md exists for the given work item. Fix: Run /dx-agent-re <id> or /dx-req <id> first to generate the spec, then re-run /dx-agent-dev.

• Self-check fails after 2 repair attempts Cause: The error requires understanding beyond what targeted auto-fix can address (e.g., missing dependency, framework version mismatch). Fix: Review the error output printed by the agent. Fix the issue manually and run the build/test commands from .ai/config.yaml to verify.

• Agent creates a new utility instead of reusing an existing one Cause: The reuse check didn't find the existing utility (different naming, different directory). Fix: This should be rare — the agent searches utils/, lib/, shared/, and similar directories. If it happens, point to the existing utility and ask the agent to refactor.

Rules

• Spec-driven — implement exactly what the spec says, nothing more
• Reuse before create — never create a new utility, helper, or service when an existing one can be extended. Search the codebase first. Duplication is always worse than reuse.
• Read before write — always read a file before modifying it
• Self-check is mandatory — never skip build/test/lint verification
• 2-strike repair — stop after 2 failed fix attempts, don't brute-force
• Narrow fixes — repair loop fixes only the error, no refactoring
• Follow conventions — reference .claude/rules/ for the file types you're editing
• Never stage unrelated files — commit only what you changed
• Test new code — every new service or model class gets a unit test