Aico Frontend Implement

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

0. Read task file (MANDATORY):

   • Look for task file in docs/reference/frontend/tasks/
   • Accept either:
     • story-{story-name}-{number}-{task-name}.md
     • standalone-{task-name}.md
   • If NOT exists → STOP and ask user which task to implement

1. 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

2. Execute implementation steps:

   • Read "Implementation Steps" section from task file
   • Execute each step in order
   • Run verification command after each step
   • If fail → fix before proceeding
   • If pass → continue to next step

3. After all steps:

   • Run unit tests
   • Run build check

4. Update task status:

   • Mark acceptance criteria checkboxes: - [ ] → - [x]
   • Change Status from pending to completed

5. Notify completion:

   • Show task file path
   • Show completion status
   • Check related Story (if task is from story breakdown):
     • Read > **Story**: field from task file
     • 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 for this story
     • If all story tasks completed, show: "✅ All tasks completed! Story {story-name} is ready for acceptance. Please notify PM to verify."
     • If partial completion, show: "⏳ Story {story-name} progress: X/Y tasks completed"

Task File Format

The implement skill reads task files in this format:

# Task: [Task Name]

> **File**: `story-{name}-{n}-{task}.md` or `standalone-{task}.md`
> **Status**: pending | in_progress | completed

## Description

...

## Acceptance Criteria

- [ ] Criterion 1
- [ ] Criterion 2

## Implementation Steps

### Step 1: [Action]

**Files**: ...
**Action**: ...
**Verify**: ...

### Step 2: [Action]

...

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:

1. Mark Acceptance Criteria as Completed

## Acceptance Criteria

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

2. Update Status

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

3. Add Completion Notes (optional)

## Notes

- Implemented on YYYY-MM-DD
- All tests passing
- Used design tokens from design-system.md

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 />)
  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-2-header"

1. ✓ Read task: docs/reference/frontend/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:

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

Rationalization Defense