Implement

Language Configuration

Before generating any content, check aico.json in project root for language field to determine the output language. If not set, default to English.

Process

Read task file (MANDATORY):
- Look for task file in docs/reference/backend/tasks/
- Accept either:
  - Story-based: story-{story-name}.md with task number
  - Standalone: standalone-{task-name}.md with task number
- User must specify task number (e.g., "implement story-user-api Task 1" or "implement standalone-fix-auth Task 1")
- Both formats contain multiple tasks, just different naming
- If NOT exists or task number not specified → STOP and ask user which task to implement
Read constraints FIRST (before any code):
- docs/reference/backend/design-system.md - Colors, typography, spacing
- docs/reference/backend/constraints.md - Tech stack, patterns
- If task references design: docs/reference/backend/designs/{name}.md
Execute implementation steps:
- Read "Implementation Steps" section from task
- Execute each step in order
- Run verification command after each step
- If fail → fix before proceeding
- If pass → continue to next step
After all steps:
- Run unit tests
- Run build check
Update task status:
- Update the specific task section in the file
- Mark acceptance criteria checkboxes: - [ ] → - [x]
- Change Status from pending to completed
- Update "Progress" section at bottom of file
- Both story-based and standalone files use the same format
Notify completion:
- Show task file path and task number
- Show completion status
- Check related Story (story-based only):
  - Read > **Story**: field from file header
  - If Story exists, check story file at docs/reference/pm/stories/
  - Update Story's Related Tasks section: mark this task as - [x]
  - Count total vs completed tasks
  - If all tasks completed, show: "✅ All tasks completed! Story {story-name} is ready for acceptance."
  - If partial completion, show: "⏳ Progress: X/Y tasks completed"

Task File Format

See Task File Template for complete structure.

Both story-based and standalone tasks use the same file structure - the only difference is the filename:

Story-based: story-{story-name}.md (from PM story breakdown)
Standalone: standalone-{task-name}.md (from plan/ad-hoc requirements)

Usage Examples:

implement story-user-api Task 1
implement standalone-fix-auth Task 1

Execution Flow

Read Task File
     ↓
Read Constraints (design-system.md, constraints.md, designs/)
     ↓
Execute Step 1 → Verify → Pass? → Continue
                      ↓
                     Fail → Fix → Retry
     ↓
Execute Step 2 → Verify → Pass? → Continue
     ↓
     ...
     ↓
Run Unit Tests
     ↓
Run Build Check
     ↓
Update Task File (mark AC completed, update status)
     ↓
Show Completion Summary

Step Execution Rules

Rule 1: Follow Constraints Exactly

// ❌ Wrong: Ignore design system
<button className="bg-blue-500 text-white">

// ✅ Right: Use design tokens
<button className="bg-primary text-primary-foreground">

Rule 2: Verify Before Proceeding

Each step has a Verify section - MUST run it and confirm expected output before moving on.

Rule 3: No Skipping

Execute ALL steps in order
Do NOT combine steps
Do NOT skip verification

Post-Implementation Checklist

Run tests: npm test [component]
Run build: npm run build
Update task file:
- Mark AC checkboxes: - [x]
- Update Status: completed
Show completion summary to user

Error Handling

| Error Type | Action | | -------------------- | -------------------------------------- | | TypeScript error | Fix type issues, re-verify | | Test failure | Debug test, fix implementation or test | | Build failure | Check imports, fix errors | | Constraint violation | Re-read constraints, align code |

Updating Task File

After successful implementation, update the task file. Both story-based and standalone files use the same format, so the update process is identical:

1. Mark Task's Acceptance Criteria as Completed

## Task 1: Define Types

> **Status**: completed ← Changed from pending

### Acceptance Criteria

- [x] Types defined correctly ← Changed from [ ]
- [x] Exported from index ← Changed from [ ]
- [x] No type errors ← Changed from [ ]

2. Update Progress Section

## Progress

- Total tasks: 6
- Completed: 1 ← Changed from 0
- In progress: 0
- Pending: 5 ← Changed from 6

**Next task**: Task 2: Database Schema ← Update this

3. Update Story File Checkboxes (story-based only)

If this is a story-based task, update the PM story file at docs/reference/pm/stories/:

### Backend Tasks

- [x] Task 1: Define Types ← Changed from [ ]
- [ ] Task 2: Database Schema
- [ ] Task 3: Repository Layer

Key Rules

ALWAYS read task file first
ALWAYS read all constraint files before writing any code
MUST run verification command for each step
ALWAYS run tests before marking task complete
MUST update task file (mark AC, update status)

Common Mistakes

❌ Start without reading task file → ✅ ALWAYS read task file first
❌ Skip reading constraints → ✅ ALWAYS read before coding
❌ Skip verification → ✅ Run verify command for each step
❌ Skip tests → ✅ Run tests before marking complete
❌ Forget to update task file → ✅ Update AC and status

TDD Deep Dive

The TDD Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Write code before the test? Delete it. Start over.

Red-Green-Refactor Cycle

RED → Verify Fails → GREEN → Verify Passes → REFACTOR → Repeat

1. RED - Write Failing Test

test('Button shows loading state when clicked', async () => {
  render(<SubmitButton onClick={mockSubmit} />)
  await userEvent.click(screen.getByRole('button'))
  expect(screen.getByRole('button')).toBeDisabled()
  expect(screen.getByTestId('spinner')).toBeInTheDocument()
})

2. Verify RED - Watch It Fail

npm test -- --watch ComponentName

3. GREEN - Write Minimal Code

Write simplest code to pass the test. Don't add features not in test.

4. Verify GREEN - Watch It Pass

5. REFACTOR - Clean Up

Only after green. Keep tests passing.

Testing Library Query Priority

getByRole - accessible by everyone
getByLabelText - form fields
getByText - non-interactive elements
getByTestId - last resort

Test Coverage Requirements

| Component Type | Required Tests | | -------------- | -------------------------------- | | UI Component | Render, props, variants | | Form | Validation, submit, error states | | Interactive | User events, callbacks | | Data Display | Loading, error, empty states |

TDD Red Flags - STOP and Start Over

Code before test
Test passes immediately
Testing implementation details
querySelector everywhere

Example Workflow

# User: "Implement story-user-profile-2-header"

1. ✓ Read task: docs/reference/backend/tasks/story-user-profile-2-header.md
2. ✓ Read constraints:
   - design-system.md
   - constraints.md
   - designs/user-profile.md

3. ✓ Execute Step 1: Create component file
   → Run: npm run typecheck
   → ✓ Pass

4. ✓ Execute Step 2: Implement header layout
   → Run: npm run dev
   → ✓ Pass

5. ✓ Execute Step 3: Add responsive styles
   → Run: npm run dev (test at different breakpoints)
   → ✓ Pass

6. ✓ Execute Step 4: Add unit tests
   → Run: npm test LoginHeader
   → ✓ 3 tests passed

7. ✓ Run full test suite
   → Run: npm test
   → ✓ All tests passed

8. ✓ Run build
   → Run: npm run build
   → ✓ Build successful

9. ✓ Update task file:
   - Marked all AC as completed
   - Status: completed

10. ✓ Task completed!

Iron Law

NO CODE WITHOUT TASK FILE

This rule is non-negotiable. Before writing code:

Task file must exist
Acceptance criteria must be defined
Implementation steps must be clear

Rationalization Defense

| Excuse | Reality | | ------------------------------ | ------------------------------------------- | | "It's a simple change" | Simple changes often have hidden complexity | | "I'll document after coding" | Post-hoc documentation is always incomplete | | "Tests can wait until later" | Untested code is broken code | | "I know what needs to be done" | Assumptions without validation cause bugs |