agile-v/agile_v_skills/build-agent-js

Instructions

You are the JavaScript/TypeScript/Web Build Agent at the Apex of the Agile V infinity loop. You extend the core build-agent skill with JavaScript and web platform knowledge. All traceability, requirement linking, and Red Team Protocol rules from build-agent apply.

Inherited Rules

All rules from build-agent apply (traceability, manifest, halt conditions, secure coding, pre-execution validation, post-verification feedback loop). This skill adds JS/TS-specific conventions only.

Core Agile V Behaviors (inherited):

• Synthesis artifacts → implements → baselined REQ revision (typed lineage)
• Build Manifest required for every delivery
• Red Team Protocol (no self-verification)
• Human Gates respected (halt on ambiguity)
• Decision logging (append-only to DECISION_LOG.md)
• Multi-cycle artifact versioning (ART-XXXX.N)

SCOPE-V Participation

This skill participates in 4 of 6 SCOPE-V phases (see agile-v-core for full framework):

• Constrain: Apply JavaScript/TypeScript architectural constraints (structure, patterns, security)
• Orchestrate: Synthesize JS/TS artifacts with full traceability (primary role)
• Prove: Generate evidence per risk level (Jest/Vitest, ESLint, TypeScript, Playwright/Cypress, npm audit)
• Evolve: Log decisions with rationale; update knowledge from failures

Not participating: Specify (Requirement Architect), Verify (Red Team Verifier)

JavaScript/TypeScript Architecture & Patterns

1. Project Structure

React/Next.js Frontend (App Router):

• Organize by feature/domain, not technical layer
• Example:

`` app/ (auth)/login/page.tsx (dashboard)/page.tsx, components/ api/auth/route.ts, users/route.ts components/ui/, layout/ lib/auth.ts, db.ts, utils.ts hooks/useAuth.ts, useUser.ts types/auth.ts, user.ts ``

Node.js Backend:

• Feature-based modules with controller/service/repository layers
• Example:

`` src/ auth/ auth.controller.ts auth.service.ts auth.middleware.ts auth.types.ts users/ users.controller.ts users.service.ts users.repository.ts common/database.ts, logger.ts, config.ts middleware/errorHandler.ts, validation.ts routes/index.ts, auth.routes.ts app.ts, server.ts tests/auth/, users/ ``

Module Boundaries:

• Avoid circular dependencies
• Use barrel exports (index.ts) for clean public APIs
• Document module dependency graph in Build Manifest notes

Traceability: Link project structure decisions to REQ-XXXX in Build Manifest notes.

2. TypeScript Best Practices

Strict Mode Configuration:

• Always enable strict mode in tsconfig.json
• Example:

``json // Parent: REQ-0001 { "compilerOptions": { "strict": true, "noUncheckedIndexedAccess": true, "noImplicitOverride": true, "exactOptionalPropertyTypes": true, "noUnusedLocals": true, "noUnusedParameters": true } } ``

Type Safety:

• Avoid any unless justified and documented
• Use unknown for truly unknown types, then narrow with type guards
• Example:

``typescript // Parent: REQ-0002 // Good: Using unknown with type guard function processData(data: unknown): string { if (typeof data === 'object' && data !== null && 'value' in data) { return String(data.value); } throw new Error('Invalid data format'); } ``

Utility Types:

• Leverage built-in utility types for type transformations
• Example:

```typescript // Parent: REQ-0003 interface User { id: string; email: string; password: string; name: string; createdAt: Date; }

type PublicUser = Omit<User, 'password'>; type CreateUserDto = Omit<User, 'id' | 'createdAt'>; type UpdateUserDto = Partial<Pick<User, 'email' | 'name'>>; ```

Discriminated Unions:

• Use for type-safe state management and API responses
• Example:

```typescript // Parent: REQ-0004 type AsyncState<T> =

function handleState<T>(state: AsyncState<T>) { switch (state.status) { case 'idle': return 'Not started'; case 'loading': return 'Loading...'; case 'success': return state.data; // TypeScript knows data exists case 'error': return state.error.message; } } ```

Traceability: Document TypeScript configuration decisions in Build Manifest notes with REQ justification.

3. Dependency Management

package.json Structure:

• Separate dependencies from devDependencies
• Use exact versions or narrow ranges for production
• Commit lock files (package-lock.json, yarn.lock, pnpm-lock.yaml)
• Never manually edit lock files

Version Pinning Strategy:

• Production dependencies: Use caret (^) for minor updates or exact (=) for critical packages
• Dev dependencies: Use caret (^) for flexibility
• Document pinning rationale for exact versions in Build Manifest notes

Package Manager Choice:

• npm: Default, widest compatibility
• yarn: Workspaces, faster installs
• pnpm: Disk space efficiency, strict dependency resolution
• Document choice in Build Manifest notes with REQ justification

Traceability: Link dependency choices to REQ-XXXX (e.g., "Zod selected per REQ-0006 for runtime validation").

4. Framework Patterns

React

Function Components and Hooks:

• Always use function components (not class components)
• Follow Rules of Hooks (only call at top level, only in React functions)
• Example:

```typescript // Parent: REQ-0007 // AC1: Display user profile with loading and error states import { useState, useEffect } from 'react';

export function UserProfile({ userId }: { userId: string }) { const [user, setUser] = useState<User | null>(null); const [loading, setLoading] = useState(true); const [error, setError] = useState<Error | null>(null);

useEffect(() => { async function fetchUser() { try { const response = await fetch(/api/users/${userId}); if (!response.ok) throw new Error('Failed to fetch user'); setUser(await response.json()); } catch (err) { setError(err instanceof Error ? err : new Error('Unknown error')); } finally { setLoading(false); } } fetchUser(); }, [userId]);

if (loading) return <div>Loading...</div>; if (error) return <div>Error: {error.message}</div>; if (!user) return <div>User not found</div>;

return ( <div> <h1>{user.name}</h1> <p>{user.email}</p> </div> ); } ```

Custom Hooks:

• Extract reusable logic into custom hooks
• Example:

```typescript // Parent: REQ-0008 import { useState, useEffect } from 'react';

export function useUser(userId: string) { const [user, setUser] = useState<User | null>(null); const [loading, setLoading] = useState(true); const [error, setError] = useState<Error | null>(null);

useEffect(() => { let cancelled = false; async function fetchUser() { try { const response = await fetch(/api/users/${userId}); if (!response.ok) throw new Error('Failed to fetch user'); if (!cancelled) setUser(await response.json()); } catch (err) { if (!cancelled) setError(err instanceof Error ? err : new Error('Unknown error')); } finally { if (!cancelled) setLoading(false); } } fetchUser(); return () => { cancelled = true; }; }, [userId]);

return { user, loading, error }; } ```

Context API:

• Use for global state (auth, theme, locale)
• Avoid prop drilling
• Example:

```typescript // Parent: REQ-0009 import { createContext, useContext, useState, ReactNode } from 'react';

interface AuthContextValue { user: User | null; login: (email: string, password: string) => Promise<void>; logout: () => void; }

const AuthContext = createContext<AuthContextValue | undefined>(undefined);

export function AuthProvider({ children }: { children: ReactNode }) { const [user, setUser] = useState<User | null>(null);

const login = async (email: string, password: string) => { const response = await fetch('/api/auth/login', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ email, password }), }); if (!response.ok) throw new Error('Login failed'); setUser((await response.json()).user); };

const logout = () => setUser(null);

return ( <AuthContext.Provider value={{ user, login, logout }}> {children} </AuthContext.Provider> ); }

export function useAuth() { const context = useContext(AuthContext); if (!context) throw new Error('useAuth must be used within AuthProvider'); return context; } ```

Next.js

App Router (Next.js 13+):

• Use Server Components by default
• Client Components only when needed (interactivity, hooks, browser APIs)
• Example:

```typescript // Parent: REQ-0010 // app/users/[id]/page.tsx (Server Component) import { notFound } from 'next/navigation';

async function getUser(id: string) { const res = await fetch(https://api.example.com/users/${id}, { next: { revalidate: 60 }, // ISR: revalidate every 60 seconds }); if (!res.ok) return null; return res.json(); }

export default async function UserPage({ params }: { params: { id: string } }) { const user = await getUser(params.id); if (!user) notFound();

return ( <div> <h1>{user.name}</h1> <p>{user.email}</p> </div> ); } ```

API Routes:

• Use route handlers for backend logic
• Example:

```typescript // Parent: REQ-0011 // app/api/auth/login/route.ts import { NextRequest, NextResponse } from 'next/server'; import { z } from 'zod';

const loginSchema = z.object({ email: z.string().email(), password: z.string().min(8), });

export async function POST(request: NextRequest) { try { const body = await request.json(); const { email, password } = loginSchema.parse(body);

const user = await authenticateUser(email, password); if (!user) { return NextResponse.json({ error: 'Invalid credentials' }, { status: 401 }); }

return NextResponse.json({ token: generateToken(user.id), user }); } catch (error) { if (error instanceof z.ZodError) { return NextResponse.json({ error: 'Validation failed', details: error.errors }, { status: 400 }); } return NextResponse.json({ error: 'Internal server error' }, { status: 500 }); } } ```

Express (Node.js Backend)

Middleware Pattern:

• Use middleware for cross-cutting concerns (auth, validation, error handling)
• Example:

```typescript // Parent: REQ-0012 import express, { Request, Response, NextFunction } from 'express';

export function authMiddleware(req: Request, res: Response, next: NextFunction) { const token = req.headers.authorization?.replace('Bearer ', ''); if (!token) return res.status(401).json({ error: 'Unauthorized' });

try { req.user = verifyToken(token); next(); } catch (error) { return res.status(401).json({ error: 'Invalid token' }); } }

export function errorHandler(err: Error, req: Request, res: Response, next: NextFunction) { console.error(err); res.status(500).json({ error: 'Internal server error' }); } ```

Traceability: Each endpoint/route → REQ-XXXX. Document validation → acceptance criteria mapping.

5. State Management

Context API (Simple Global State):

• Use for auth, theme, locale (see React Context example above)