diegosouzapw Task Specification Format
Compact YAML format for parallel task files in parallel/TS-XXXX-slug/tasks/.
Complete Task Example
---
id: task-001
component: users
wave: 1
deps: []
blocks: [task-004, task-005]
agent: python-experts:django-expert
skills: [python-experts:python-style, python-experts:django-dev, python-experts:django-api]
tech_spec: TS-0042
contracts: [contracts/types.py, contracts/api-schema.yaml]
---
# task-001: User Management
## Scope
CREATE: apps/users/{models,views,serializers,urls}.py, apps/users/tests/*.py
MODIFY: config/urls.py
BOUNDARY: apps/orders/*, apps/products/*, apps/*/migrations/*
## Requirements
- User model with email authentication
- UserSerializer with explicit fields
- UserViewSet (list, retrieve, create, update)
- Email uniqueness validation
## Checklist
- [ ] Model matches UserDTO in contracts/types.py
- [ ] API matches /api/users/* in contracts/api-schema.yaml
- [ ] pytest apps/users/ passes
- [ ] mypy apps/users/ passes
- [ ] ruff check apps/users/ passes
- [ ] No files modified outside scope
YAML Frontmatter Fields
| Field | Required | Description |
|---|---|---|
id |
Yes | Task identifier (task-NNN or task-NNN-component) |
component |
Yes | System component name |
wave |
Yes | Dependency wave number (1, 2, 3...) |
deps |
Yes | Task IDs this depends on (empty list [] if none) |
blocks |
No | Task IDs this blocks (optional) |
agent |
Yes | Recommended agent type |
skills |
Yes | Skills the agent should invoke (list from agent-skills-mapping.yaml) |
tech_spec |
No | Tech Spec ID (if applicable) |
contracts |
Yes | Contract files to reference (relative paths) |
Note: skills are stored in task files so prompt generation can include them in === REQUIRED SKILLS === sections. They are NOT stored in manifest.json.
Scope Section Format
Use compact notation with three directives:
CREATE
Files to create (use glob patterns). A file can only be in CREATE for ONE task.
CREATE: apps/users/{models,views,serializers,urls}.py, apps/users/tests/*.py
MODIFY
Existing files to modify. Use scoped syntax for parallel modifications:
Unscoped (whole file - only ONE task per wave can use this):
MODIFY: config/urls.py, config/settings.py
Scoped (specific section - multiple tasks in same wave can modify different scopes):
MODIFY: apps/users/models.py::User.save # Owns User.save method
MODIFY: apps/users/models.py::User.clean # Different task owns User.clean
MODIFY: apps/users/views.py::UserViewSet # Owns entire class
MODIFY: config/urls.py::urlpatterns # Owns urlpatterns list
Scoped syntax rules:
file.py::ClassName- owns entire classfile.py::function_name- owns entire functionfile.py::ClassName.method- owns specific method- Scopes must NOT overlap (no nesting like
::Classand::Class.methodin same wave)
BOUNDARY
Files NOT to touch (owned by other tasks):
BOUNDARY: apps/orders/*, apps/products/*, apps/*/migrations/*
Task Naming Convention
task-{number}-{component}.md
Examples:
- task-001-users.md
- task-002-products.md
- task-003-orders.md
- task-004-api.md
- task-005-integration.md
Agent Type Selection
| Task Files | Agent | Description |
|---|---|---|
apps/*/models.py, apps/*/views.py |
python-experts:django-expert |
Django models, views, serializers |
api/*.py, routers/*.py |
python-experts:fastapi-expert |
FastAPI endpoints |
src/components/*.tsx |
frontend-experts:react-typescript-expert |
React components |
**/test_*.py, **/tests/*.py |
python-experts:python-testing-expert |
Python tests |
*.spec.ts, *.test.tsx |
frontend-experts:playwright-testing-expert |
TypeScript/E2E tests |
terraform/, docker-compose.yml |
devops-data:devops-expert |
Infrastructure |
| Integration, architecture | devops-data:cto-architect |
Cross-cutting concerns |
Contract References
Contracts are in the same parallel directory:
parallel/TS-0042-slug/
contracts/
types.py # Reference as: contracts/types.py
api-schema.yaml # Reference as: contracts/api-schema.yaml
tasks/
task-001-users.md
Wave Dependencies
Tasks in Wave N can only depend on tasks in Waves 1 to N-1:
Wave 1: task-001, task-002 (no dependencies, run in parallel)
Wave 2: task-003 (depends on task-001, task-002)
Wave 3: task-004 (depends on task-003)
deps vs blocks
deps: Tasks that MUST complete before this task startsblocks: Tasks that CANNOT start until this task completes
Both express the same relationship from different perspectives:
# task-001
blocks: [task-003]
# task-003
deps: [task-001]
Requirements Section
Clear, actionable requirements:
## Requirements
- Implement `User` model with fields: `email`, `username`, `password`, `is_active`
- Create `UserSerializer` with all User fields (hide password)
- Implement `UserViewSet` with: list, retrieve, create, update
- Add email validation and uniqueness constraint
- Test coverage: minimum 85%
Checklist Section
Verification criteria:
## Checklist
- [ ] Model matches DTO in contracts/types.py
- [ ] API matches schema in contracts/api-schema.yaml
- [ ] pytest apps/users/ passes
- [ ] mypy apps/users/ --strict passes
- [ ] Coverage >= 85%
- [ ] No files modified outside scope
Why Compact Format?
- Token efficiency: Less tokens for agent context
- Faster parsing: YAML frontmatter is standard
- Clear boundaries: Scope section is scannable
- Actionable checklist: Verification is explicit
Validation Rules
Before using tasks:
- Every task has unique
id - Every task has
agentassigned - Every task has
skillslist (from agent-skills-mapping.yaml) - Every task has
contractsreferenced - Every task has BOUNDARY section
- No circular dependencies in
deps - Wave numbers are sequential (1, 2, 3...)
- Wave 1 tasks have
deps: []
Output Format
The Output Format JSON block is not included in task files or generated prompts. It's managed via system prompt by the external execution tool (cpo orchestrator).
This ensures consistent JSON output format across all agents without duplicating the schema in every prompt.