Assembler Agent Pattern

File Paths & Versioning

Input:

• project-docs/work-orders/work-orders-latest.md

  — Work orders from Planner

• project-docs/blueprint/blueprint-latest.md

  — Technical reference

Output:

• src/

  — Implementation code (git-versioned, not file-versioned)
• Implementation reports are included in work order comments or commit messages

Workflow:

1. Read

   project-docs/work-orders/work-orders-latest.md

2. For each work order, implement in

   src/

3. Commit with reference to work order ID (e.g.,

   WO-001: Implement auth service

   )
4. Mark work order as complete in the document

Note: Unlike other agents, Assembler outputs code which is versioned via git, not via numbered markdown files.

Purpose

The Assembler Agent is the fourth stage in the software factory workflow. It takes work orders from the Planner and executes them - either by writing code directly, coordinating with coding agents (like Letta Code, Cursor, Copilot), or delegating to human developers. It's where the actual implementation happens.

When to Use This Pattern

Use the Assembler Agent pattern when:

• You have detailed work orders ready to execute
• You need to coordinate code generation across multiple files
• You're managing implementation by AI agents or human developers
• You need to track implementation progress and quality

Core Responsibilities

1. Work Order Execution

Implement the specified work:

• Read and understand the work order
• Gather necessary context (existing code, dependencies)
• Generate or write the implementation
• Ensure acceptance criteria are met

2. Code Quality Management

Maintain code standards:

• Follow coding conventions and style guides
• Write clean, maintainable code
• Add appropriate comments and documentation
• Ensure consistent patterns across codebase

3. Tool Coordination

Integrate with development ecosystem:

• Use coding assistants (Letta Code, Cursor, etc.)
• Run linters and formatters
• Execute tests
• Manage version control

4. Progress Tracking

Monitor implementation status:

• Track which work orders are complete
• Identify blockers or issues
• Report progress to stakeholders
• Update work order status

5. Integration & Testing

Ensure code works:

• Write unit tests
• Run integration tests
• Verify acceptance criteria
• Fix issues found during testing

Implementation Approach

Step 1: Understand the Work Order

Work Order → Context Gathering → Implementation Plan

Read the work order carefully:

• What is the goal?
• What are the acceptance criteria?
• Which files need to be created or modified?
• What are the dependencies?
• What technologies are involved?

Gather context:

• Read existing related code
• Understand current architecture patterns
• Review coding conventions
• Check for similar implementations

Step 2: Plan the Implementation

Work Order + Context → Implementation Strategy → Code Outline

Break down the implementation:

For a backend API endpoint:

1. Define the route and handler
2. Implement request validation
3. Write business logic
4. Handle errors
5. Write tests
6. Document the API

For a frontend component:

1. Create component file
2. Define props and state
3. Implement render logic
4. Add styling
5. Write tests
6. Update parent components

Create an implementation checklist:

Work Order: WO-005 "Implement Task Creation API"

Implementation Steps:
- [ ] Create route handler in src/api/tasks.ts
- [ ] Add validation schema for request body
- [ ] Implement createTask service function
- [ ] Add error handling
- [ ] Write unit tests for validation
- [ ] Write unit tests for service function
- [ ] Write integration test for endpoint
- [ ] Update API documentation

Step 3: Execute the Implementation

Implementation Plan → Code Generation → Working Code

Execution modes:

Mode 1: Direct Implementation (AI agent writes code)

- Agent reads work order
- Agent generates complete implementation
- Agent writes files
- Agent runs tests
- Agent verifies acceptance criteria

Mode 2: Assisted Implementation (Human + AI pair programming)

- Human outlines approach
- AI generates code blocks
- Human reviews and refines
- AI runs tests and fixes issues
- Human does final review

Mode 3: Delegated Implementation (Human developer)

- Assign work order to developer
- Developer implements
- Developer submits for review
- AI or human reviews
- Developer addresses feedback

Best practices during execution:

• Work in small increments
• Test frequently
• Commit working code regularly
• Keep work order acceptance criteria in mind
• Ask for clarification if requirements are ambiguous

Step 4: Implement with Quality

Code Generation → Quality Checks → Production-Ready Code

Code quality checklist:

Correctness:

• Implements all acceptance criteria
• Handles edge cases
• Error handling is comprehensive
• No obvious bugs

Maintainability:

• Code is readable and well-organized
• Functions are small and focused
• Comments explain "why" not "what"
• Follows project conventions

Testability:

• Unit tests cover main logic
• Integration tests verify behavior
• Tests are clear and comprehensive
• Tests run quickly

Performance:

• No obvious performance issues
• Database queries are optimized
• Appropriate caching where needed
• No N+1 query problems

Security:

• Input validation is thorough
• No SQL injection vulnerabilities
• Authentication/authorization enforced
• Sensitive data is protected

Step 5: Test the Implementation

Working Code → Testing → Verified Code

Testing strategy:

Unit Tests:

// Test individual functions
describe('createTask', () => {
  it('should create a task with valid input', async () => {
    const input = { title: 'Test Task', description: 'Test' };
    const task = await createTask(input);
    expect(task).toHaveProperty('id');
    expect(task.title).toBe('Test Task');
  });

  it('should throw error with invalid input', async () => {
    const input = { title: '' }; // Invalid
    await expect(createTask(input)).rejects.toThrow();
  });
});

Integration Tests:

// Test API endpoints
describe('POST /api/tasks', () => {
  it('should create task and return 201', async () => {
    const response = await request(app)
      .post('/api/tasks')
      .send({ title: 'Test Task', description: 'Test' })
      .set('Authorization', `Bearer ${token}`);
    
    expect(response.status).toBe(201);
    expect(response.body).toHaveProperty('id');
  });
});

Manual Testing:

• Test happy path
• Test edge cases
• Test error scenarios
• Test with realistic data

Step 6: Document the Implementation

Verified Code → Documentation → Complete Work Package

Documentation types:

Code Comments:

/**
 * Creates a new task in the system
 * @param input - Task creation data
 * @returns Created task with generated ID
 * @throws ValidationError if input is invalid
 * @throws AuthorizationError if user lacks permission
 */
async function createTask(input: CreateTaskInput): Promise<Task> {
  // Implementation
}

API Documentation:

## POST /api/tasks

Create a new task.

**Authentication**: Required

**Request Body**:
{
  "title": "string (required, 1-200 chars)",
  "description": "string (optional)",
  "assigneeId": "string (optional, valid user ID)",
  "priority": "low | medium | high (optional, default: medium)"
}

**Response 201**:
{
  "id": "uuid",
  "title": "string",
  ...
}

**Errors**:
- 400: Invalid input
- 401: Not authenticated
- 403: Not authorized

Implementation Notes:

## Work Order WO-005: Task Creation API

**Implemented**: 2025-12-17
**Developer**: Assembler Agent

**Key Decisions**:
- Used UUID for task IDs (more scalable than auto-increment)
- Default priority is 'medium' if not specified
- Task owner defaults to creator if assigneeId not provided

**Known Limitations**:
- No support for bulk task creation yet (future work order)
- Task attachments not implemented in this work order

**Testing**:
- Unit tests: 12 cases, 100% coverage
- Integration tests: 6 endpoints scenarios
- Manual testing: Completed via Postman

Step 7: Review & Iterate

Complete Implementation → Review → Refinement

Review checklist:

Self-Review:

• Read through all changed code
• Run all tests
• Check acceptance criteria
• Review code quality
• Test manually

Peer Review (if applicable):

• Create pull request
• Address review comments
• Update based on feedback
• Re-test after changes

Quality Gate:

• All tests passing
• Linter passing
• No critical code smells
• Documentation complete
• Acceptance criteria met

Output Format

Implementation Report

# Implementation Report: WO-005

## Work Order
**Title**: Implement Task Creation API
**Priority**: P1
**Estimated Hours**: 4
**Actual Hours**: 5

## Status
✅ **Completed** - 2025-12-17 15:30 UTC

## Implementation Summary
Implemented the POST /api/tasks endpoint with full validation, error handling, and testing. The endpoint allows authenticated users to create tasks with optional assignment to team members.

## Files Created
- `src/api/tasks.ts` - Route handler and validation
- `src/services/taskService.ts` - Business logic
- `src/models/Task.ts` - Task type definitions
- `tests/unit/taskService.test.ts` - Unit tests
- `tests/integration/taskApi.test.ts` - Integration tests

## Files Modified
- `src/api/index.ts` - Added tasks route
- `src/db/schema.sql` - Already existed (no changes needed)
- `docs/api.md` - Added endpoint documentation

## Acceptance Criteria

✅ POST /api/tasks endpoint creates new task
✅ Endpoint validates input (title required, valid types)
✅ Returns 201 with created task
✅ Returns 400 for invalid input
✅ Unit tests cover all service functions (100% coverage)
✅ Integration tests verify API behavior (6 test cases)
✅ API documentation updated

## Testing Results
- **Unit Tests**: 12/12 passing
- **Integration Tests**: 6/6 passing
- **Coverage**: 100% (business logic)
- **Manual Testing**: Verified via Postman

## Key Implementation Details

### Validation Schema
Used Zod for request validation:
```typescript
const createTaskSchema = z.object({
  title: z.string().min(1).max(200),
  description: z.string().optional(),
  assigneeId: z.string().uuid().optional(),
  priority: z.enum(['low', 'medium', 'high']).default('medium')
});

Error Handling

Implemented consistent error responses:

• ValidationError → 400
• AuthenticationError → 401
• AuthorizationError → 403
• NotFoundError → 404
• InternalError → 500

Security

• JWT authentication required
• User can only create tasks in their team
• Input sanitization prevents injection

Issues Encountered & Resolutions

Issue 1: TypeScript type mismatch with Zod schema

• Resolution: Updated Task interface to match schema output

Issue 2: Integration test failing due to timezone handling

• Resolution: Use UTC timestamps consistently

Performance Considerations

• Database query time: <10ms average
• Endpoint response time: <50ms (p95)
• No N+1 queries

Future Improvements

• Add bulk task creation endpoint
• Add task attachment support
• Add task templates

Code Review

Self-Review: Completed Peer Review: N/A (solo implementation) Approved By: Assembler Agent Approved Date: 2025-12-17

Deployment

Status: Ready for staging Migration Required: No Config Changes: No Rollback Plan: Simple rollback, no DB changes

## Best Practices

### DO:
- **Follow existing patterns**: Match the codebase style
- **Test as you go**: Don't wait until the end
- **Commit frequently**: Small, atomic commits
- **Document decisions**: Explain non-obvious choices
- **Ask for clarification**: Don't guess requirements
- **Refactor as needed**: Leave code better than you found it

### DON'T:
- **Skip tests**: Every work order needs tests
- **Hardcode values**: Use configuration
- **Ignore errors**: Handle them properly
- **Over-engineer**: Solve the current problem, not future ones
- **Break existing code**: Run existing tests
- **Mix concerns**: One work order = one focused change

## Integration with Other Agents

### Input ← Planner Agent
Receives work orders containing:
- Task description
- Acceptance criteria
- Technical details
- File paths
- Testing requirements

### Output → Validator Agent
Provides implemented code for validation:
- All created/modified files
- Test results
- Implementation notes
- Known issues

### Feedback Loop → Planner Agent
May provide feedback on:
- Work orders that were under-specified
- Missing dependencies discovered
- Estimation accuracy improvements

## Example Usage

### Input Work Order

WO-005: Implement Task Creation API Priority: P1 Estimated: 4 hours Dependencies: WO-002 (Task Model)

Acceptance Criteria:

• POST /api/tasks endpoint creates task
• Input validation required
• Returns 201 with created task
• Unit tests with >80% coverage

### Assembler Execution
1. **Read work order**: Understand requirements
2. **Gather context**: Review existing API patterns
3. **Plan implementation**: 
   - Create route handler
   - Add validation
   - Write service function
   - Write tests
4. **Execute**: Generate code files
5. **Test**: Run unit + integration tests
6. **Document**: Update API docs
7. **Report**: Create implementation report

### Output Implementation

Files Created:

• src/api/tasks.ts (route handler)
• src/services/taskService.ts (business logic)
• tests/unit/taskService.test.ts (12 tests)
• tests/integration/taskApi.test.ts (6 tests)

Files Modified:

• src/api/index.ts (added route)
• docs/api.md (added documentation)

Status: ✅ Complete Tests: 18/18 passing Coverage: 100%

## Tips for Effective Assembly

1. **Read the whole work order first**: Don't start coding immediately
2. **Understand the context**: Review related code before implementing
3. **Start with tests**: TDD can clarify requirements
4. **Keep it simple**: Solve the problem at hand, no more
5. **Verify continuously**: Test after each small change
6. **Document as you go**: Don't save documentation for the end

## Common Pitfalls

- **Scope creep**: Implementing more than the work order specifies
- **Pattern inconsistency**: Not following existing codebase conventions
- **Insufficient testing**: Skipping edge cases or error scenarios
- **Poor error messages**: Generic errors that don't help debugging
- **Tight coupling**: Making components too dependent on each other
- **Premature optimization**: Optimizing before there's a problem

## Working with AI Coding Agents

### Effective Prompting

Good Prompt: "Implement the createTask function according to WO-005. It should validate input using Zod, save to database using the existing taskRepository pattern, and return the created task. Handle validation errors with 400 response."

Bad Prompt: "Make a task creation function"

### Reviewing AI-Generated Code
- **Always review**: Don't trust AI output blindly
- **Test thoroughly**: AI can miss edge cases
- **Check patterns**: Ensure consistency with codebase
- **Verify security**: AI might miss security concerns
- **Refactor if needed**: AI code isn't always optimal

### Iterating with AI

1. Generate initial implementation
2. Run tests → some fail
3. Provide feedback: "Test X fails because Y"
4. AI fixes the issue
5. Run tests again → all pass
6. Final review and refinement

## Summary

The Assembler Agent is where the plan becomes reality. It bridges the gap between specification and working software, ensuring that code is not just functional but also maintainable, tested, and well-documented.

**Remember**: Good implementation is:
- **Correct**: Meets all acceptance criteria
- **Tested**: Comprehensive test coverage
- **Maintainable**: Clean, readable code
- **Documented**: Clear comments and docs
- **Consistent**: Follows codebase patterns
- **Reviewed**: Quality-checked before completion