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

1. •

   Read task file (MANDATORY):

   • •Look for task file in docs/reference/frontend/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-profile Task 1" or "implement standalone-fix-login 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
2. •

   Read constraints FIRST (before any code):

   • •docs/reference/frontend/design-system.md - Colors, typography, spacing
   • •docs/reference/frontend/constraints.md - Tech stack, patterns
   • •If task references design: docs/reference/frontend/designs/{name}.md
3. •

   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
4. •

   After all steps:

   • •Run unit tests
   • •Run build check
5. •

   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
6. •

   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-profile Task 1
• •implement standalone-fix-login 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

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

Error Handling

Updating Task File

After successful implementation, update the task file. Both story-based and standalone use the same update process:

1. Mark Task's Acceptance Criteria as Completed

## Task 1: Setup Component

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

### Acceptance Criteria

- [x] Logo displays correctly ← Changed from [ ]
- [x] Title uses correct typography ← Changed from [ ]
- [x] Header is responsive ← Changed from [ ]

2. Update Progress Section

## Progress

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

**Next task**: Task 2: Implement Header ← 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/:

### Frontend Tasks

- [x] Task 1: Setup Component ← Changed from [ ]
- [ ] Task 2: Implement Header
- [ ] Task 3: Add Tests

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

1. •getByRole - accessible by everyone
2. •getByLabelText - form fields
3. •getByText - non-interactive elements
4. •getByTestId - last resort

Test Coverage Requirements

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 Task 1"
# (Works the same for standalone: "Implement standalone-fix-login Task 1")

1. ✓ Read task file: docs/reference/frontend/tasks/story-user-profile.md
   - Extract Task 1 section from the file
2. ✓ Read constraints:
   - design-system.md
   - constraints.md
   - designs/user-profile.md (if referenced)

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

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

5. ✓ Execute Step 3: Add tests
   → Run: npm test Component
   → ✓ 3 tests passed

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

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

8. ✓ Update task file:
   - Updated Task 1 section
   - Marked all AC as completed
   - Status: completed
   - Updated Progress: 1/5 completed

9. ✓ Update Story file (story-based only):
   - Marked Task 1 checkbox in PM story file

10. ✓ Task completed! Progress: 1/5 tasks

Iron Law

NO CODE WITHOUT TASK FILE

This rule is non-negotiable. Before writing code:

1. •Task file must exist
2. •Acceptance criteria must be defined
3. •Implementation steps must be clear

Rationalization Defense