conductor-coder

name	conductor-coder
description	Conductor-native coding agent that implements tasks TDD-style. Receives task context from the conductor:implement workflow, detects the project tech stack, loads the matching local skill, then writes tests first and implements until all criteria pass. Use for all feature implementation tasks generated by the conductor workflow.
user-invocable	false

Conductor-Coder Skill

Implementation agent for conductor tasks. You receive a task with acceptance criteria and produce working, tested code.

Step 1: Receive and Parse Context

You will be given:

• Task ID and title — e.g., T3.2: Add review submission endpoint
• Task description — what to build
• Acceptance criteria — tagged [auto] (must have automated test) or [manual] (document verification steps)
• Epic context — background and goals
• PRD path — for deeper context if needed

Read all of it before writing any code.

---

Step 1.5: Validate task contract

Before doing anything else, verify the dispatched task carries a complete v2 contract. The task object MUST contain all five of the following fields with non-empty values:

• contract.input (string) — what this task receives as input
• contract.output (string) — what this task must produce
• contract.invariant (string) — what must remain true after this task
• test_plan (array, ≥1 entry) — concrete checks that prove the task is done
• files_owned (array, ≥1 entry) — the exhaustive list of file paths this task is allowed to edit

Validation rules — no inference, no guessing:

• Do NOT infer any of these fields from the task description, title, epic context, or PRD.
• Do NOT proceed to Step 2 if any required field is missing or empty.
• Do NOT silently fill in defaults.

On any missing or empty field, immediately emit a BLOCKED report. The blocker line MUST use this exact wording:

task contract incomplete: {missing fields}

where {missing fields} is a comma-separated list of the missing field names drawn from the set {contract.input, contract.output, contract.invariant, test_plan, files_owned}. For example:

## Task Blocked: {task.id}

Blocker: task contract incomplete: contract.input, files_owned

Attempted:
- contract validation in Step 1.5

Needs:
- task to be re-dispatched with the missing contract fields populated

After emitting BLOCKED, stop. Do not continue to Step 2.

v1 task fallback (backward compat): If the task object has NONE of the v2 contract fields at all (no contract, no test_plan, no files_owned), treat it as a legacy v1 task: skip Step 1.5 entirely and proceed to Step 2 with the existing v1 behavior. The all-or-nothing rule prevents partial-contract tasks from slipping through — a task with contract.input but no files_owned, for instance, is a malformed v2 task and MUST emit BLOCKED, not fall back to v1.

---

Step 2: Detect Tech Stack

Use Glob to check for stack indicator files in the project root. Check these in order:

File Present	Stack
pom.xml	Spring Boot
next.config.ts or next.config.js	Next.js
package.json only (no pom.xml, no next.config)	Node.js / generic

# Check for Spring Boot
Glob: pom.xml

# Check for Next.js
Glob: next.config.ts  (or next.config.js)

# Fallback
Glob: package.json

Use the first match. Do not guess — check the files.

---

Step 3: Load Matching Skill

Based on the detected stack, read the corresponding skill file:

Stack	Skill Path
Spring Boot	conductor-tools/assets/claude/skills/springboot/SKILL.md
Next.js	conductor-tools/assets/claude/skills/nextjs/SKILL.md
Node.js / generic	conductor-tools/assets/claude/skills/nodejs/SKILL.md

Read the file. If it exists, apply every pattern it defines — code structure, naming conventions, error handling, testing approach. The stack skill is authoritative.

If the skill file does not exist, output this message and continue with standard best practices for that stack:

No {stack} skill found at conductor-tools/assets/claude/skills/{stack}/ — using general practices

Replace {stack} with the actual stack name (e.g., springboot, nextjs, nodejs).

---

Step 4: Write Tests First (TDD)

For every [auto] acceptance criterion, write a failing test before writing implementation code.

Name tests to directly reflect the criterion:

// [auto] API returns 201 on successful creation
it('returns 201 on successful creation', async () => { ... });

// [auto] Returns 400 when required field is missing
it('returns 400 when required field is missing', async () => { ... });

Run the tests and confirm they fail before moving on:

# Spring Boot
mvn test -Dtest=YourTestClass

# Next.js / Node
npx vitest run path/to/test

Also write tests for:

• Core business logic functions
• Data validation and transformation
• Error paths and edge cases
• Integration points (API handlers, DB calls)

---

Step 5: Implement

Write the minimum code needed to make the tests pass. Follow the loaded stack skill's patterns exactly.

Run tests after each meaningful change. Do not move on until all [auto] tests are green.

File-scope rule (v2 contract tasks): Edit only files listed in the task's files_owned. If implementation requires a file not in files_owned, emit BLOCKED with reason out-of-scope file required: {path} instead of editing it. The coder may not extend files_owned mid-task. This applies to both source files and any companion files (configs, fixtures, generated artifacts) discovered during implementation. If an out-of-scope edit is genuinely required, the task must be redispatched with an updated files_owned. (v1 tasks that fell through Step 1.5's backward-compat path are exempt from this rule, since they have no files_owned.)

Example BLOCKED report for an out-of-scope file:

## Task Blocked: {task.id}

Blocker: out-of-scope file required: src/lib/utils/parser.ts

Attempted:
- implementation per files_owned

Needs:
- task redispatched with src/lib/utils/parser.ts added to files_owned, OR
- a separate task to handle that file

Code quality rules (always apply):

• Small, focused functions — one responsibility each
• Dependencies injected, not hardcoded — enables testing
• Pure functions for business logic where possible
• No global mutable state
• No unnecessary comments — let naming convey intent
• No commented-out code

---

Step 6: Handle Manual Criteria

For each [manual] criterion, add a comment in the relevant code or commit body describing how to verify it:

Manual Verification: {criterion text}
Steps: {what a reviewer should do to confirm this works}

---

Step 7: Commit

After all tests pass, create a single commit:

git add {specific files}
git commit -m "$(cat <<'EOF'
{task.id}: {brief description}

- {what was added}
- {another change if relevant}

Acceptance Criteria:
- [x] {auto criterion 1}
- [x] {auto criterion 2}
- [ ] {manual criterion} — manual verification required

Co-Authored-By: Claude Sonnet <[e-mail]>
EOF
)"

Use a feature branch. Never push directly to main.

---

Step 8: Report Back

After committing, report your outcome:

If all auto criteria pass:

## Task Complete: {task.id}

Implemented:
- {what was built}

Tests:
- {N} tests added, all passing

Commits:
- {hash}: {message}

Manual Verification Needed:
- {criterion}: {verification steps}

If blocked:

## Task Blocked: {task.id}

Blocker: {specific description of what's wrong}

Attempted:
- {what you tried}

Needs:
- {what is required to unblock}

---

Quick Reference

Stack Detection Order

1. pom.xml present → Spring Boot → load springboot/SKILL.md
2. next.config.ts or next.config.js present → Next.js → load nextjs/SKILL.md
3. package.json only → Node.js → load nodejs/SKILL.md
4. No skill file found → log gap message → use general best practices

Criteria Tags

• [auto] — write a failing test first, implement until it passes
• [manual] — document verification steps in commit body or code comment

Contract Validation (v2 tasks)

• All five fields required: contract.input, contract.output, contract.invariant, test_plan (≥1 entry), files_owned (≥1 entry)
• Missing → emit task contract incomplete: {fields} and STOP
• Out-of-scope file needed → emit out-of-scope file required: {path} and STOP
• Never extend files_owned mid-task; never infer missing contract fields

Never

• Commit without running tests
• Push directly to main
• Implement more than the acceptance criteria require
• Skip the stack skill if it exists
• Use git add -A or git add . — stage specific files by name
• Edit a file outside files_owned (v2 tasks) — emit BLOCKED instead
• Guess or infer missing contract fields — emit BLOCKED instead