---
name: x-implement
description: Implement or fix with TDD — parallelize independent tasks with x-parallel, apply x-ui for frontend work and x-unbloat to every change, red-green-refactor per task, verify with x-review + x-fix, gate on plan completion
version: 1.1.0
author: Community
tags: [tdd, implementation, test-driven, red-green-refactor, production-code, parallel, ui]
user-invocable: true
---

# X-Implement — Test-Driven Implementation
**No production code without a failing test first.** Wrote code before the test? Delete it. Rewrite from the test. Exception — confirm with a `confirm` panel (yes/no) first: prototypes, generated code, throwaway scripts.

## Artifact Location

```bash
node <path-to-save-plan.js> --epic <slug>
```
The script creates the staging directory. Read all `.md` files inside it — one file per user story.

## Directory Organization
Assign each responsibility to its own directory (models/, services/, controllers/, utils/, tests/). One file per concern, imports flow top-down, never cycle. See `references/dir-organization.md` for full guidance.

## Comments

Code must document itself. Comments are a last resort, reserved for what the code cannot express. Follow x-comments rules on every line you write.

- **No trivial comments.** Never restate what the code says (`i++`, `return user`). If the line reads fine alone, it needs no comment.
- **Only the *why*, never the *what*.** A comment earns its place only when the code cannot express the reason: a non-obvious workaround, a CPU-architecture or third-party provider quirk, the source of a magic value, an invariant, or what breaks if changed.
- **Prefer a better name or a smaller function over a comment.** If a block needs a paragraph to explain what it does, extract it into a descriptively named function and delete the paragraph.
- **Strip noise in REFACTOR.** Every refactor pass must remove comments that restate code, not just improve structure.

## No Bloat

Write the least code that works. Follow x-unbloat (`~/.agents/skills/x-unbloat/SKILL.md` for a global install, `.agents/skills/x-unbloat/SKILL.md` for a local one): its ladder before GREEN, and its ladder, table and Never Cut list in REFACTOR. Its rules are not repeated here, so read them there.

## Functional Style

Prefer a functional approach for readability. Side effects make code hard to reason about and test; isolate them at the edges.

- **Prefer pure functions.** Compute and return values instead of mutating inputs or external state. Given the same inputs, the same result — no hidden state.
- **Avoid side effects in the middle of logic.** Keep I/O, state mutation, and randomness at the boundaries; keep the core logic pure.
- **Prefer immutable data.** Return new values (`map`, `filter`, `reduce`) instead of mutating arrays or objects in place.
- **Prefer expressions over statements.** Chain transformations and use named intermediate values over loops that accumulate into mutable variables.
- **Pass data explicitly.** Return values rather than writing to shared/global state or relying on closures that hide dependencies.
- **Side effects are only acceptable where unavoidable** (I/O, DB, network) — and must be clearly named and isolated.
- **One responsibility per function; keep orchestrators thin.** Each phase (fetch, validate, probe, decrypt) is a named helper that returns data; the orchestrator only composes them. If a function both does a job and reports on it — a `push` closure appending to a shared `results` array inside every branch — the reporting is entangled with each responsibility; collect the report in exactly one place.
- **One responsibility per class and file too.** A class plays one role — persistence, validation, orchestration — not several. If a class's methods group by role rather than by shared state, split it; keep one file per concern (see Directory Organization).

## Parallelize Independent Tasks

Implement tasks in dependency order. When two or more tasks can run independently, dispatch them to background agents with x-parallel instead of doing them one by one.

1. Read every task file under `<run folder>/E<nn>-tasks/`.
2. A task is **independent** when no other pending task modifies the same files and no other task requires its output (check each file's `Preconditions` and `Files:`).
3. Independent tasks run concurrently:
   ```bash
   node <path-to-x-parallel>/scripts/parallel.mjs --tasks <run folder>/E<nn>-tasks --parallel 4
   ```
   x-parallel gives each task an isolated worktree and a full background agent, retries failures, and merges committed results back into your branch.
4. Tasks that depend on one another stay in the inline TDD loop below, in dependency order.
5. After an x-parallel batch merges, run the full test suite, then VERIFY (step 4) on the merged changes before updating the plan.

## Frontend Work Uses X-UI

When a task's scope includes UI (HTML/CSS, templates, components, or styles in any framework), apply the x-ui skill to everything you produce:

1. Read the x-ui skill's `SKILL.md` before writing any UI code — `~/.agents/skills/x-ui/SKILL.md` for a global install, `.agents/skills/x-ui/SKILL.md` for a local one.
2. Follow x-ui's method: state the screen's primary task, then build to its strict rules (element count limits, component selection, row actions, status display, pagination rules).
3. Run x-ui's Pre-Flight Checklist before VERIFY. A screen that fails any checklist item is not done.

## Workflow

For each task file in `<run folder>/E<nn>-tasks/`:

1. **RED** — Write the minimal failing test for the task's acceptance criterion. It must fail for the *right reason*.
2. **GREEN** — Write the minimum implementation to pass that test. Nothing more. Walk the x-unbloat ladder before writing.
3. **REFACTOR** — Evaluate against SOLID/clean code, the comment rules, the x-unbloat pass (steps 3, 5 and 7), and the functional style above. Strip comments that restate code; extract explained blocks into named functions; push side effects to the edges and prefer pure, immutable functions. State what you assessed and what (if anything) improved — or why no changes were needed.
   - **One-sentence test:** every function you wrote must be describable in one sentence; if not, split it.
   - **Reporting test:** if deleting a phase's `push`/output call leaves the phase unusable, the phase was never a unit. Delegate each phase to a named helper that returns data and let the orchestrator collect the report in one place.
4. **VERIFY — x-review + x-fix + test.** Run on every finished task before committing:
   - **Test** — run the task's tests and the full regression suite. All must pass.
   - **x-review** — run the review skill on the changed files. It writes a plan (`E<nn>-review-plan.md`) into the run folder, which `x-fix` reads.
   - **x-fix** — resolve every issue in the fix plan. Re-run tests after each fix.
   - Repeat x-review + x-fix until the plan has no unresolved issues and all tests are green.
5. **SYNC DOCS** — Update the spec (`<run folder>/E00-plan.md`) if it exists; otherwise update living docs (README, comments) directly.
6. **COMMIT** — Run `node <path-to-commit.mjs> "<message>"` from the x-commit skill for every single commit. This is mandatory and non-negotiable. Never run `git commit` manually. If x-commit exits with an error, stop and ask for a corrected message with an `open` panel (free text only) — do not bypass it.
7. **UPDATE PLAN** — Change `- [ ]` to `- [x]` for this task. Do not start the next task without this edit.

All tasks `- [x]` and green → close the run:

8. **CLOSE THE RUN** — With every task `[x]`:
   - Write `<run folder>/E<nn>-summary.md`: the epic's `goal:`, one line per completed task, and the test results.
   - Run `x-roast` on the summary, then `x-humanize` on it; each appends its own `E<nn>` artifact beside it.
   - Rewrite the summary from the humanized text.
   - If the epic carries an `issue:` and the repo has an `origin` remote, offer to post the summary with a `confirm` panel (yes/no); on yes run `gh issue comment <n> -F <summary>`. Never invent an issue number, and never post without the panel.

## Gate

Before committing: evaluate the implementation against SOLID principles, design patterns, clean code, and the functional style above (pure functions, immutability, side effects at the edges). State what you assessed and what (if anything) you improved — or why no changes were needed.

## Anti-Patterns
See `references/tdd-rules.md` for full list of anti-patterns. Comment noise (restating code, obvious comments, paragraphs that should be a function) is an anti-pattern too — see the Comments section. Scattered side effects and in-place mutation are anti-patterns as well — see the Functional Style section.