365 lines
12 KiB
YAML
365 lines
12 KiB
YAML
# Implementation Task Template Schema
|
|
# Used by the Architect agent to create implementation tasks
|
|
# Tasks are generated from design_document.yml with full context
|
|
|
|
# ============================================================================
|
|
# TASK DEFINITION
|
|
# ============================================================================
|
|
task:
|
|
# Required fields
|
|
id: task_<type>_<entity> # e.g., task_create_model_user, task_create_api_users
|
|
type: create | update | delete | refactor | test | review
|
|
title: string # Human-readable title
|
|
agent: frontend | backend # Which agent implements this
|
|
entity_id: string # Primary entity ID from design_document
|
|
entity_ids: [string] # All entity IDs this task covers (for multi-entity tasks)
|
|
status: pending | in_progress | review | approved | completed | blocked
|
|
|
|
# Execution layer (from dependency_graph)
|
|
layer: integer # Which layer this task belongs to (1, 2, 3...)
|
|
parallel_group: string # Group ID for parallel execution
|
|
|
|
# Optional fields
|
|
description: string # Detailed implementation notes
|
|
file_paths: [string] # Files to create/modify
|
|
dependencies: [string] # Task IDs that must complete first
|
|
acceptance_criteria: [string] # Checklist for completion
|
|
priority: low | medium | high # Task priority
|
|
complexity: low | medium | high # Estimated complexity
|
|
|
|
# Tracking (set by system)
|
|
created_at: datetime
|
|
assigned_at: datetime
|
|
completed_at: datetime
|
|
reviewed_by: string
|
|
review_notes: string
|
|
|
|
# ============================================================================
|
|
# CONTEXT SECTION (Passed to subagent)
|
|
# ============================================================================
|
|
# This is the critical section that provides full context to subagents
|
|
# Generated from design_document.yml during task creation
|
|
|
|
context:
|
|
# Source reference
|
|
design_version: string # design_document revision
|
|
workflow_version: string # Workflow version (v001, etc.)
|
|
context_snapshot_path: string # Path to full context file
|
|
|
|
# TARGET: What this task implements
|
|
target:
|
|
entity_id: string # model_user, api_create_user, etc.
|
|
entity_type: model | api | page | component
|
|
definition: object # Full definition from design_document
|
|
|
|
# For models
|
|
model:
|
|
name: string
|
|
table_name: string
|
|
fields: [field_definition]
|
|
relations: [relation_definition]
|
|
validations: [validation_rule]
|
|
indexes: [index_definition]
|
|
|
|
# For APIs
|
|
api:
|
|
method: string
|
|
path: string
|
|
summary: string
|
|
path_params: [param_definition]
|
|
query_params: [param_definition]
|
|
request_body: object
|
|
responses: [response_definition]
|
|
auth: object
|
|
|
|
# For pages
|
|
page:
|
|
path: string
|
|
layout: string
|
|
data_needs: [data_requirement]
|
|
components: [string]
|
|
seo: object
|
|
auth: object
|
|
|
|
# For components
|
|
component:
|
|
name: string
|
|
props: [prop_definition]
|
|
events: [event_definition]
|
|
uses_apis: [string]
|
|
uses_components: [string]
|
|
variants: [string]
|
|
|
|
# DEPENDENCIES: What this task needs
|
|
dependencies:
|
|
# Models this task interacts with
|
|
models:
|
|
- id: string # model_user
|
|
definition:
|
|
name: string
|
|
fields: [field_definition]
|
|
relations: [relation_definition]
|
|
|
|
# APIs this task needs
|
|
apis:
|
|
- id: string # api_get_user
|
|
definition:
|
|
method: string
|
|
path: string
|
|
request_body: object
|
|
responses: [object]
|
|
|
|
# Components this task uses
|
|
components:
|
|
- id: string # component_button
|
|
definition:
|
|
props: [prop_definition]
|
|
events: [event_definition]
|
|
|
|
# CONTRACTS: Input/Output specifications
|
|
contracts:
|
|
# What this task receives from previous tasks
|
|
inputs:
|
|
- from_task: string # task_create_model_user
|
|
provides: string # model_user
|
|
type: model | api | component | file
|
|
|
|
# What this task provides to later tasks
|
|
outputs:
|
|
- entity_id: string # api_create_user
|
|
type: model | api | component | file
|
|
consumers: [string] # [page_user_create, component_user_form]
|
|
|
|
# FILES: File operations
|
|
files:
|
|
# Files to create
|
|
create: [string]
|
|
|
|
# Files to modify
|
|
modify: [string]
|
|
|
|
# Files to read for patterns/context
|
|
reference:
|
|
- path: string
|
|
purpose: string # "Similar component pattern", "API route pattern"
|
|
|
|
# VALIDATION: How to verify completion
|
|
validation:
|
|
# Required checks
|
|
checks:
|
|
- type: file_exists | lint | typecheck | test | build
|
|
target: string # File or test pattern
|
|
required: boolean
|
|
|
|
# Acceptance criteria (human-readable)
|
|
criteria:
|
|
- criterion: string
|
|
verification: string # How to verify this
|
|
|
|
# HINTS: Implementation guidance
|
|
hints:
|
|
# Patterns to follow
|
|
patterns:
|
|
- pattern: string # "Use existing API route pattern"
|
|
reference: string # "app/api/health/route.ts"
|
|
|
|
# Things to avoid
|
|
avoid:
|
|
- issue: string
|
|
reason: string
|
|
|
|
# Code examples
|
|
examples:
|
|
- description: string
|
|
file: string
|
|
|
|
# ============================================================================
|
|
# TASK GENERATION RULES
|
|
# ============================================================================
|
|
generation_rules:
|
|
from_model:
|
|
task_id: "task_create_model_{model_name}"
|
|
type: create
|
|
agent: backend
|
|
file_paths:
|
|
- "prisma/schema.prisma" # Add model to schema
|
|
- "app/models/{model_name}.ts" # TypeScript types
|
|
acceptance_criteria:
|
|
- "Model defined in Prisma schema"
|
|
- "TypeScript types exported"
|
|
- "Relations properly configured"
|
|
- "Migrations generated"
|
|
|
|
from_api:
|
|
task_id: "task_create_api_{endpoint_name}"
|
|
type: create
|
|
agent: backend
|
|
file_paths:
|
|
- "app/api/{path}/route.ts"
|
|
acceptance_criteria:
|
|
- "Endpoint responds to {method} requests"
|
|
- "Request validation implemented"
|
|
- "Response matches contract"
|
|
- "Auth requirements enforced"
|
|
- "Error handling complete"
|
|
|
|
from_page:
|
|
task_id: "task_create_page_{page_name}"
|
|
type: create
|
|
agent: frontend
|
|
file_paths:
|
|
- "app/{path}/page.tsx"
|
|
acceptance_criteria:
|
|
- "Page renders at {path}"
|
|
- "Data fetching implemented"
|
|
- "Components integrated"
|
|
- "Auth protection active"
|
|
- "SEO metadata set"
|
|
|
|
from_component:
|
|
task_id: "task_create_component_{component_name}"
|
|
type: create
|
|
agent: frontend
|
|
file_paths:
|
|
- "app/components/{ComponentName}.tsx"
|
|
acceptance_criteria:
|
|
- "Component renders correctly"
|
|
- "Props typed and documented"
|
|
- "Events emitted properly"
|
|
- "Variants implemented"
|
|
- "Accessible (a11y)"
|
|
|
|
# ============================================================================
|
|
# VALID STATUS TRANSITIONS
|
|
# ============================================================================
|
|
status_transitions:
|
|
pending:
|
|
- in_progress # Start work
|
|
- blocked # Dependencies not met
|
|
in_progress:
|
|
- review # Ready for review
|
|
- blocked # Hit blocker
|
|
review:
|
|
- approved # Review passed
|
|
- in_progress # Changes requested
|
|
approved:
|
|
- completed # Final completion
|
|
blocked:
|
|
- pending # Blocker resolved
|
|
- in_progress # Resume after unblock
|
|
|
|
# ============================================================================
|
|
# EXAMPLE: Complete Task with Context
|
|
# ============================================================================
|
|
example_task:
|
|
id: task_create_api_create_user
|
|
type: create
|
|
title: "Create User API Endpoint"
|
|
agent: backend
|
|
entity_id: api_create_user
|
|
entity_ids: [api_create_user]
|
|
status: pending
|
|
layer: 2
|
|
parallel_group: "layer_2_apis"
|
|
description: "Implement POST /api/users endpoint for user registration"
|
|
file_paths:
|
|
- app/api/users/route.ts
|
|
dependencies:
|
|
- task_create_model_user
|
|
acceptance_criteria:
|
|
- "POST /api/users returns 201 on success"
|
|
- "Validates email format"
|
|
- "Returns 409 if email exists"
|
|
- "Hashes password before storage"
|
|
- "Returns user object without password"
|
|
priority: high
|
|
complexity: medium
|
|
|
|
context:
|
|
design_version: "rev_3"
|
|
workflow_version: "v001"
|
|
context_snapshot_path: ".workflow/versions/v001/contexts/api_create_user.yml"
|
|
|
|
target:
|
|
entity_id: api_create_user
|
|
entity_type: api
|
|
api:
|
|
method: POST
|
|
path: /api/users
|
|
summary: "Create a new user"
|
|
request_body:
|
|
type: object
|
|
properties:
|
|
email: { type: string, required: true, validation: email }
|
|
name: { type: string, required: true, validation: "min:1,max:100" }
|
|
password: { type: string, required: true, validation: "min:8" }
|
|
responses:
|
|
- status: 201
|
|
schema: { id: uuid, email: string, name: string, created_at: datetime }
|
|
- status: 400
|
|
schema: { error: string, details: array }
|
|
- status: 409
|
|
schema: { error: string }
|
|
auth:
|
|
required: false
|
|
|
|
dependencies:
|
|
models:
|
|
- id: model_user
|
|
definition:
|
|
name: User
|
|
table_name: users
|
|
fields:
|
|
- { name: id, type: uuid, constraints: [primary_key] }
|
|
- { name: email, type: string, constraints: [unique, not_null] }
|
|
- { name: name, type: string, constraints: [not_null] }
|
|
- { name: password_hash, type: string, constraints: [not_null] }
|
|
- { name: created_at, type: datetime, constraints: [not_null] }
|
|
|
|
contracts:
|
|
inputs:
|
|
- from_task: task_create_model_user
|
|
provides: model_user
|
|
type: model
|
|
outputs:
|
|
- entity_id: api_create_user
|
|
type: api
|
|
consumers: [page_signup, component_signup_form]
|
|
|
|
files:
|
|
create:
|
|
- app/api/users/route.ts
|
|
reference:
|
|
- path: app/api/health/route.ts
|
|
purpose: "API route pattern"
|
|
- path: app/lib/db.ts
|
|
purpose: "Database connection"
|
|
- path: app/lib/auth.ts
|
|
purpose: "Password hashing"
|
|
|
|
validation:
|
|
checks:
|
|
- { type: typecheck, target: "app/api/users/route.ts", required: true }
|
|
- { type: lint, target: "app/api/users/route.ts", required: true }
|
|
- { type: test, target: "app/api/users/*.test.ts", required: false }
|
|
criteria:
|
|
- criterion: "Returns 201 with user object on success"
|
|
verification: "curl -X POST /api/users with valid data"
|
|
- criterion: "Returns 409 if email exists"
|
|
verification: "curl -X POST /api/users with duplicate email"
|
|
|
|
hints:
|
|
patterns:
|
|
- pattern: "Use NextResponse for responses"
|
|
reference: "app/api/health/route.ts"
|
|
- pattern: "Use Prisma for database operations"
|
|
reference: "app/lib/db.ts"
|
|
avoid:
|
|
- issue: "Don't store plain text passwords"
|
|
reason: "Security vulnerability - always hash with bcrypt"
|
|
- issue: "Don't return password_hash in response"
|
|
reason: "Sensitive data exposure"
|
|
examples:
|
|
- description: "Similar API endpoint"
|
|
file: "app/api/health/route.ts"
|