What You'll Learn

You'll take a single user story from sprint backlog to accepted — using test-driven development, continuous integration, structured commits, pull requests, and formal acceptance.

The Scenario

Sprint 1 is planned. You're starting with US-001: Add a new task. The acceptance criteria are clear: users can create tasks with a title and optional description, validation rejects empty titles, and each task gets a unique ID. You'll build this feature using the full TDD workflow.

Step 1: Create the Feature Branch with /agile-code-branch

Before anything else, create a properly named feature branch linked to the story:

/agile-code-branch

🌿 Branch created: feature/US-001-add-task

Source: main
Convention: feature/[STORY-ID]-[short-description]
Story link: US-001 — Add a new task

Switched to branch 'feature/US-001-add-task'

Step 2: Plan the Story with /agile-story-plan

Before writing any code, break the story into implementation phases:

/agile-story-plan

📋 Implementation Plan: US-001 — Add a new task
═══════════════════════════════════════════════

Phase 1: Data Model + Repository
  • Create Task model (id, title, description, status, createdAt)
  • Create TaskRepository with insert() and findById()
  • Migration: create tasks table
  Files: src/models/task.js, src/repositories/task-repository.js, migrations/

Phase 2: Service Layer
  • Create TaskService with createTask()
  • Input validation (title required, max 200 chars)
  • Business logic: set status="pending", generate timestamp
  Files: src/services/task-service.js, src/validators/task-validator.js

Phase 3: API Endpoint
  • POST /api/v1/tasks endpoint
  • Request/response serialization
  • Error handling integration
  Files: src/controllers/task-controller.js, src/routes/task-routes.js

Estimated phases: 3
Confidence: 9/10
Risk: Low — standard CRUD, well-known patterns

✅ Plan approved. Ready to implement.

Step 3: Test-Driven Development with /agile-code-tdd

This is the heart of the implementation. Run TDD for each phase:

/agile-code-tdd

The AI follows the Red-Green-Refactor cycle:

🔴 RED — Writing failing test...

// test/services/task-service.test.js
describe('TaskService', () => {
  describe('createTask', () => {
    it('should_create_task_when_valid_input', async () => {
      const input = { title: 'Buy groceries', description: 'Milk, eggs, bread' };
      const task = await taskService.createTask(input);

      expect(task.id).toBeDefined();
      expect(task.title).toBe('Buy groceries');
      expect(task.description).toBe('Milk, eggs, bread');
      expect(task.status).toBe('pending');
      expect(task.createdAt).toBeInstanceOf(Date);
    });

    it('should_reject_when_title_missing', async () => {
      await expect(taskService.createTask({ description: 'no title' }))
        .rejects.toThrow('Title is required');
    });

    it('should_reject_when_title_empty_string', async () => {
      await expect(taskService.createTask({ title: '' }))
        .rejects.toThrow('Title is required');
    });
  });
});

Running tests...
  ✗ should_create_task_when_valid_input — FAILED (TaskService not found)
  ✗ should_reject_when_title_missing — FAILED (TaskService not found)
  ✗ should_reject_when_title_empty_string — FAILED (TaskService not found)

3 failing ← This is expected. Tests define what we want to build.

🟢 GREEN — Implementing to make tests pass...

// src/models/task.js
class Task {
  constructor({ id, title, description, status, createdAt }) {
    this.id = id;
    this.title = title;
    this.description = description || null;
    this.status = status || 'pending';
    this.createdAt = createdAt || new Date();
  }
}

// src/validators/task-validator.js
function validateTaskInput(data) {
  if (!data.title || data.title.trim() === '') {
    throw new AppError('Title is required', 400);
  }
  if (data.title.length > 200) {
    throw new AppError('Title must be 200 characters or less', 400);
  }
}

// src/services/task-service.js
class TaskService {
  constructor(taskRepository) {
    this.taskRepository = taskRepository;
  }

  async createTask(data) {
    validateTaskInput(data);
    const task = new Task({ title: data.title, description: data.description });
    return this.taskRepository.insert(task);
  }
}

Running tests...
  ✓ should_create_task_when_valid_input — PASSED
  ✓ should_reject_when_title_missing — PASSED
  ✓ should_reject_when_title_empty_string — PASSED

3 passing ← All green!

🔵 REFACTOR — Improving structure without changing behavior...

Refactoring: Extracted validation logic to TaskValidator class
  • Moved from inline function to class with static methods
  • Added validate() entry point for extensibility
  • No test changes needed — all 3 still pass ✓

Running tests after refactor...
  ✓ should_create_task_when_valid_input — PASSED
  ✓ should_reject_when_title_missing — PASSED
  ✓ should_reject_when_title_empty_string — PASSED

✅ TDD cycle complete for Phase 1+2. 3 tests passing.

Step 4: Run CI Checks with /agile-code-ci

Before committing, verify everything passes:

/agile-code-ci

🔄 Running CI pipeline locally...

Build:
  ✅ Compilation successful (0 errors, 0 warnings)

Tests:
  ✅ 12 tests passing (3 unit + 5 integration + 4 edge cases)
  ✅ Coverage: 94% lines, 100% branches (threshold: 80%)

Lint:
  ✅ ESLint: 0 errors, 0 warnings
  ✅ Prettier: all files formatted

Security:
  ✅ npm audit: 0 vulnerabilities
  ✅ No hardcoded secrets detected

✅ All CI checks pass. Safe to commit.

Step 5: Commit with /agile-code-commit

Create a conventional commit with a clear message:

/agile-code-commit

📦 Commit created:

feat(tasks): add task creation with validation

- Task model with id, title, description, status, createdAt
- TaskService.createTask() with input validation
- TaskRepository.insert() with PostgreSQL integration
- POST /api/v1/tasks endpoint
- 12 tests covering happy path and edge cases

Refs: US-001

Step 6: Create a Pull Request with /agile-code-pr

Open a PR linked to the story:

/agile-code-pr

🔀 Pull Request created: #14

Title: feat(tasks): add task creation with validation
Branch: feature/US-001-add-task → main
Story: US-001

Description:
  Implements the "Add a new task" user story. Users can create tasks
  via POST /api/v1/tasks with title (required) and description (optional).
  Input validation rejects empty/missing titles.

Changes:
  +6 files, 247 additions
  src/models/task.js
  src/validators/task-validator.js
  src/services/task-service.js
  src/repositories/task-repository.js
  src/controllers/task-controller.js
  src/routes/task-routes.js

Test coverage: 94%
CI status: ✅ All checks passing

Reviewers: @lead (auto-assigned)

Step 7: Code Review with /agile-code-pr-review

The reviewer examines the PR and provides structured feedback:

/agile-code-pr-review

👀 Code Review — PR #14
═══════════════════════

Findings:
  🟡 S2 — task-service.js:15 — Parameter naming
     Rename `data` to `taskPayload` for clarity
     Suggestion: async createTask(taskPayload) { ... }

  🔵 S3 — task-controller.js:8 — Documentation
     Add JSDoc to the controller method describing
     request body shape and response format

  ✅ Architecture: Follows 3-layer pattern correctly
  ✅ Tests: Comprehensive, covers edge cases
  ✅ Security: No injection risks, input validated
  ✅ Conventions: Naming, imports, error handling all match project style

Verdict: CHANGES REQUESTED (2 minor items)

---

After fixes applied:

👀 Re-review — PR #14
  ✅ S2 fix verified — parameter renamed to taskPayload
  ✅ S3 fix verified — JSDoc added

Verdict: ✅ APPROVED by @lead

Step 8: Merge the Branch with /agile-code-merge

With the PR approved, merge the feature branch into main:

/agile-code-merge

🔀 Merge — PR #14
═══════════════════

Pre-merge checks:
  ✅ PR approved by @lead
  ✅ CI passing on branch
  ✅ No merge conflicts
  ✅ Branch up to date with main

Merging: feature/US-001-add-task → main
Strategy: squash merge (project convention)

Merge complete.
Branch feature/US-001-add-task deleted (was 3a7f2c1).

✅ PR #14 merged to main.

Step 9: Definition of Done with /agile-story-dod

Walk through every DoD criterion to confirm the story is truly done:

/agile-story-dod

📝 Definition of Done Checklist — US-001
════════════════════════════════════════

  ✅ All acceptance criteria met (3/3 scenarios pass)
  ✅ Code reviewed and approved by @lead
  ✅ All tests passing (12/12)
  ✅ Test coverage above threshold (94% > 80%)
  ✅ No lint errors or warnings
  ✅ No security vulnerabilities
  ✅ API documentation updated
  ✅ Conventional commit message
  ✅ PR linked to story US-001
  ✅ Branch merged to main

DoD result: ✅ ALL CRITERIA MET (10/10)

Step 10: Accept the Story with /agile-story-accept

The product owner verifies each acceptance criterion against the working software:

/agile-story-accept

🎯 Story Acceptance — US-001: Add a new task
═════════════════════════════════════════════

AC 1: Given valid title and description → task created with status "pending"
  Test: POST /api/v1/tasks {"title":"Buy groceries","description":"Milk, eggs"}
  Result: 201 Created, status="pending", ID assigned
  ✅ PASS

AC 2: Given missing title → 400 error returned
  Test: POST /api/v1/tasks {"description":"no title"}
  Result: 400 Bad Request, message="Title is required"
  ✅ PASS

AC 3: Given empty string title → 400 error returned
  Test: POST /api/v1/tasks {"title":""}
  Result: 400 Bad Request, message="Title is required"
  ✅ PASS

Verdict: ✅ ACCEPTED by @po
Story status: US-001 → DONE

The Feature Development Flow

Knowledge Check

What You Learned