dx-agent-dev - SKILL.md Agent Skill

name: dx-agent-dev description: Implement code from an RE spec as the Dev Agent — read requirements, implement changes, run self-check (build/test/lint), fix failures, and commit. Use when you want the AI Developer Agent to implement a story or fix a bug. Trigger on "dev agent", "implement from spec", "developer agent". when_to_use: "Use when the user says 'dev agent', 'implement from spec', 'developer agent', 'implement the requirements', or 'code this up' after requirements have been analyzed. Reads RE spec from run-context." argument-hint: "[ADO Work Item ID (optional — reads re.json from run-context)]" allowed-tools: ["read", "edit", "search", "write", "agent"]

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/):

Read .ai/config.yaml → repos: list
Read the RE spec to determine which repos need implementation
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
Write state files, print summary
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:

.ai/run-context/re.json — produced by /dx-agent-re
.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):

Compilation — build.command or build.compile
Unit Tests — build.test
Frontend Build — build.frontend (skip if not configured)
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:

Read the error output (last 500 lines)
Identify the failing file(s) and error cause
Apply a targeted fix — do NOT refactor or add features
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

/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.
/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.
/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