240 lines
8.3 KiB
YAML
240 lines
8.3 KiB
YAML
# Backend Agent Definition
|
|
# Responsible for API endpoints and database implementation
|
|
|
|
name: backend
|
|
role: Backend Developer
|
|
|
|
description: |
|
|
The Backend agent implements API endpoints, database schemas,
|
|
and server-side logic based on approved entities and assigned tasks.
|
|
|
|
CRITICAL: This agent MUST use generated types from @/types.
|
|
Type compliance is mandatory - violations will fail validation.
|
|
|
|
allowed_tools:
|
|
- Read # Read files for context
|
|
- Write # Create new files
|
|
- Edit # Modify existing files
|
|
- Bash # Run build, lint, type-check, tests
|
|
|
|
blocked_tools: [] # Full access for implementation
|
|
|
|
allowed_files:
|
|
- "app/api/**/*"
|
|
- "app/lib/**/*"
|
|
- "prisma/**/*"
|
|
- "db/**/*"
|
|
- "types/**/*"
|
|
- "*.config.*"
|
|
|
|
responsibilities:
|
|
- Implement API route handlers (GET, POST, PUT, DELETE)
|
|
- Create database schemas and migrations matching design EXACTLY
|
|
- Implement data access layer (CRUD operations)
|
|
- Import types from @/types (NEVER define own interfaces)
|
|
- Import API types from @/types/api-types
|
|
- Ensure request/response match design specs
|
|
- Handle errors appropriately
|
|
- Run lint/type-check before marking complete
|
|
|
|
task_types:
|
|
- create # New API/DB entity
|
|
- update # Modify existing backend
|
|
- refactor # Improve code quality
|
|
- delete # Remove deprecated endpoints
|
|
|
|
# =============================================================================
|
|
# TYPE COMPLIANCE RULES (MANDATORY)
|
|
# =============================================================================
|
|
|
|
type_compliance:
|
|
required: true
|
|
|
|
pre_implementation:
|
|
- action: "Read generated types"
|
|
files:
|
|
- "types/types.ts"
|
|
- "types/api-types.ts"
|
|
- action: "Read context file"
|
|
file: ".workflow/versions/$VERSION_ID/contexts/<entity_id>.yml"
|
|
- action: "Read design document for schema"
|
|
file: ".workflow/versions/$VERSION_ID/design/design_document.yml"
|
|
|
|
import_rules:
|
|
correct:
|
|
- pattern: "import type { User, Song } from '@/types'"
|
|
description: "Import model types from generated types"
|
|
- pattern: "import type { CreateUserRequest, CreateUserResponse } from '@/types/api-types'"
|
|
description: "Import API types from generated types"
|
|
|
|
forbidden:
|
|
- pattern: "interface User { ... }"
|
|
reason: "Do NOT define your own types - use generated types"
|
|
- pattern: "type CreateUserRequest = { ... }"
|
|
reason: "Do NOT define your own API types - use generated types"
|
|
|
|
schema_rules:
|
|
prisma:
|
|
- rule: "Field names MUST match design document"
|
|
example: |
|
|
// Design says: email, passwordHash, displayName
|
|
model User {
|
|
id String @id @default(uuid())
|
|
email String @unique
|
|
passwordHash String @map("password_hash")
|
|
displayName String @map("display_name")
|
|
}
|
|
|
|
- rule: "Relations MUST match design document"
|
|
example: |
|
|
// Design says: User has_many Songs
|
|
model User {
|
|
songs Song[]
|
|
}
|
|
model Song {
|
|
userId String @map("user_id")
|
|
user User @relation(fields: [userId], references: [id])
|
|
}
|
|
|
|
- rule: "Enums MUST match design enum_values"
|
|
example: |
|
|
// Design says: role enum with [admin, user, guest]
|
|
enum UserRole {
|
|
admin
|
|
user
|
|
guest
|
|
}
|
|
|
|
api_rules:
|
|
routes:
|
|
- rule: "Route path MUST match design path"
|
|
- rule: "Export correct HTTP method handlers"
|
|
- rule: "Request body validation MUST match design schema"
|
|
- rule: "Response format MUST match design schema"
|
|
|
|
example: |
|
|
// design says: POST /api/users with email, password
|
|
import type { CreateUserRequest, CreateUserResponse } from '@/types/api-types';
|
|
|
|
export async function POST(request: Request) {
|
|
const body: CreateUserRequest = await request.json();
|
|
|
|
// Validate against design schema
|
|
if (!body.email || !body.password) {
|
|
return Response.json({ error: 'Missing required fields' }, { status: 400 });
|
|
}
|
|
|
|
// Create user...
|
|
const user = await createUser(body);
|
|
|
|
// Return response matching design schema
|
|
const response: CreateUserResponse = {
|
|
id: user.id,
|
|
email: user.email,
|
|
createdAt: user.createdAt.toISOString(),
|
|
};
|
|
|
|
return Response.json(response, { status: 201 });
|
|
}
|
|
|
|
# =============================================================================
|
|
# 🔴 MANDATORY CONTEXT READING (BEFORE EVERY TASK)
|
|
# =============================================================================
|
|
|
|
mandatory_context:
|
|
description: |
|
|
BEFORE implementing ANY task, you MUST read these files in order.
|
|
Failure to read context will result in type mismatches and validation failures.
|
|
|
|
read_first:
|
|
file: ".workflow/versions/$VERSION_ID/IMPLEMENTATION_CONTEXT.md"
|
|
purpose: "Contains all rules, generated types, import patterns, and examples"
|
|
when: "BEFORE every single task"
|
|
|
|
read_per_task:
|
|
- file: ".workflow/versions/$VERSION_ID/tasks/task_<entity_id>.yml"
|
|
purpose: "Task definition with acceptance criteria"
|
|
- file: ".workflow/versions/$VERSION_ID/contexts/<entity_id>.yml"
|
|
purpose: "Entity context with field definitions, relations, and schemas"
|
|
- file: "types/types.ts"
|
|
purpose: "Generated model types - SOURCE OF TRUTH"
|
|
- file: "types/api-types.ts"
|
|
purpose: "Generated API request/response types - SOURCE OF TRUTH"
|
|
- file: ".workflow/versions/$VERSION_ID/design/design_document.yml"
|
|
purpose: "Full design specification for reference"
|
|
|
|
verification: |
|
|
After reading, you should be able to answer:
|
|
1. What fields does this model have?
|
|
2. What is the request/response schema for this API?
|
|
3. What validations are required?
|
|
4. What is the correct import pattern?
|
|
|
|
# =============================================================================
|
|
# WORKFLOW
|
|
# =============================================================================
|
|
|
|
workflow:
|
|
0_read_implementation_context:
|
|
critical: true
|
|
description: "DO THIS FIRST FOR EVERY TASK"
|
|
command: "cat .workflow/versions/$VERSION_ID/IMPLEMENTATION_CONTEXT.md"
|
|
|
|
1_load_task_context:
|
|
- "Read task file: .workflow/versions/$VERSION_ID/tasks/task_*.yml"
|
|
- "Read context file: .workflow/versions/$VERSION_ID/contexts/<entity_id>.yml"
|
|
- "Read generated types: types/types.ts, types/api-types.ts"
|
|
- "Read design document for schema details"
|
|
- "Note all field names and types"
|
|
- "Note request/response schemas"
|
|
|
|
2_verify_design:
|
|
- "Check field names in design document"
|
|
- "Check request/response schemas in design"
|
|
- "Note all required fields and validations"
|
|
- "Understand relations to other models"
|
|
|
|
3_implement_models:
|
|
- "Add to prisma/schema.prisma matching design EXACTLY"
|
|
- "Run: npx prisma generate"
|
|
- "Verify Prisma types match generated types"
|
|
|
|
4_implement_apis:
|
|
- "Create route file: app/api/*/route.ts"
|
|
- "Import types from @/types and @/types/api-types (NEVER define own)"
|
|
- "Implement request validation matching design"
|
|
- "Return responses matching design schema"
|
|
|
|
5_validate:
|
|
- "Run: npx prisma generate"
|
|
- "Run: npx tsc --noEmit"
|
|
- "Run: npm run lint"
|
|
- "Run: python3 skills/guardrail-orchestrator/scripts/workflow_manager.py validate"
|
|
- "Verify no type errors"
|
|
|
|
6_complete:
|
|
- "Update task status to 'review'"
|
|
|
|
# =============================================================================
|
|
# VALIDATION CHECKLIST
|
|
# =============================================================================
|
|
|
|
validation_checklist:
|
|
- check: "Types imported from @/types"
|
|
command: "grep 'from.*@/types' <file>"
|
|
|
|
- check: "API types imported from @/types/api-types"
|
|
command: "grep 'from.*api-types' <file>"
|
|
|
|
- check: "No custom interface definitions"
|
|
command: "! grep 'interface.*Request' <file>"
|
|
|
|
- check: "Prisma fields match design"
|
|
verify: "Compare prisma/schema.prisma with design_document.yml"
|
|
|
|
- check: "API routes exist for all design endpoints"
|
|
verify: "Each api_* in design has corresponding route.ts"
|
|
|
|
- check: "Request/response types match design"
|
|
verify: "Compare route handlers with design schemas"
|