parallel-task-format

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 class
• file.py::function_name - owns entire function
• file.py::ClassName.method - owns specific method
• Scopes must NOT overlap (no nesting like ::Class and ::Class.method in 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 starts
• blocks: 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?

1. Token efficiency: Less tokens for agent context
2. Faster parsing: YAML frontmatter is standard
3. Clear boundaries: Scope section is scannable
4. Actionable checklist: Verification is explicit

Validation Rules

Before using tasks:

• Every task has unique id
• Every task has agent assigned
• Every task has skills list (from agent-skills-mapping.yaml)
• Every task has contracts referenced
• 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.