docs/planning/agent-tasks/AGENT_KICKOFF_GUIDE.md

Agent Kickoff Guide

🚀 Starting Your Implementation

This guide helps agents quickly understand how to start working on WidgeTDC improvements.

📖 Quick Start (5 minutes)

1. Read Current State

# Check main branch status
git checkout main
git pull origin main

# Review current architecture
cat README.md
cat docs/planning/agent-tasks/README.md

2. Understand Project Structure

WidgeTDC/
├── apps/
│   ├── backend/          # Node.js/Express backend
│   │   ├── src/
│   │   │   ├── services/ # Business logic (Memory, SRAG, Evolution, PAL)
│   │   │   ├── mcp/      # MCP gateway and tools
│   │   │   └── database/ # SQLite (to be migrated to PostgreSQL)
│   │   └── package.json
│   └── matrix-frontend/     # React frontend
│       ├── components/   # UI components
│       ├── widgets/      # Individual widgets
│       └── package.json
├── packages/
│   └── shared/
│       └── mcp-types/    # Shared TypeScript types
└── docs/
    └── planning/
        └── agent-tasks/  # Implementation plans (YOU ARE HERE)

3. Choose Your Phase

If you're the first agent: → Start with Phase 1: Authentication OR Phase 9: CI/CD (can run in parallel)

If Phase 1 is done: → Start Phase 2: PostgreSQL Migration

If you want observability: → Phase 6: Observability (can run anytime)

4. Create Your Branch

# Pattern: agent/<your-role>/phase<N>-<task-name>
git checkout -b agent/backend-engineer/phase1-auth-service

# Example names:
# agent/backend-architect/phase1-auth-design
# agent/frontend-engineer/phase1-login-form
# agent/devops/phase2-postgres-setup

🎯 Agent Role Assignments

Backend Architect

Responsibilities: System design, architecture decisions, database schema Primary Phases: 1, 2, 4 Skills Required: System architecture, database design, microservices patterns

Start Here:

1. Phase 1, Task 1.1: Design Authentication Architecture
2. Phase 2, Task 2.1: Database Schema Analysis & Design

Backend Engineer

Responsibilities: API implementation, business logic, testing Primary Phases: 1, 2, 3, 4, 6, 7, 10 Skills Required: Node.js, TypeScript, Express, SQL, Testing

Start Here:

1. Phase 1, Task 1.2: Implement Database Schema
2. Phase 1, Task 1.3: Implement Authentication Service
3. Phase 2, Task 2.4: Update Repository Layer

Frontend Engineer

Responsibilities: UI components, state management, responsive design Primary Phases: 1, 5, 7, 8 Skills Required: React, TypeScript, CSS, Mobile development

Start Here:

1. Phase 1, Task 1.6: Frontend Login Implementation
2. Phase 5: Widget marketplace UI
3. Phase 8: Mobile app development

Data Engineer

Responsibilities: Database migrations, data pipelines, ETL Primary Phases: 2, 3 Skills Required: SQL, PostgreSQL, data migration, vector databases

Start Here:

1. Phase 2, Task 2.1: Database Schema Analysis & Design
2. Phase 2, Task 2.5: Data Migration Script
3. Phase 3: Vector embeddings setup

DevOps Engineer

Responsibilities: Infrastructure, CI/CD, containerization, monitoring Primary Phases: 4, 6, 9 Skills Required: Docker, Kubernetes, GitHub Actions, Prometheus, Grafana

Start Here:

1. Phase 9: CI/CD Automation (HIGH PRIORITY - enables all other work)
2. Phase 2, Task 2.2: Set Up PostgreSQL Infrastructure
3. Phase 6: Observability stack

Security Expert

Responsibilities: Security audits, compliance, vulnerability assessment Primary Phases: 1, 10 Skills Required: Security best practices, GDPR, penetration testing

Start Here:

1. Phase 1: Authentication security review
2. Phase 10: Data privacy and compliance implementation

QA Engineer

Responsibilities: Test strategy, test automation, quality assurance Primary Phases: All phases (cross-cutting) Skills Required: Jest, Playwright, E2E testing, performance testing

Start Here:

1. Phase 1: Write test suites for authentication
2. Phase 9: Set up automated testing in CI/CD
3. Review test coverage across all phases

📝 Implementation Workflow

Step 1: Read Phase Document

# Open your assigned phase
cat docs/planning/agent-tasks/PHASE_1_AUTHENTICATION.md

What to look for:

• Objective and prerequisites
• Task breakdown with estimates
• Deliverables (code, config, docs)
• Test cases
• Success criteria

Step 2: Verify Prerequisites

Example for Phase 1:

# Check Node.js version
node --version  # Should be >= 18

# Check if backend runs
cd apps/backend
npm install
npm run dev

# Check if frontend runs
cd ../matrix-frontend
npm install
npm run dev

Step 3: Implement Task by Task

# Create feature branch for each task
git checkout -b agent/backend-engineer/phase1-task1.2-db-schema

# Make changes
# ... implement task ...

# Run tests
npm test

# Commit with descriptive message
git add .
git commit -m "Phase 1, Task 1.2: Implement auth database schema

- Created users, roles, and user_roles tables
- Added foreign key constraints
- Seeded default roles (admin, standard, viewer)
- Tests: Schema creation and constraint validation

Test Results: ✅ All passing (8/8)
"

# Push and create PR
git push origin agent/backend-engineer/phase1-task1.2-db-schema

Step 4: Write Tests FIRST (TDD)

// BEFORE implementing feature, write the test

describe('AuthService.login', () => {
  it('should return token for valid credentials', async () => {
    // Arrange
    const username = 'testuser';
    const password = 'password123';

    // Act
    const result = await authService.login(username, password);

    // Assert
    expect(result.accessToken).toBeDefined();
    expect(result.refreshToken).toBeDefined();
  });
});

// NOW implement the feature to make test pass

Step 5: Document As You Go

/**
 * Authenticates a user with username and password.
 *
 * @param username - User's username
 * @param password - Plain text password (will be compared with hashed version)
 * @returns Access token, refresh token, and user object
 * @throws {Error} If credentials are invalid
 *
 * @example
 * ```typescript
 * const result = await authService.login('john', 'password123');
 * console.log(result.accessToken); // JWT token
 * ```
 */
async login(username: string, password: string): Promise<AuthResult> {
  // ... implementation
}

Step 6: Create Pull Request

PR Title Format: [Phase X] Task X.Y: <Brief Description>

PR Description Template:

## Phase 1, Task 1.3: Implement Authentication Service

### Deliverables
✅ AuthService class with login, register, refresh methods
✅ Password hashing with bcrypt
✅ JWT token generation and verification
✅ Unit tests with 95% coverage

### Test Results
- Unit Tests: 15/15 passing ✅
- Integration Tests: 5/5 passing ✅
- Code Coverage: 95% ✅

### Breaking Changes
None

### Dependencies
Requires Task 1.2 (database schema) to be merged first

### Screenshots
N/A (backend service)

### Checklist
- [x] Code follows project style guide
- [x] Tests written and passing
- [x] Documentation updated
- [x] No console.log statements
- [x] Error handling implemented
- [x] Security best practices followed

### Review Notes
Please verify:
1. JWT secret handling (using env vars)
2. Password hashing cost factor (set to 10)
3. Token expiration times (15m access, 7d refresh)

🧪 Testing Standards

Unit Tests (Jest)

Location: *.test.ts next to implementation Coverage Target: ≥ 80% Run Command: npm test

Example:

// apps/backend/src/services/auth/authService.test.ts
import { AuthService } from './authService';

describe('AuthService', () => {
  let authService: AuthService;

  beforeEach(() => {
    authService = new AuthService();
  });

  it('should hash passwords securely', async () => {
    const password = 'mypassword';
    const hash = await authService.hashPassword(password);

    expect(hash).not.toBe(password);
    expect(hash.length).toBeGreaterThan(50);
  });
});

Integration Tests

Location: apps/backend/src/__tests__/integration/ Run Command: npm run test:integration

Example:

// apps/backend/src/__tests__/integration/auth.test.ts
import request from 'supertest';
import app from '../../index';

describe('Auth Integration', () => {
  it('should login and access protected endpoint', async () => {
    // 1. Login
    const loginRes = await request(app)
      .post('/api/auth/login')
      .send({ username: 'testuser', password: 'password123' });

    expect(loginRes.status).toBe(200);
    const { accessToken } = loginRes.body;

    // 2. Access protected endpoint
    const protectedRes = await request(app)
      .get('/api/memory/entities')
      .set('Authorization', `Bearer ${accessToken}`);

    expect(protectedRes.status).toBe(200);
  });
});

E2E Tests (Playwright)

Location: apps/matrix-frontend/tests/ Run Command: npm run test:e2e

Example:

// apps/matrix-frontend/tests/auth-flow.spec.ts
import { test, expect } from '@playwright/test';

test('complete auth flow', async ({ page }) => {
  // Navigate to app
  await page.goto('http://localhost:3000');

  // Fill login form
  await page.fill('input[name="username"]', 'testuser');
  await page.fill('input[name="password"]', 'password123');
  await page.click('button:has-text("Login")');

  // Verify redirect to dashboard
  await expect(page).toHaveURL(/.*dashboard/);
  await expect(page.locator('.user-menu')).toContainText('testuser');

  // Logout
  await page.click('.user-menu');
  await page.click('text=Logout');

  // Verify redirect to login
  await expect(page).toHaveURL(/.*login/);
});

🔍 Code Quality Standards

TypeScript

// ✅ GOOD: Explicit types, no 'any'
function login(username: string, password: string): Promise<AuthResult> {
  // ...
}

// ❌ BAD: Implicit any, no return type
function login(username, password) {
  // ...
}

Error Handling

// ✅ GOOD: Specific error types, proper error messages
class InvalidCredentialsError extends Error {
  constructor(message: string) {
    super(message);
    this.name = 'InvalidCredentialsError';
  }
}

async function login(username: string, password: string) {
  const user = await findUser(username);
  if (!user) {
    throw new InvalidCredentialsError('User not found');
  }
  // ...
}

// ❌ BAD: Generic errors, no context
async function login(username: string, password: string) {
  const user = await findUser(username);
  if (!user) {
    throw new Error('Error');
  }
}

Async/Await

// ✅ GOOD: Async/await with try-catch
async function login(username: string, password: string) {
  try {
    const user = await findUser(username);
    return user;
  } catch (error) {
    logger.error('Login failed', { username, error });
    throw error;
  }
}

// ❌ BAD: Promise chains, no error handling
function login(username, password) {
  return findUser(username)
    .then(user => user);
}

📞 Communication & Coordination

Daily Updates

Format: Git commit messages Frequency: At least one commit per task

Blockers

Report Via: GitHub issues with [BLOCKER] tag Include:

1. Phase and task number
2. Description of blocker
3. What you've tried
4. What help you need

Example:

Title: [BLOCKER] Phase 1, Task 1.3: Missing JWT_SECRET environment variable

Description:
Cannot test authentication service because JWT_SECRET is not defined.

Attempted Solutions:
- Checked .env.example
- Searched codebase for .env template

Needed:
- .env.example with JWT_SECRET
- OR documentation on how to generate secrets
- OR default value for development

Blocking:
- Task 1.3: Authentication Service
- Task 1.4: Authorization Middleware

Handoffs

When completing a phase, create handoff document:

# Phase 1 Handoff Document

## Completed
✅ All 6 tasks complete
✅ 100% test coverage
✅ Documentation updated
✅ Security audit passed

## What's Ready
- Authentication API (/api/auth/*)
- Authorization middleware
- Login form component
- User/role database

## Known Issues
None

## Next Phase Dependencies Met
✅ Phase 2 can start (auth not blocking)
✅ Phase 10 can start (auth foundation ready)

## Environment Variables Added
- JWT_SECRET (required)
- JWT_REFRESH_SECRET (required)
- JWT_EXPIRY (optional, default: 15m)

## Migration Required
Yes - run: npm run migrate:auth

## Notes for Next Agent
- User table has username and email (both unique)
- Default roles seeded on first migration
- Admin user must be created manually (see docs)

🎓 Learning Resources

Codebase Patterns

Read these before starting:

• apps/backend/src/services/memory/memoryRepository.ts - Repository pattern
• apps/backend/src/mcp/toolHandlers.ts - MCP integration pattern
• apps/matrix-frontend/widgets/AiPalWidget.tsx - Widget structure

External Docs

• Express.js Best Practices
• TypeScript Handbook
• React Testing Library
• Playwright Testing

🚨 Common Pitfalls

1. Not Running Tests Before Committing

# ❌ DON'T
git add .
git commit -m "Fix"
git push

# ✅ DO
npm test
npm run lint
npm run build
git add .
git commit -m "Phase 1, Task 1.3: Implement AuthService - Tests passing"
git push

2. Working Directly on Main

# ❌ DON'T
git checkout main
# ... make changes ...
git push

# ✅ DO
git checkout -b agent/backend-engineer/phase1-task3
# ... make changes ...
git push origin agent/backend-engineer/phase1-task3
# ... create PR ...

3. Skipping Documentation

// ❌ DON'T
async function login(u, p) {
  // code
}

// ✅ DO
/**
 * Authenticates user with username and password.
 * @param username - User's unique username
 * @param password - Plain text password
 * @returns Authentication tokens and user object
 */
async function login(username: string, password: string): Promise<AuthResult> {
  // code
}

✅ Final Checklist

Before starting:

• Read phase document completely
• Verified prerequisites
• Created feature branch
• Understand test requirements
• Know where to report blockers

Before committing:

• All tests passing
• Lint passing
• Documentation updated
• No console.log or debug code
• Error handling implemented

Before merging:

• PR created with proper description
• Another agent reviewed
• All CI checks passing
• Conflicts resolved
• Handoff document created (if final task)

---

Ready to start? Pick your phase and create your branch! 🚀

Questions? Create a GitHub issue with your question.

Stuck? Review the phase document test cases - they show expected behavior.