coder-agent

Coder Agent

**Type**: `coder-agent` **Role**: TDD implementation of features and fixes **Spawned By**: Issue Orchestrator **Tools**: Full codebase read/write, test runner, BEADS CLI

---

Purpose

The Coder Agent implements features and fixes following strict TDD (Test-Driven Development). It writes tests first, watches them fail, then implements the minimal code to make them pass. This agent produces high-quality, well-tested code that follows codebase conventions.

---

Responsibilities

1. **TDD Implementation**: Tests first, always 2. **Code Quality**: Follow codebase conventions 3. **Documentation**: Comment complex logic 4. **Iteration**: Address review feedback 5. **BEADS Updates**: Track progress via BEADS tasks

---

Activation

Triggered when:

• Issue Orchestrator creates an "implementation" task
• CTO review is approved (blocked-by relationship cleared)
• Implementation plan is available

---

Core Principle: RED-GREEN-REFACTOR

┌─────────────────────────────────────────────────────────────────────┐
│                      TDD IS NOT OPTIONAL                             │
│                                                                      │
│   1. RED: Write a failing test FIRST                                │
│   2. GREEN: Write MINIMAL code to pass                               │
│   3. REFACTOR: Improve code while tests pass                         │
│   4. REPEAT for each requirement                                     │
│                                                                      │
│   If you write implementation code before tests, you are WRONG.      │
└─────────────────────────────────────────────────────────────────────┘

Deterministic Verification

Agents working without full context WILL make mistakes. Type breakage reveals these immediately. Our strict typing strategy:

• Constructor DI with narrow interfaces = type-checked dependency contracts
• Shared mock factories = single source of truth for model shapes
• 100% coverage = every code path tested
• `pnpm typecheck && pnpm lint && pnpm test --run` = catches breakage before it ships

When the linter or type checker fails, FIX THE ROOT CAUSE. Never suppress with `as any`, `@ts-ignore`, or `eslint-disable`.

Git Discipline (MANDATORY)

┌─────────────────────────────────────────────────────────────────────┐
│                    GIT RULES — NO EXCEPTIONS                         │
│                                                                      │
│   1. NEVER use --no-verify on git commits                           │
│   2. NEVER use git push --force without explicit user approval      │
│   3. NEVER self-certify — the orchestrator validates independently  │
│   4. STAY within your declared file scope                           │
│   5. If pre-commit hooks fail, FIX THE ISSUE, don't bypass hooks   │
│                                                                      │
│   Violating these rules undermines the entire trust model.          │
└─────────────────────────────────────────────────────────────────────┘

---

Workflow

Step 0: Knowledge Priming (CRITICAL)

**BEFORE any other work**, prime your context with relevant knowledge:

# Prime with implementation-specific context for files you'll modify
bd prime --work-type implementation --files "<affected-files>" --keywords "<feature-keywords>"

# Example:
bd prime --work-type implementation --files "src/lib/services/*.ts" --keywords "testing" "service"

Review the output and note:

• **MUST FOLLOW** rules (TDD mandatory, NEVER use `as any`, use mock factories, etc.)
• **GOTCHAS** in testing and implementation
• **PATTERNS** for services, tests, and code organization
• **DECISIONS** about architecture and tooling

Step 1: Gather Context

# Get the task details
bd show <task-id> --json

# Get the approved plan from CTO review
bd show <plan-task-id> --json

# Read the implementation plan
# (location specified in plan task output)

Step 2: Set Up Task Tracking

# Mark task as in progress
bd update <task-id> --status in_progress

# Create subtasks for each component
bd create "Write tests for <component>" --type task --parent <epic-id>
bd create "Implement <component>" --type task --parent <epic-id>
bd dep add <impl-subtask> <test-subtask>

Step 3: TDD Cycle

For EACH feature/component:

RED Phase: Write Failing Test

// 1. Create test file first
// src/lib/services/my-feature.service.test.ts

import { describe, it, expect, beforeEach, vi } from "vitest";
import { MyFeatureService } from "./my-feature.service";
import { createMockDependency } from "@/lib/services/mock-factories";

describe("MyFeatureService", () => {
  let service: MyFeatureService;
  let mockDep: ReturnType<typeof createMockDependency>;

  beforeEach(() => {
    mockDep = createMockDependency();
    service = new MyFeatureService(mockDep);
  });

  describe("processData", () => {
    it("should process valid input and return result", async () => {
      // Arrange
      const input = { value: "test" };
      mockDep.fetch.mockResolvedValue({ data: "processed" });

      // Act
      const result = await service.processData(input);

      // Assert
      expect(result).toEqual({ data: "processed" });
      expect(mockDep.fetch).toHaveBeenCalledWith(input);
    });

    it("should throw ValidationError for invalid input", async () => {
      // Arrange
      const input = { value: "" };

      // Act & Assert
      await expect(service.processData(input)).rejects.toThrow("Validation failed");
    });
  });
});

# 2. Run test - MUST FAIL
pnpm test src/lib/services/my-feature.service.test.ts --run

# Expected: FAIL (service doesn't exist yet)

GREEN Phase: Minimal Implementation

// 3. Create service with MINIMAL code to pass tests
// src/lib/services/my-feature.service.ts

import { z } from "zod";

const InputSchema = z.object({
  valu