# Implement Task

> Implement a planned Jira task using TDD. Reads the approved plan, creates the branch, and executes red-green-refactor cycles. Usage: /implement-task MLID-XXXX OR /implement-task docs/agomez/plans/MLID-XXXX-short-description.md OR /implement-task MLID-XXXX stage-N (run only one stage of a staged plan) OR /implement-task MLID-XXXX worktree=yes (create the feature branch in a separate git worktree)

- Skill: `alejandrogomezforte/implement-task` (Agent Skill)
- Install (CLI): `npx skillmds@latest add alejandrogomezforte/implement-task`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alejandrogomezforte/implement-task/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: alejandrogomezforte (https://skillmd.com/u/alejandrogomezforte)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/alejandrogomezforte/implement-task

---


# /implement-task $ARGUMENTS

You are starting the **implementation phase** of the software workflow. The plan has been approved — now execute it using strict TDD.

## Step 1 — Resolve `$ARGUMENTS` to a task ID, plan file, optional stage, and worktree mode

`$ARGUMENTS` may contain a task reference (Jira task ID or plan file path), an **optional stage selector**, and an **optional worktree selector**. Normalize before doing anything else and produce four values: `<task_id>`, `<plan_file>`, `<stage>` (an integer, or empty), and `<worktree>` (`yes` or `no`).

**First, split off the optional worktree selector.** Tokenize `$ARGUMENTS` on whitespace. If any token matches `worktree[=\s]?(yes|no|true|false|y|n)` (case insensitive), set `<worktree>` accordingly (`true`/`y` count as `yes`, `false`/`n` count as `no`) and remove that token. **If no such token is present, `<worktree>` defaults to `no`** — worktree mode is strictly opt-in and omitting the parameter keeps the historical behavior.

**Then split off the optional stage selector.** From the remaining tokens, if the **last** token matches `stage[-\s]?(\d+)` (e.g. `stage-2`, `stage 2`, `stage2`) or is a **bare integer** (e.g. `2`), set `<stage>` to that number and remove the token. The remaining string is `<task_ref>`. If no such token is present, `<stage>` is empty and `<task_ref>` is what remains.

> A plan-file path (contains `/` or ends `.md`) and a Jira ID (`MLID-\d+`) never look like a bare integer, `stage-N`, or `worktree=...`, so this split is unambiguous. The selectors may appear in any order, so `/implement-task MLID-1868 worktree=yes stage-2` and `/implement-task MLID-1868 stage-2 worktree=yes` are equivalent.

**Then resolve `<task_ref>` to `<task_id>` and `<plan_file>`:**

**If `<task_ref>` contains `/` or ends with `.md`** — treat it as a plan file path:
- `<plan_file>` = `<task_ref>` (verify the file exists; if not, **STOP** and report the bad path)
- `<task_id>` = the first `MLID-\d+` token found in the filename (e.g., `docs/agomez/plans/MLID-1868-foo.md` → `MLID-1868`). If no Jira ID is found in the filename, **STOP** and ask the user for the task ID explicitly.

**Otherwise** — treat `<task_ref>` as a Jira task ID:
- `<task_id>` = `<task_ref>`
- `<plan_file>` = the result of globbing `docs/agomez/plans/<task_id>*.md`. If zero matches, **STOP** and tell the user to run `/plan-task <task_id>` first. If multiple matches, **STOP** and ask the user to pass the explicit plan file path.

For the rest of this skill, use `<task_id>` wherever a Jira ID is needed (branch names, commit messages, the `/verify-task` handoff). Use `<plan_file>` to read the plan.

If the plan is for an epic sub-task, also read the epic plan-progress file for overall context.

Read `<plan_file>` completely. This is your implementation roadmap.

## Step 1b — Scope to the requested stage (only when `<stage>` is set)

If `<stage>` is empty, skip this step — you will implement the entire plan.

If `<stage>` is set:
- Confirm the plan is a **staged plan** (it has a "Stage map" table and `### Stage N` sections). If it is not staged, **STOP** and tell the user this plan has no stages, so they should run `/implement-task <task_id>` without a stage selector.
- Confirm a `### Stage <stage>` section exists. If not, **STOP** and list the stages the plan actually defines.
- Your implementation scope for this run is **only the steps under `### Stage <stage>`** (all its `#### Step <stage>.x` sub-steps). Do not implement steps from any other stage.
- Check the stage's **Depends on** entry in the Stage map. If earlier stages it depends on do not appear to be implemented yet on the current branch, surface that to the user before proceeding (they may have intentionally jumped ahead, but flag it once).
- Briefly tell the user which stage you are about to implement and its end-of-stage testable outcome (from the Stage map), then proceed.

## Step 2 — Create the feature branch

Read `<base_branch>` from the plan file: `develop` for a standalone task, or the epic branch (`epic/MLID-XXXX-epic-name`) for an epic sub-task.

Then follow **Step 2a** or **Step 2b** depending on `<worktree>`.

### Step 2a — Main working directory (`<worktree>` = `no`)

Check the current git branch. If not already on the correct feature branch:

```bash
git checkout <base_branch>
git pull origin <base_branch>
git checkout -b feature/<task_id>-short-description
```

If the branch already exists (resuming work), just check it out.

### Step 2b — Separate git worktree (`<worktree>` = `yes`)

The worktree lives at `../worktrees/<task_id>` relative to the repository root — a sibling of the main checkout, matching the existing convention (for example `Dev/worktrees/MLID-2740`). Do **not** use the harness's default `.claude/worktrees/` location, and do **not** create the worktree with `EnterWorktree` — it branches from the default branch and would ignore an epic base branch.

**1. Check whether the worktree already exists** (resuming work):

```bash
git worktree list
```

If `../worktrees/<task_id>` is already listed, skip to sub-step 4 (enter it) and then skip any setup whose output already exists.

**2. Update the base branch and create the worktree** from the main working directory:

```bash
git checkout <base_branch>
git pull origin <base_branch>
git worktree add -b feature/<task_id>-short-description ../worktrees/<task_id> <base_branch>
```

If the feature branch already exists but has no worktree, omit `-b` and pass the existing branch name instead:

```bash
git worktree add ../worktrees/<task_id> feature/<task_id>-short-description
```

**3. Copy the gitignored environment files** from the main working directory into the new worktree. These are not tracked by git, so the worktree starts without them and nothing will run:

```bash
cp .env.local ../worktrees/<task_id>/.env.local
cp apps/web/.env.local ../worktrees/<task_id>/apps/web/.env.local
```

If either file does not exist in the main working directory, say so and continue — do not invent one.

**4. Switch the session into the worktree** using the `EnterWorktree` tool with the `path` parameter set to the worktree path (not `name`, which would create a new one in the wrong place). Every later file edit, test run, and git command in this skill then happens inside the worktree.

**5. Install dependencies** inside the worktree. A fresh worktree has no `node_modules`, so tests cannot run until this finishes:

```bash
npm install
```

> **This is the one place `/implement-task` may run `npm install` without stopping to ask.** The user authorized it specifically for worktree setup. It does not extend to adding, removing, or upgrading packages — those still need explicit permission, and the install here must be a plain `npm install` with no package arguments and no flags that change the lockfile.

Skip this sub-step if `node_modules` already exists at the worktree root (resuming work).

**6. Confirm the setup** before starting TDD. Tell the user the worktree path, the branch name, the base branch it was created from, and that dependencies are installed. Then proceed to Step 3.

## Step 3 — Execute TDD cycles

Follow the implementation steps from the plan. For each step:

### RED — Write a failing test first
- Create or modify the test file
- Write test cases that describe the expected behavior
- Run the test to confirm it fails: `cd apps/web && npx jest --testPathPattern="<test-file>" --no-coverage`
- The test must fail for the **right reason** (missing implementation, not syntax errors)

### GREEN — Write the full implementation and pass the test
- Write the complete, clean implementation for the current step (no stubs or throwaway code)
- Clean up naming, structure, and duplication as you go
- Run the test to confirm it passes

## Step 4 — Repeat for each implementation step

Work through the implementation steps sequentially. **Respect the scope from Step 1b:** if `<stage>` is set, implement only the steps under `### Stage <stage>` and then stop — do NOT continue into the next stage. If `<stage>` is empty, work through every step in the plan.

## Step 5 — Signal completion

When the steps in scope are done:

1. Run the full test suite for the affected files.
2. **If `<worktree>` = `yes`**, remind the user where the work lives: the worktree path, the branch name, and that this session is currently inside the worktree — so `/verify-task` and any commits should be run from this same session. Also tell them the dev server for manual testing must be started from the worktree directory, not the main checkout.
3. Signal completion, scoped to what was run:
   - **If a single stage was implemented** (`<stage>` set): tell the user "Stage `<stage>` implemented. You can now test it in the browser — <restate the stage's end-of-stage testable outcome from the Stage map>. When it looks right, run `/verify-task <task_id>` for the quality gates and commit this stage. Then run `/implement-task <task_id> stage-<next>` for the next stage." (Use the actual next stage number, or say it was the final stage if there is none.)
   - **If the whole plan was implemented** (`<stage>` empty): tell the user "Implementation complete. You can now test the UI manually. When ready, run `/verify-task <task_id>` to check quality gates."

## Important Rules

- **Follow the plan** — don't deviate from the approved implementation steps without discussing with the user
- **TDD is mandatory** — never write implementation code before its test
- **Never commit** — do NOT commit. The user will commit manually when ready
- **Never remove a worktree** — do NOT call `ExitWorktree` with `remove`, and do NOT run `git worktree remove`. The worktree and its branch stay on disk until the user says otherwise, the same way feature branches are never deleted without permission
- **No `any` types** — use proper TypeScript types
- **No `console.log`** — use `logger` from `@/utils/logger`
- **Named exports only** — no default exports (except Next.js pages/layouts)
- **Commit format** (when user asks): `[<task_id>] - type(scope): description` — no Co-Authored-By