Coder Phase

What is the Coder Phase?

The Coder phase is where the Coder Agent transforms approved specifications into working code without making architectural decisions or modifying requirements. This phase demonstrates how VibeSpec maintains strict separation between design and implementation, ensuring that code faithfully implements specifications while avoiding scope creep and architectural drift.

In the Todo Application project, the Coder Agent reads the approved architecture specification and implements each component exactly as designed. The agent translates specification requirements into code but never changes the architecture, adds features, or makes design decisions that weren't explicitly specified by the Architect Agent.

The Coder Agent operates within strict boundaries: it implements what is specified, asks for clarification when specifications are ambiguous, and documents implementation patterns in memory for future reuse. However, it never redesigns systems, modifies requirements, or introduces features beyond the approved specifications.

Understanding this phase is crucial because it demonstrates how disciplined implementation prevents the common problem of "implementation drift" where code gradually deviates from intended design, creating maintenance problems and technical debt.

Why This Matters

Problems It Solves

Implementation Drift from Specifications: Traditional development often sees code gradually deviate from original specifications as developers make "convenient" changes during implementation. The Coder Agent maintains strict specification compliance, preventing architectural drift.

Unauthorized Feature Addition: Developers frequently add features or modify requirements during implementation without proper approval. The Coder Agent implements only what is specified, preventing scope creep and maintaining project boundaries.

Inconsistent Implementation Patterns: Different developers implement similar functionality in different ways, creating maintenance complexity. The Coder Agent applies consistent patterns based on specifications and accumulated memory.

Ambiguity Handling Inconsistency: When specifications are unclear, different developers make different assumptions, leading to inconsistent implementations. The Coder Agent systematically identifies and requests clarification for ambiguous requirements.

Benefits You'll Gain

Specification Fidelity: Code matches approved specifications exactly, ensuring that implemented systems behave as designed and meet stakeholder expectations without surprises.

Controlled Implementation Scope: Only approved features are implemented, preventing scope creep and maintaining project timelines and budgets.

Consistent Code Patterns: All implementations follow the same patterns and conventions, creating maintainable and predictable codebases regardless of complexity.

Systematic Ambiguity Resolution: Unclear specifications are identified and clarified systematically, preventing implementation assumptions that lead to defects and rework.

Real-World Impact

Development teams using strict specification-to-code discipline report 80% fewer post-deployment surprises and 60% less rework compared to teams that allow implementation-time design changes. The disciplined approach prevents technical debt accumulation and maintains system integrity over time.

How to Execute the Coder Phase

How the Coder Agent Reads Specifications

Specification Parsing Process: The Coder Agent systematically reads approved specifications to understand implementation requirements without making design decisions:

1. Architecture Specification Analysis: Extracts technology stack, component structure, data models, and integration requirements
2. Interface Definition Extraction: Identifies API endpoints, data formats, and communication protocols
3. Security Requirement Identification: Locates authentication, authorization, and data protection requirements
4. Performance Constraint Recognition: Finds response time, scalability, and resource usage requirements

Implementation Boundary Recognition: The Coder Agent distinguishes between what is specified (must implement) and what is not specified (cannot implement without approval):

• Specified: Database schema, API endpoints, authentication methods, technology choices
• Not Specified: Code organization details, variable names, internal algorithms, optimization techniques

Spec → Code Responsibility Mapping

Clear Implementation Responsibilities:

Architecture Spec Says → Coder Agent Implements
─────────────────────────────────────────────────
"PostgreSQL database" → Creates database connection and configuration
"JWT authentication" → Implements JWT token generation and validation
"React frontend" → Sets up React application with specified features
"REST API endpoints" → Creates Express routes with specified functionality
"Input validation" → Implements validation middleware with specified rules
"bcrypt password hashing" → Uses bcrypt for password security implementation

Boundaries the Coder Agent Cannot Cross:

What Coder Agent CANNOT Decide → Must Ask Architect Agent
─────────────────────────────────────────────────────────
Technology stack changes → "Should we use MongoDB instead?"
New feature additions → "Should we add user profiles?"
Architecture modifications → "Should we use microservices?"
Security policy changes → "Should we use OAuth instead?"
Performance trade-offs → "Should we prioritize speed over memory?"
Integration approaches → "Should we use GraphQL instead?"

Handling Ambiguity in Specifications

Systematic Ambiguity Detection: The Coder Agent identifies unclear specifications and requests clarification rather than making assumptions:

Example Ambiguous Specification:

"Implement user authentication with secure password storage"

Coder Agent Response:

AMBIGUITY DETECTED: Authentication specification lacks implementation details

Clarification needed:
- Password complexity requirements (length, character types)?
- Session duration and refresh token strategy?
- Rate limiting parameters for login attempts?
- Password reset mechanism requirements?
- Multi-factor authentication requirements?

Cannot proceed with implementation until specifications are clarified.

Example Clear Specification:

"Implement JWT authentication with:
- bcrypt password hashing (12 salt rounds)
- 24-hour token expiration with refresh mechanism
- Rate limiting: 5 login attempts per 15 minutes per IP
- Password requirements: 8+ characters, mixed case, numbers, special characters"

Coder Agent Response:

SPECIFICATION CLEAR: Proceeding with JWT authentication implementation
- Using bcrypt with 12 salt rounds for password hashing
- JWT tokens expire in 24 hours with refresh token support
- Express-rate-limit middleware: 5 attempts/15 minutes/IP
- Joi validation schema for password complexity requirements

Avoiding Partial Implementations

Complete Feature Implementation Strategy: The Coder Agent implements features completely based on specifications, avoiding partial implementations that create technical debt:

Correct Approach - Complete Implementation:

// Specification: "Implement todo CRUD operations with user authorization"

// ✅ COMPLETE: All CRUD operations implemented
router.get('/todos', authenticateToken, getTodos);      // Read
router.post('/todos', authenticateToken, createTodo);   // Create  
router.put('/todos/:id', authenticateToken, updateTodo); // Update
router.delete('/todos/:id', authenticateToken, deleteTodo); // Delete

// ✅ COMPLETE: User authorization on all endpoints
// ✅ COMPLETE: Input validation on all operations
// ✅ COMPLETE: Error handling for all scenarios

Incorrect Approach - Partial Implementation:

// ❌ PARTIAL: Only some CRUD operations implemented
router.get('/todos', getTodos);      // Missing authentication
router.post('/todos', createTodo);   // Missing validation

// ❌ PARTIAL: Inconsistent security implementation
// ❌ PARTIAL: Missing error handling
// ❌ PARTIAL: Incomplete feature set

Implementation Completeness Checklist:

• ✅ All specified endpoints implemented
• ✅ All security requirements applied consistently
• ✅ All validation rules implemented
• ✅ All error scenarios handled
• ✅ All performance requirements met
• ✅ All integration points functional

What to Expect

Examples of Correct vs Incorrect Coder Behavior

Correct Coder Agent Behavior

Scenario: Implementing user authentication based on architecture specification

Architecture Specification States:

"JWT authentication with bcrypt password hashing, 24-hour token expiration, 
rate limiting of 5 attempts per 15 minutes per IP address"

✅ Correct Coder Agent Implementation:

// Implements exactly what is specified
import bcrypt from 'bcryptjs';
import jwt from 'jsonwebtoken';
import rateLimit from 'express-rate-limit';

// Rate limiting as specified: 5 attempts per 15 minutes
const authLimiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 5, // 5 attempts per window
  message: { error: 'Too many authentication attempts' }
});

// JWT token generation with 24-hour expiration as specified
const generateToken = (userId: number) => {
  return jwt.sign(
    { userId },
    process.env.JWT_SECRET!,
    { expiresIn: '24h' } // Exactly as specified
  );
};

// bcrypt password hashing as specified
const hashPassword = async (password: string) => {
  return await bcrypt.hash(password, 12); // Standard salt rounds
};

✅ Correct Behavior Characteristics:

• Implements exactly what specification requires
• Uses specified technologies (JWT, bcrypt, rate limiting)
• Follows specified parameters (24-hour expiration, 5 attempts/15 minutes)
• Does not add features beyond specification
• Does not modify security parameters without approval

Incorrect Coder Agent Behavior

❌ Incorrect Implementation - Adding Unspecified Features:

// WRONG: Adding features not in specification
const authLimiter = rateLimit({
  windowMs: 15 * 60 * 1000,
  max: 5,
  // ❌ WRONG: Adding IP whitelist not in specification
  skip: (req) => whitelist.includes(req.ip),
  // ❌ WRONG: Adding custom error messages not specified
  message: (req) => `Too many attempts from ${req.ip}. Try again later.`
});

// ❌ WRONG: Adding OAuth integration not in specification
const googleAuth = passport.use(new GoogleStrategy({
  clientID: process.env.GOOGLE_CLIENT_ID,
  clientSecret: process.env.GOOGLE_CLIENT_SECRET
}));

// ❌ WRONG: Changing token expiration without approval
const generateToken = (userId: number) => {
  return jwt.sign(
    { userId },
    process.env.JWT_SECRET!,
    { expiresIn: '7d' } // Changed from specified 24h to 7 days
  );
};

❌ Incorrect Implementation - Making Architectural Decisions:

// ❌ WRONG: Changing database technology without approval
// Specification said PostgreSQL, but implementing MongoDB
const mongoose = require('mongoose');
const userSchema = new mongoose.Schema({
  email: String,
  password: String
});

// ❌ WRONG: Changing API design without approval
// Specification said REST API, but implementing GraphQL
const typeDefs = gql`
  type User {
    id: ID!
    email: String!
  }
  type Query {
    users: [User]
  }
`;

// ❌ WRONG: Adding caching layer not in specification
const redis = require('redis');
const client = redis.createClient();

Memory Documentation by Coder Agent

What Memory the Coder Agent Writes: The Coder Agent documents implementation patterns and technical solutions, but never architectural decisions:

# memory/patterns.md - Coder Agent Entries

## JWT Authentication Implementation Pattern
**Problem**: Implementing JWT authentication with rate limiting
**Solution**: Express middleware with jsonwebtoken and express-rate-limit
**Implementation Details**:
- bcrypt salt rounds: 12 (security standard)
- JWT token structure: { userId, iat, exp }
- Rate limiting middleware placement: before authentication routes
- Error handling: Generic messages to prevent information disclosure
**Code Pattern**:
```typescript
const authLimiter = rateLimit({
  windowMs: 15 * 60 * 1000,
  max: 5,
  message: { error: 'Too many authentication attempts' }
});

router.post('/login', authLimiter, async (req, res) => {
  // Implementation pattern for secure login
});

Usage Context: REST API authentication with security requirements Performance: under 100ms token generation, under 50ms token validation

**What Memory the Coder Agent Does NOT Write:**
```markdown
# ❌ WRONG - Coder Agent should NOT write architectural decisions

## Authentication Strategy Decision
**Context**: Need user authentication for todo application
**Decision**: Use JWT instead of session-based authentication
**Rationale**: Stateless authentication better for API scalability
**Alternatives**: Session cookies (rejected for API design)
**Status**: Approved

# This type of decision belongs to Architect Agent, not Coder Agent

Specification Compliance Validation

Before Implementation - Specification Check:

Coder Agent Checklist:
✅ Architecture specification approved and available
✅ All technology choices clearly specified
✅ Database schema defined with relationships
✅ API endpoints specified with security requirements
✅ Authentication method and parameters defined
✅ Input validation requirements documented
✅ Error handling approach specified
✅ Performance requirements clearly stated

Proceeding with implementation...

During Implementation - Compliance Monitoring:

Implementation Progress:
✅ Database models match specified schema exactly
✅ API endpoints implement specified functionality only
✅ Authentication uses specified JWT parameters
✅ Input validation follows specified rules
✅ Error handling matches specified approach
✅ No features added beyond specification
✅ No architectural changes made
✅ All security requirements implemented as specified

Implementation compliant with specifications.

After Implementation - Compliance Verification:

Final Compliance Check:
✅ All specified features implemented completely
✅ No unspecified features added
✅ All security requirements met exactly
✅ Performance requirements satisfied
✅ Code follows specified technology stack
✅ Database schema matches specification
✅ API design matches specification exactly
✅ Ready for Reviewer Agent validation

Implementation complete and specification-compliant.

Common Mistakes and Warnings

⚠️ Critical Warnings

• Never Implement Features Not in Specifications: The Coder Agent must implement only what is explicitly specified. Adding features, even "obvious" ones, violates agent boundaries and creates scope creep that undermines project control.

• Never Make Architectural Decisions During Implementation: Technology choices, design patterns, and system structure are determined by the Architect Agent. The Coder Agent implements these decisions but never changes them.

Common Mistakes

Mistake: Adding "helpful" features not in specifications

Why it happens: Developers see opportunities for improvement and add features they think users will want
How to avoid: Implement only what is specified, request specification updates for additional features
If it happens: Remove unspecified features and return to specification-compliant implementation

Mistake: Making technology substitutions during implementation

Why it happens: Developers encounter implementation challenges and switch to "easier" technologies
How to avoid: Use only technologies specified in architecture specification, request clarification for ambiguities
If it happens: Revert to specified technologies or request architectural specification update

Mistake: Implementing partial features to "save time"

Why it happens: Time pressure leads to incomplete implementations that will be "finished later"
How to avoid: Implement features completely according to specifications or don't implement them at all
If it happens: Complete partial implementations before proceeding to additional features

Mistake: Making assumptions about ambiguous specifications

Why it happens: Developers want to maintain momentum and guess at unclear requirements
How to avoid: Stop implementation and request specification clarification for any ambiguous requirements
If it happens: Revert assumption-based code and get proper specification clarification

Best Practices

• ✅ Implement Specifications Exactly: Follow approved specifications without additions, modifications, or substitutions
• ✅ Request Clarification for Ambiguity: Stop implementation and ask for specification updates when requirements are unclear
• ✅ Complete Features Fully: Implement all aspects of specified features rather than creating partial implementations
• ✅ Document Implementation Patterns: Capture technical solutions and code patterns in memory for future reuse
• ✅ Maintain Agent Boundaries: Focus on implementation details while respecting architectural decisions made by other agents