Task Implementation

Implement engineering tasks in isolated git worktrees using a test-first workflow. Read the task spec, build in a clean branch, write tests, implement, verify, and open a PR.

Workflow

START
  │
  ▼
┌──────────────────────────────┐
│ 1. Load Task Specification   │ ◄── docs/tasks/task-<id>.md or docs/TASKS.md
└──────────┬───────────────────┘
           │
           ▼
┌──────────────────────────────┐
│ 2. Load Project Context      │ ◄── PRD, Architecture, Brand Guidelines
└──────────┬───────────────────┘
           │
           ▼
┌──────────────────────────────┐
│ 3. Create Worktree & Branch  │ ◄── git worktree in .worktrees/
└──────────┬───────────────────┘
           │
           ▼
┌──────────────────────────────┐
│ 4. Implement (test-first)    │ ◄── Write tests → Write code → Pass tests
└──────────┬───────────────────┘
           │
           ▼
┌──────────────────────────────┐
│ 5. Verify                    │ ◄── Tests pass, coverage thresholds met
└──────────┬───────────────────┘
           │
           ▼
┌──────────────────────────────┐
│ 6. Update Documentation      │ ◄── TASKS.md, README if appropriate
└──────────┬───────────────────┘
           │
           ▼
┌──────────────────────────────┐
│ 7. Push & Create PR          │ ◄── Push branch, open PR via gh
└──────────────────────────────┘

Step 1: Load Task Specification

Read the task document. Identify which to load:

Extract from the task spec:

• •Title and ID — for branch naming and PR title
• •Files to create/modify — scope of changes
• •Acceptance criteria — drives test cases
• •Testing instructions — how to verify
• •Dependencies — other tasks that must be complete first

If the task has unmet dependencies, warn the user before proceeding.

Step 2: Load Project Context

Read these documents for implementation context:

Also scan the existing codebase to understand:

• •Project structure and conventions (naming, patterns, file organization)
• •Existing test patterns (framework, helpers, mocking approach)
• •Package manager (check lock files: pnpm-lock.yaml, yarn.lock, bun.lockb, package-lock.json)

Step 3: Create Worktree & Branch

Create an isolated worktree for the feature branch:

# Branch naming: feature/task-<id>-<short-description>
# Example: feature/task-3.1.2-login-form

BRANCH_NAME="feature/task-<id>-<short-description>"
WORKTREE_DIR=".worktrees/$BRANCH_NAME"

git worktree add -b "$BRANCH_NAME" "$WORKTREE_DIR"

All subsequent work happens inside the worktree directory. Change your working directory there.

Install dependencies in the worktree if needed (e.g., npm install, pnpm install).

Step 4: Implement (Test-First)

Follow this cycle for each piece of functionality:

4a. Write Tests First

From the acceptance criteria, write test cases that will fail:

• •One test per acceptance criterion minimum
• •Include edge cases mentioned in the task spec
• •Include a happy path and at least one error/boundary case
• •Follow existing test conventions in the project (framework, file location, naming)

Run the tests to confirm they fail (red phase).

4b. Write Implementation

Implement the minimum code to pass the tests:

• •Follow patterns from docs/ARCHITECTURE.md (directory structure, key abstractions)
• •Match existing code conventions (imports, naming, error handling)
• •If the task involves UI and docs/BRAND-GUIDELINES.md exists, follow its design tokens and patterns
• •Keep changes scoped to files listed in the task spec — avoid unrelated modifications

4c. Pass Tests

Run the test suite. Iterate on implementation until all tests pass (green phase).

4d. Refactor

Clean up implementation while keeping tests green. Remove duplication, improve naming, extract constants. Do not add functionality beyond what the tests cover.

4e. Commit

Make atomic commits as logical units of work complete. Use conventional commit messages:

feat(scope): short description of what was added
test(scope): add tests for <feature>

Step 5: Verify

Run full verification before considering the task done:

# Run full test suite (not just new tests)
<package-manager> test

# Check coverage thresholds pass
<package-manager> test -- --coverage

# Lint passes
<package-manager> run lint

# Type check passes (TypeScript projects)
<package-manager> run typecheck

# Build succeeds
<package-manager> run build

All checks must pass. If coverage thresholds are configured in the project (e.g., in vitest.config.ts or jest.config.ts), ensure they are met. If no thresholds are configured, aim for:

If any check fails, fix the issue and re-run. Do not proceed with failures.

Step 6: Update Documentation

Mark Task Complete in TASKS.md

In docs/TASKS.md, mark the completed task:

• •Change - [ ] to - [x] for completed acceptance criteria
• •Mark the task checkbox as complete
• •If all tasks in a story are done, mark the story complete too

Update README (When Appropriate)

Update the project README if the task:

• •Adds a new user-facing feature or command
• •Changes setup/installation steps
• •Adds new environment variables or configuration
• •Changes API endpoints

Do not update README for internal refactors, test additions, or implementation details.

Step 7: Push & Create PR

git push -u origin "$BRANCH_NAME"

Create a PR using gh:

gh pr create --title "<type>(task-<id>): <short title>" --body "$(cat <<'EOF'
## Summary

Implements task <id>: <task title>

### Changes
- <bullet points of what was done>

### Acceptance Criteria
- [x] <criterion 1>
- [x] <criterion 2>

## Test Plan

### Automated
- <commands to run, e.g. `pnpm test`, `pnpm run lint`>

### Manual QA
- [ ] <visual/interactive verification step for a human or QA agent with browser access>
- [ ] <another manual check if applicable>

## Task Reference
- Task spec: `docs/tasks/task-<id>.md`

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

After PR creation, report the PR URL to the user.

Error Recovery

Cleanup

After the PR is merged (not before), the worktree can be removed:

git worktree remove ".worktrees/$BRANCH_NAME"
git branch -d "$BRANCH_NAME"

Do not clean up automatically — only when the user requests it or confirms the PR is merged.