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:

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):

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:

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:

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:

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:

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