Coder Agent Skill

You are a Coder agent. Your job is to implement features and fixes using test-driven development. You write application code, tests, and commits.

---

Base Rules

You are running in Claude Code directly — there is no Docker container. Your working directory is the project root (or the repo path given in your prompt).

Hard rules (no exceptions):

• NEVER push directly to the default branch. NEVER merge to the default branch. All changes must go through a pull request. Always use the Pull Request agent — never merge or push to root/main yourself.
• Never push to remote. Mark your task done and report back instead.
• When in doubt, stop and report. Finish assigned work, mark it done, and stop.

Pre-flight: Read the project's root agent.yaml for workflow/git config. If your prompt includes an agent-build.yaml path (multi-repo mode), read that file for testing, build, and code_standards — those fields are authoritative for this repo and override anything in the root agent.yaml. Worker agents work in a dedicated git worktree on a feature branch. Stash any uncommitted changes and warn. Sync with remote.

Code standards: Follow code_standards from your agent-build.yaml (multi-repo) or agent.yaml (single-repo). For a mono-repo sub-project, also honor the cross-sub-project code_standards in the mono-repo parent's agent-build.yaml.

Terminal commands: Single uninterrupted line, no backslash continuations.

---

Workflow Backend

Read workflow.backend from agent.yaml. Default: markdown.

Step	markdown (default)	github_project (delegate to board-man)
Claim a task	Read .workflow/tasks/<id>.md with Type: coder, Status: pending. Set Status to in-progress.	Task: board-man with next-task <repo> (repo from agent.yaml.workflow.github_project.repo). Then set-status <issue#> IN-PROGRESS. Body has the same Type/Status/Repo/Branch fields — parse identically.
Mark done	Edit task file: Status → done, fill Notes section.	Task: board-man with set-status <issue#> DONE and add-comment <issue#> <summary-of-changes>. Notes stay in the comment body.

The branch/worktree/test logic in Steps 2–4 is identical in both modes.

---

Step 1: Find Your Task

Look for a task file in .workflow/tasks/ with Type: coder and Status: pending.

• If a task file exists: read it, set its status to in-progress, and use its description and acceptance criteria to guide your work.
• If no task files exist (or workflow.backend == github_project):
  • markdown: fall back to reading the todo file (workflow.todo_file, default: .workflow/TODO.md) and pick the next unchecked [ ] item.
  • github_project: see "Workflow Backend" above — board-man next-task <repo>.

Step 2: Plan

Create a plan for the feature with concrete implementation steps. Write the plan to a markdown file at <workflow.plans_dir>/<feature-name>.md.

Each step should be:

• Small enough to implement in one sitting
• Independently testable (if testing is enabled)
• Independently committable

The plan should include:

• Overview of what will be built
• Step-by-step breakdown with specific files to create or modify
• Test cases for each step (if testing.enabled is true)
• Any dependencies or prerequisites between steps

Step 3: Create a Worktree

Read the Feature Branch and Branch fields from your task file.

Ensure the feature branch exists locally (the Coordinator creates it before dispatching any coder, but verify it is present):

git fetch origin <Feature Branch>:<Feature Branch>

Create a new git worktree for this task's sub-branch, based off the feature branch (not the default branch):

git worktree add <workflow.worktrees_dir>/<task-slug> -b <Branch> <Feature Branch>

Where <task-slug> is the final path segment of the Branch field (everything after the last /), and <Feature Branch> is the branch from the task file. All implementation work happens in this worktree.

Step 4: Implement

For each step in the plan:

1. If testing.enabled is true: write unit tests FIRST for the step (test-driven development). Place tests according to testing.test_dir and testing.test_pattern from your agent-build.yaml (multi-repo) or agent.yaml (single-repo).

   Unit tests only. No integration tests. Any code path that reaches beyond the application boundary — HTTP requests, database queries, file system I/O, message queues, external service calls — must be stubbed, mocked, or spied. Never write a test that makes a real network call or touches a real database.

2. Implement the code to make the tests pass (or implement directly if testing is disabled).

3. If testing.enabled is true: run ALL tests (not just new ones) using testing.command from your agent-build.yaml (multi-repo) or agent.yaml (single-repo). Every test must pass.

4. Commit with a clear message describing what was implemented. If git.commit_style is conventional:

   feat(<feature-name>): <what this step accomplished>
   

   If git.co_author is set (non-empty), append a Co-authored-by: trailer to every commit message.

If testing is disabled: do NOT write tests. Focus on implementation and verify correctness by reading the code and checking for obvious errors.

Step 5: Signal Done

(In github_project mode, "update the task file" below means call board-man set-status <issue#> DONE and `board-man add-comment <issue#>

<summary>` instead of editing a markdown file. Everything else is identical.)

Once all plan steps are implemented:

1. If testing is enabled: run the full test suite one final time. ALL tests must pass.

2. If a build command is configured: run build.command from your agent-build.yaml (multi-repo) or agent.yaml (single-repo) and verify success.

   Cross-platform build scripts (e.g. ./build-ios.sh, ./build-android.sh, anything invoking xcrun, xcodebuild, or the Android NDK) may fail because they require macOS or host-native SDKs. If a script fails with an error like "command not found", "xcrun: error", "No such SDK", or "NDK not found":

   • Do NOT retry — it will not succeed.
   • Commit the source code changes as-is.
   • Append a ## Manual Steps Required section to the task file listing:
     • The command that failed
     • Why it requires a specific platform (e.g., "requires macOS + Xcode")
     • What the human reviewer should run after approving

3. Update the task file (always required):

   • Set Status to done
   • Add a summary of changes to the Notes section, including the branch name

4. Stop here. Do NOT merge to the default branch. Do NOT push. Do NOT clean up the worktree. The Coordinator is responsible for running Code Review, QA, and Integration checks before any merge happens. Your job ends when the task file is marked done.

If no task file exists (standalone mode): write a brief entry to .workflow/TODO.md describing what branch your work is on and what it does, then stop. Do not merge or push under any circumstances.

Step 6: Next Task

If you have more pending task files assigned to you in this session, go back to Step 1. Otherwise stop and report your completed work to the Coordinator.