Environment & tools setup

1.1 Verify prerequisites

Open a terminal and verify:

node --version    # Should display v18+ or v20+
npm --version     # Should display 9+
git --version     # Should display 2.x+

1.2 Configure the AI tool

Choose one of the following options:

Option A: Cursor (recommended)

1. Download Cursor from cursor.com
2. Connect your account (Claude or OpenAI)
3. Enable Composer mode (Ctrl+I)

Option B: Claude Code CLI

npm install -g @anthropic-ai/claude-code
claude    # Launch Claude Code in your terminal

1.3 Create the GitHub repo

1. Go to github.com/new
2. Name: taskflow-aidd
3. Visibility: Public
4. Check Add a README file
5. Click Create repository

git clone https://github.com/YOUR_USERNAME/taskflow-aidd.git
cd taskflow-aidd

1.4 Create the Firebase project

1. Go to console.firebase.google.com
2. Create a project called "taskflow-aidd"
3. Enable Authentication → Email/Password
4. Enable Firestore Database in test mode
5. Add a Web app and copy the config

Vision.md & specifications

Before writing a single line of code, document what you are going to build.

2.1 Create the vision.md

Create a vision.md file at the project root with the following content. Adapt it to your preferences:

# TaskFlow - Vision Document

## Summary
Collaborative task management application allowing users to
create, organize, and track their tasks with authentication
and persistent data.

## Tech Stack
- **Frontend**: Next.js 14, TypeScript, Tailwind CSS
- **Auth**: Firebase Authentication (email/password)
- **Database**: Firestore (NoSQL, real-time)
- **Hosting**: Vercel (continuous deployment via GitHub)

## Architecture
- App Router (src/app/)
- Server Components by default, Client Components for interactivity
- AuthContext for session management
- Firestore for persistence ("tasks" collection per user)

## User Stories (MoSCoW)
### Must Have
- [ ] US1: Create a task (title, description, priority, due date)
- [ ] US2: View task list with sorting and filters
- [ ] US3: Mark a task as completed
- [ ] US4: Sign in / sign up by email

### Should Have
- [ ] US5: Edit an existing task
- [ ] US6: Delete a task
- [ ] US7: Filter by priority (high/medium/low)

### Could Have
- [ ] US8: Dashboard with statistics
- [ ] US9: Dark mode
- [ ] US10: Export tasks to CSV

## Architecture Decisions
- Firestore over PostgreSQL: no need for complex relations,
  native real-time, free for workshop volume
- Tailwind over CSS modules: faster prototyping,
  design system consistency
- App Router over Pages Router: Next.js 14+ standard,
  better Server Components support

2.2 Create the GitHub Issues

For each Must Have User Story, create an Issue on GitHub:

1. Go to the Issues tab of your repo
2. Create 4 issues (US1 to US4) with:
   • Title: use the US title
   • Description: detailed acceptance criteria
   • Label: must-have

2.3 Commit the vision.md

git add vision.md
git commit -m "docs: add vision document with architecture and user stories"
git push

Scaffolding & initial deployment

3.1 Create the Next.js project

npx create-next-app@latest . --typescript --tailwind --app --eslint --src-dir --import-alias "@/*"

Answer Yes to all questions. The . creates the project in the current folder.

3.2 Install Firebase

npm install firebase

3.3 Scaffolding prompt (AIDD)

Open your AI tool and send this prompt:

Context: Freshly created Next.js 14 + TypeScript + Tailwind CSS project.
Firebase configured (Auth email/password + Firestore).
Here is my vision.md: [paste the vision.md content]

Action: Create the base project structure:
1. src/lib/firebase.ts - Firebase config (read keys from .env.local)
2. src/contexts/AuthContext.tsx - Authentication provider with useAuth() hook
3. src/app/layout.tsx - Layout with AuthProvider and responsive navigation
4. src/app/page.tsx - Home page with redirect to /dashboard if logged in
5. src/components/Header.tsx - Navigation with username and logout button
6. src/types/index.ts - Task and User types

Format: Strict TypeScript, Tailwind CSS, "use client" for interactive components.
Conventions: Absolute imports @/*, no any, proper error handling.

3.4 Configure environment variables

Create .env.local with your Firebase keys:

NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_project.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id

3.5 Test locally

npm run dev    # Open http://localhost:3000

Verify that the app displays without errors in the terminal and in the browser.

3.6 First Vercel deployment

1. Commit and push all the code:

   git add .
   git commit -m "feat: initial scaffold with Next.js, Firebase config, and AuthProvider"
   git push

2. Go to vercel.com/new
3. Import your taskflow-aidd repo
4. Add the Firebase environment variables
5. Click Deploy

Feature 1: Task CRUD

First complete feature using the AIDD workflow.

4.1 DISCOVER — Read the GitHub issue

Open issue #1 (Create a task). Review the acceptance criteria.

4.2 PLAN — Identify the files to create

• src/lib/tasks.ts — Firestore CRUD functions (addTask, getTasks, updateTask, deleteTask)
• src/components/TaskForm.tsx — creation form
• src/components/TaskList.tsx — list display
• src/components/TaskCard.tsx — individual card
• src/app/dashboard/page.tsx — main page

4.3 EXECUTE — CRAFT Prompt

Context: Next.js 14 + TypeScript + Tailwind + Firebase project.
Working AuthContext in src/contexts/AuthContext.tsx.
Task type defined in src/types/index.ts:
{ id: string, title: string, description: string,
  priority: 'high' | 'medium' | 'low', dueDate: string,
  completed: boolean, userId: string, createdAt: Timestamp }

Requirement: Implement the complete task CRUD:
- Create a task with title, description, priority (select), due date
- Display the list of tasks for the logged-in user
- Mark a task as completed (toggle)
- Professional design with cards, colors by priority

Action: Create the following files:
1. src/lib/tasks.ts - Firestore functions (addTask, getTasks, toggleTask)
2. src/components/TaskForm.tsx - Form with validation
3. src/components/TaskCard.tsx - Task card with toggle and priority badge
4. src/components/TaskList.tsx - List with empty state
5. src/app/dashboard/page.tsx - Protected page (redirect if not logged in)

Format: Strict TypeScript, Tailwind CSS, "use client" for components.
Test: I can create a task, see it in the list, and check it as completed.

4.4 REVIEW — Verify the code

Before committing, verify:

• Imports are correct (no non-existent module)
• Types are strict (no any)
• Firestore rules filter by userId
• The form validates required fields
• UX is clean: loading state, empty state, visual feedback

4.5 COMMIT & TEST

# Test locally
npm run dev
# → Create a task, verify it appears, check it off

# Commit
git add src/lib/tasks.ts src/components/ src/app/dashboard/
git commit -m "feat: add task CRUD with Firestore - closes #1"
git push

Feature 2: Filters & search

Add interactivity with client-side filtering and sorting.

5.1 DISCOVER

Issue #2: "View task list with sorting and filters". The base CRUD already exists. We add:

• Filter by priority (all / high / medium / low)
• Filter by status (all / active / completed)
• Sort by due date or creation date
• Search bar by title

5.2 PLAN

This feature modifies one existing file and creates one:

• src/components/TaskFilters.tsx — new: filter bar
• src/app/dashboard/page.tsx — modify: integrate filters and state

5.3 EXECUTE

Context: My dashboard (src/app/dashboard/page.tsx) displays a list
of tasks from Firestore. The TaskList and TaskCard components exist.
Here is the current dashboard code: [paste the code]

Requirement: Add a filter system above the list:
- Toggle buttons for priority (All / High / Medium / Low)
- Toggle buttons for status (All / Active / Completed)
- Select for sorting (Due date ascending / descending, Priority)
- Search input by title (real-time filtering)
- Filters combine (AND logic)

Action:
1. Create src/components/TaskFilters.tsx with the controls
2. Modify src/app/dashboard/page.tsx to manage filter state
   and filter/sort tasks client-side

Format: TypeScript, Tailwind. The TaskFilters component emits changes
via callbacks. Filtering is done in the dashboard, not in the component.

Test: I can filter by "high priority" + "active" and only see
the matching tasks. Search filters in real-time.

5.4 REVIEW

Verify that:

• Filters combine correctly (not OR instead of AND)
• Search is case-insensitive
• Empty state is handled ("No tasks match the filters")
• Active buttons are visually distinct

5.5 COMMIT

git add src/components/TaskFilters.tsx src/app/dashboard/page.tsx
git commit -m "feat: add task filters by priority, status, and search - closes #2"
git push

Feature 3: Complete authentication

Login and registration pages with route protection.

6.1 DISCOVER

Issue #4: "Sign in / sign up by email". The AuthContext already exists (step 3). We add:

• Login page (/login)
• Registration page (/register)
• Protection of the /dashboard route
• Firebase Auth error handling
• Automatic redirect based on login state

6.2 EXECUTE

Context: Next.js 14 + TypeScript + Tailwind + Firebase project.
Existing AuthContext in src/contexts/AuthContext.tsx that exposes:
{ user: User | null, loading: boolean }
Firebase config in src/lib/firebase.ts.

Requirement: Create the complete auth pages:
- /login: email + password form, link to /register
- /register: email + password + confirmation form, link to /login
- Firebase error handling: auth/wrong-password, auth/user-not-found,
  auth/email-already-in-use, auth/weak-password
- User-friendly error messages
- Redirect to /dashboard after successful login
- Redirect to /login if not logged in on /dashboard

Action: Create:
1. src/app/login/page.tsx
2. src/app/register/page.tsx
3. Modify src/app/dashboard/page.tsx to protect the route
4. Add signIn, signUp, signOut to AuthContext

Format: TypeScript, Tailwind, "use client". Centered design with card,
loading states on buttons, error messages in red below fields.

Test: I can sign up, log out, log back in. If I go to /dashboard
without being logged in, I am redirected to /login.
Error messages display correctly.

6.3 REVIEW — Security checklist

• No Firebase secrets in the code (all in .env.local)
• Client-side field validation (email format, password length)
• No information leakage ("this email does not exist" is a risk)
• The loading state prevents double-submit
• Route protection uses the AuthContext (not just a client-side check)

6.4 COMMIT & TEST

# Test the complete flow
# 1. Open /register → create an account
# 2. Verify the redirect to /dashboard
# 3. Click "Log out" in the header
# 4. Verify the redirect to /login
# 5. Log back in with the created account
# 6. Open /dashboard in an incognito tab → should redirect to /login

git add src/app/login/ src/app/register/ src/contexts/ src/app/dashboard/
git commit -m "feat: add auth pages with login, register, and route protection - closes #4"
git push

Polish & final deployment

7.1 Quick polish

Ask the AI to refine:

Review the design of my TaskFlow app and improve:
1. Responsive: the dashboard should display correctly on mobile
2. Loading states: add skeletons/spinners during loading
3. Empty state: message and illustration when there are no tasks
4. Correct favicon and page title
5. CSS transitions on cards (hover, completion toggle)

Do NOT change the business logic, only the CSS/UI.

7.2 Final verification

Test your app deployed on Vercel (not locally!):

• Register a new user
• Create 3-4 tasks with different priorities
• Filter by priority + status
• Search by title
• Complete a task
• Log out and log back in
• Test on mobile (or DevTools responsive mode)

7.3 Final deploy

git add .
git commit -m "style: polish UI with responsive design, loading states, and empty states"
git push
# Vercel deploys automatically

7.4 Session summary

In 2h30, you built:

• A full-stack Next.js + TypeScript app
• With Firebase authentication
• Complete CRUD with Firestore
• Client-side filters and search
• Deployed on Vercel
• Following the AIDD workflow at each step