Enhanced Task JSON Schema

Purpose: Extended JSON schema for multi-stage orchestration with line-number precision, domain modeling, and prioritization

Version: 2.0

Last Updated: 2026-02-14

Backward Compatible: Yes (all new fields are optional)

Overview

This schema extends the base task.json and subtask_NN.json schemas with:

Line-number precision for context and reference files
Domain modeling fields (bounded_context, module, vertical_slice)
Contract tracking for API/interface dependencies
Design artifacts linking
ADR references for architectural decisions
Prioritization scores (RICE, WSJF)
Release planning (release_slice)

All enhancements are optional and backward compatible with existing task files.

Enhanced task.json Schema

New Fields

Field	Type	Required	Description
`bounded_context`	string	No	DDD bounded context (e.g., "authentication", "billing")
`module`	string	No	Module/package name (e.g., "@app/auth", "payment-service")
`vertical_slice`	string	No	Feature slice identifier (e.g., "user-registration", "checkout-flow")
`contracts`	array	No	API/interface contracts this feature depends on or provides
`design_components`	array	No	Design artifacts (Figma URLs, wireframes, mockups)
`related_adrs`	array	No	Architecture Decision Records (ADR file paths or IDs)
`rice_score`	object	No	RICE prioritization (Reach, Impact, Confidence, Effort)
`wsjf_score`	object	No	WSJF prioritization (Business Value, Time Criticality, Risk Reduction, Job Size)
`release_slice`	string	No	Release identifier (e.g., "v1.2.0", "Q1-2026", "MVP")

Enhanced context_files and reference_files Format

Old format (still supported):

"context_files": [
  ".opencode/context/core/standards/code-quality.md"
]

New format (line-number precision):

"context_files": [
  {
    "path": ".opencode/context/core/standards/code-quality.md",
    "lines": "1-50",
    "reason": "Pure function patterns for service layer"
  },
  {
    "path": ".opencode/context/core/standards/security-patterns.md",
    "lines": "120-145",
    "reason": "JWT token validation rules"
  }
]

Backward Compatibility: Both formats are valid. Agents should handle both:

String format → read entire file
Object format → read specified lines only

Enhanced subtask_NN.json Schema

New Fields

Field	Type	Required	Description
`bounded_context`	string	No	Inherited from task.json or subtask-specific override
`module`	string	No	Module this subtask modifies
`vertical_slice`	string	No	Feature slice this subtask belongs to
`contracts`	array	No	Contracts this subtask implements or depends on
`design_components`	array	No	Design artifacts relevant to this subtask
`related_adrs`	array	No	ADRs relevant to this subtask

TypeScript Interfaces

// Line-number precision for context files
interface ContextFileReference {
  path: string;           // File path (absolute or relative to project root)
  lines?: string;         // Line range: "10-50", "1-20,45-60", or omit for entire file
  reason?: string;        // Why this file/section is relevant (max 200 chars)
}

// Contract definition
interface Contract {
  type: 'api' | 'interface' | 'event' | 'schema';
  name: string;           // Contract identifier (e.g., "UserAPI", "AuthEvent")
  path?: string;          // File path where contract is defined
  status: 'draft' | 'defined' | 'implemented' | 'verified';
  description?: string;   // Brief description (max 200 chars)
}

// Design component reference
interface DesignComponent {
  type: 'figma' | 'wireframe' | 'mockup' | 'prototype' | 'sketch';
  url?: string;           // External URL (Figma, etc.)
  path?: string;          // Local file path
  description?: string;   // What this design covers (max 200 chars)
}

// ADR reference
interface ADRReference {
  id: string;             // ADR identifier (e.g., "ADR-001", "auth-strategy")
  path?: string;          // File path to ADR document
  title?: string;         // ADR title
  decision?: string;      // Brief summary of decision (max 200 chars)
}

// RICE prioritization
interface RICEScore {
  reach: number;          // How many users affected (per time period)
  impact: number;         // Impact score (0.25 = minimal, 0.5 = low, 1 = medium, 2 = high, 3 = massive)
  confidence: number;     // Confidence % (0-100)
  effort: number;         // Person-months of work
  score?: number;         // Calculated: (reach * impact * confidence) / effort
}

// WSJF prioritization
interface WSJFScore {
  business_value: number;     // 1-10 scale
  time_criticality: number;   // 1-10 scale
  risk_reduction: number;     // 1-10 scale
  job_size: number;           // 1-10 scale (effort estimate)
  score?: number;             // Calculated: (business_value + time_criticality + risk_reduction) / job_size
}

// Enhanced task.json
interface EnhancedTask {
  // Base fields (from task-schema.md)
  id: string;
  name: string;
  status: 'active' | 'completed' | 'blocked' | 'archived';
  objective: string;
  context_files?: (string | ContextFileReference)[];
  reference_files?: (string | ContextFileReference)[];
  exit_criteria?: string[];
  subtask_count?: number;
  completed_count?: number;
  created_at: string;
  completed_at?: string;

  // Enhanced fields
  bounded_context?: string;
  module?: string;
  vertical_slice?: string;
  contracts?: Contract[];
  design_components?: DesignComponent[];
  related_adrs?: ADRReference[];
  rice_score?: RICEScore;
  wsjf_score?: WSJFScore;
  release_slice?: string;
}

// Enhanced subtask_NN.json
interface EnhancedSubtask {
  // Base fields (from task-schema.md)
  id: string;
  seq: string;
  title: string;
  status: 'pending' | 'in_progress' | 'completed' | 'blocked';
  depends_on?: string[];
  parallel?: boolean;
  context_files?: (string | ContextFileReference)[];
  reference_files?: (string | ContextFileReference)[];
  suggested_agent?: string;
  acceptance_criteria?: string[];
  deliverables?: string[];
  agent_id?: string;
  started_at?: string;
  completed_at?: string;
  completion_summary?: string;

  // Enhanced fields
  bounded_context?: string;
  module?: string;
  vertical_slice?: string;
  contracts?: Contract[];
  design_components?: DesignComponent[];
  related_adrs?: ADRReference[];
}

Field Examples

bounded_context

Purpose: DDD bounded context for domain modeling

{
  "bounded_context": "authentication"
}

Common values:

"authentication" - User identity and access
"billing" - Payment and invoicing
"inventory" - Product and stock management
"notification" - Messaging and alerts
"analytics" - Reporting and insights

module

Purpose: Module or package name for code organization

{
  "module": "@app/auth"
}

Examples:

"@app/auth" - Authentication module
"payment-service" - Payment microservice
"ui-components" - Shared UI library
"core/utils" - Core utilities

vertical_slice

Purpose: Feature slice identifier for vertical slice architecture

{
  "vertical_slice": "user-registration"
}

Examples:

"user-registration" - Complete user signup flow
"checkout-flow" - End-to-end checkout
"dashboard-overview" - Dashboard feature
"report-generation" - Report creation flow

contracts

Purpose: Track API/interface dependencies and implementations

{
  "contracts": [
    {
      "type": "api",
      "name": "UserAPI",
      "path": "src/api/user.contract.ts",
      "status": "defined",
      "description": "REST API for user CRUD operations"
    },
    {
      "type": "event",
      "name": "UserCreatedEvent",
      "status": "draft",
      "description": "Event emitted when new user is created"
    }
  ]
}

Contract types:

"api" - REST/GraphQL API endpoints
"interface" - TypeScript/language interfaces
"event" - Event bus messages
"schema" - Database schemas, validation schemas

Contract statuses:

"draft" - Being designed
"defined" - Specification complete
"implemented" - Code written
"verified" - Tests passing

design_components

Purpose: Link design artifacts to implementation tasks

{
  "design_components": [
    {
      "type": "figma",
      "url": "https://figma.com/file/abc123/Login-Flow",
      "description": "Login page mockups with responsive breakpoints"
    },
    {
      "type": "wireframe",
      "path": "docs/design/checkout-wireframe.png",
      "description": "Checkout flow wireframe"
    }
  ]
}

Component types:

"figma" - Figma designs
"wireframe" - Low-fidelity wireframes
"mockup" - High-fidelity mockups
"prototype" - Interactive prototypes
"sketch" - Sketch files

related_adrs

Purpose: Reference architectural decisions that govern implementation

{
  "related_adrs": [
    {
      "id": "ADR-003",
      "path": "docs/adr/003-jwt-authentication.md",
      "title": "Use JWT for stateless authentication",
      "decision": "Implement JWT with RS256 signing and 15-minute expiry"
    },
    {
      "id": "ADR-007",
      "path": "docs/adr/007-database-choice.md",
      "title": "PostgreSQL for primary database"
    }
  ]
}

rice_score

Purpose: RICE prioritization framework (Reach × Impact × Confidence / Effort)

{
  "rice_score": {
    "reach": 5000,
    "impact": 2,
    "confidence": 80,
    "effort": 3,
    "score": 2666.67
  }
}

Calculation: (5000 × 2 × 0.80) / 3 = 2666.67

Field definitions:

reach: Number of users/customers affected per time period (e.g., per quarter)
impact: 0.25 (minimal), 0.5 (low), 1 (medium), 2 (high), 3 (massive)
confidence: Percentage (0-100) - how confident are you in reach/impact estimates?
effort: Person-months of work
score: Auto-calculated or manually entered

wsjf_score

Purpose: WSJF prioritization (Weighted Shortest Job First) for SAFe/Agile

{
  "wsjf_score": {
    "business_value": 8,
    "time_criticality": 6,
    "risk_reduction": 5,
    "job_size": 3,
    "score": 6.33
  }
}

Calculation: (8 + 6 + 5) / 3 = 6.33

Field definitions (all on 1-10 scale):

business_value: Direct business impact
time_criticality: How time-sensitive is this?
risk_reduction: Does this reduce risk/enable other work?
job_size: Effort estimate (1 = tiny, 10 = huge)
score: Auto-calculated or manually entered

release_slice

Purpose: Group tasks into releases for planning

{
  "release_slice": "v1.2.0"
}

Examples:

"v1.2.0" - Semantic version
"Q1-2026" - Quarterly release
"MVP" - Minimum viable product
"Phase-2" - Project phase
"Sprint-15" - Sprint identifier

Line-Number Precision Format

Purpose

Reduce cognitive load by pointing agents to exact sections of large files instead of forcing them to read entire documents.

Format

{
  "path": "path/to/file.md",
  "lines": "10-50",
  "reason": "Why these lines matter"
}

Line Range Syntax

"10-50" - Lines 10 through 50 (inclusive)
"1-20,45-60" - Lines 1-20 AND 45-60 (multiple ranges)
Omit lines field to read entire file

Examples

Single range:

{
  "path": ".opencode/context/core/standards/code-quality.md",
  "lines": "53-95",
  "reason": "Pure function and immutability patterns"
}

Multiple ranges:

{
  "path": ".opencode/context/core/standards/security-patterns.md",
  "lines": "1-25,120-145,200-220",
  "reason": "JWT validation rules and token refresh patterns"
}

Entire file (backward compatible):

{
  "path": ".opencode/context/core/standards/code-quality.md",
  "reason": "All coding standards"
}

Legacy string format (still supported):

".opencode/context/core/standards/code-quality.md"

Backward Compatibility Rules

Rule 1: All new fields are optional

Existing task.json and subtask_NN.json files remain valid without any changes.

Rule 2: Mixed formats allowed

You can mix old and new formats in the same file:

{
  "context_files": [
    ".opencode/context/core/standards/code-quality.md",
    {
      "path": ".opencode/context/core/standards/security-patterns.md",
      "lines": "120-145",
      "reason": "JWT validation"
    }
  ]
}

Rule 3: Agent handling

Agents MUST support both formats:

function loadContextFile(ref: string | ContextFileReference): string {
  if (typeof ref === 'string') {
    // Legacy format: read entire file
    return readFile(ref);
  } else {
    // New format: read specified lines
    const content = readFile(ref.path);
    if (ref.lines) {
      return extractLines(content, ref.lines);
    }
    return content;
  }
}

Rule 4: Gradual migration

Projects can adopt enhanced fields incrementally:

Start with line-number precision for large files
Add domain modeling fields (bounded_context, module) when needed
Add prioritization scores when planning releases
Add contracts/ADRs when formalizing architecture

Complete Example

Enhanced task.json

{
  "id": "user-authentication",
  "name": "User Authentication System",
  "status": "active",
  "objective": "Implement JWT-based authentication with refresh tokens and role-based access control",
  "context_files": [
    {
      "path": ".opencode/context/core/standards/code-quality.md",
      "lines": "53-95",
      "reason": "Pure function patterns for auth service"
    },
    {
      "path": ".opencode/context/core/standards/security-patterns.md",
      "lines": "120-145,200-220",
      "reason": "JWT validation and token refresh patterns"
    }
  ],
  "reference_files": [
    {
      "path": "src/middleware/auth.middleware.ts",
      "lines": "1-50",
      "reason": "Existing auth middleware to extend"
    },
    "package.json"
  ],
  "exit_criteria": [
    "All tests passing with >90% coverage",
    "JWT tokens signed with RS256",
    "Refresh token rotation implemented",
    "Role-based access control working"
  ],
  "subtask_count": 5,
  "completed_count": 0,
  "created_at": "2026-02-14T10:00:00Z",
  "bounded_context": "authentication",
  "module": "@app/auth",
  "vertical_slice": "user-login",
  "contracts": [
    {
      "type": "api",
      "name": "AuthAPI",
      "path": "src/api/auth.contract.ts",
      "status": "defined",
      "description": "REST endpoints for login, logout, refresh, verify"
    },
    {
      "type": "event",
      "name": "UserAuthenticatedEvent",
      "status": "draft",
      "description": "Event emitted on successful authentication"
    }
  ],
  "design_components": [
    {
      "type": "figma",
      "url": "https://figma.com/file/xyz789/Auth-Flows",
      "description": "Login and registration UI mockups"
    }
  ],
  "related_adrs": [
    {
      "id": "ADR-003",
      "path": "docs/adr/003-jwt-authentication.md",
      "title": "Use JWT for stateless authentication",
      "decision": "JWT with RS256, 15-min access tokens, 7-day refresh tokens"
    }
  ],
  "rice_score": {
    "reach": 10000,
    "impact": 3,
    "confidence": 90,
    "effort": 4,
    "score": 6750
  },
  "wsjf_score": {
    "business_value": 9,
    "time_criticality": 8,
    "risk_reduction": 7,
    "job_size": 4,
    "score": 6
  },
  "release_slice": "v1.0.0"
}

Enhanced subtask_NN.json

{
  "id": "user-authentication-02",
  "seq": "02",
  "title": "Implement JWT service with token generation and validation",
  "status": "pending",
  "depends_on": ["01"],
  "parallel": false,
  "context_files": [
    {
      "path": ".opencode/context/core/standards/code-quality.md",
      "lines": "53-72",
      "reason": "Pure function patterns"
    },
    {
      "path": ".opencode/context/core/standards/security-patterns.md",
      "lines": "120-145",
      "reason": "JWT signing and validation rules"
    }
  ],
  "reference_files": [
    {
      "path": "src/config/jwt.config.ts",
      "reason": "JWT configuration constants"
    }
  ],
  "suggested_agent": "CoderAgent",
  "acceptance_criteria": [
    "JWT tokens signed with RS256 algorithm",
    "Access tokens expire in 15 minutes",
    "Refresh tokens expire in 7 days",
    "Token validation includes signature and expiry checks",
    "Unit tests cover all token operations",
    "No secrets hardcoded in code"
  ],
  "deliverables": [
    "src/auth/jwt.service.ts",
    "src/auth/jwt.service.test.ts"
  ],
  "bounded_context": "authentication",
  "module": "@app/auth",
  "contracts": [
    {
      "type": "interface",
      "name": "JWTService",
      "path": "src/auth/jwt.service.ts",
      "status": "implemented",
      "description": "Interface for JWT operations (sign, verify, refresh)"
    }
  ],
  "related_adrs": [
    {
      "id": "ADR-003",
      "path": "docs/adr/003-jwt-authentication.md"
    }
  ]
}

Migration Guide

For TaskManager Agents

When creating new tasks:

Use line-number precision for large files (>100 lines):

{
 "path": ".opencode/context/core/standards/code-quality.md",
 "lines": "53-95",
 "reason": "Pure function patterns"
}

Add domain modeling fields when known:

{
 "bounded_context": "authentication",
 "module": "@app/auth",
 "vertical_slice": "user-login"
}

Link design artifacts for UI tasks:

{
 "design_components": [
   {
     "type": "figma",
     "url": "https://figma.com/...",
     "description": "Login page mockups"
   }
 ]
}

Reference ADRs for architectural decisions:

{
 "related_adrs": [
   {
     "id": "ADR-003",
     "path": "docs/adr/003-jwt-authentication.md"
   }
 ]
}

For Working Agents (CoderAgent, etc.)

When reading tasks:

Handle both context file formats:

const contextFiles = task.context_files || [];
for (const ref of contextFiles) {
 if (typeof ref === 'string') {
   // Read entire file
   const content = await readFile(ref);
 } else {
   // Read specified lines
   const content = await readFileLines(ref.path, ref.lines);
   console.log(`Reading ${ref.path} (${ref.lines}): ${ref.reason}`);
 }
}

Use contract information to understand dependencies:

const contracts = task.contracts || [];
const apiContracts = contracts.filter(c => c.type === 'api');
// Load API contract definitions before implementing

Check ADRs before making architectural decisions:

const adrs = task.related_adrs || [];
for (const adr of adrs) {
 if (adr.path) {
   const decision = await readFile(adr.path);
   // Apply architectural constraints from ADR
 }
}

task-schema.md - Base schema (backward compatible foundation)
../guides/splitting-tasks.md - How to decompose features
../guides/managing-tasks.md - Lifecycle workflow
../lookup/task-commands.md - CLI reference

enhanced-task-schema.md 19 KB

Permalink History Raw

Enhanced Task JSON Schema

Overview

Enhanced task.json Schema

New Fields

Enhanced context_files and reference_files Format

Enhanced subtask_NN.json Schema

New Fields

TypeScript Interfaces

Field Examples

bounded_context

module

vertical_slice

contracts

design_components

related_adrs

rice_score

wsjf_score

release_slice

Line-Number Precision Format

Purpose

Format

Line Range Syntax

Examples

Backward Compatibility Rules

Rule 1: All new fields are optional

Rule 2: Mixed formats allowed

Rule 3: Agent handling

Rule 4: Gradual migration

Complete Example

Enhanced task.json

Enhanced subtask_NN.json

Migration Guide

For TaskManager Agents

For Working Agents (CoderAgent, etc.)

Related

enhanced-task-schema.md 19 KB Permalink History Raw

Enhanced Task JSON Schema

Overview

Enhanced task.json Schema

New Fields

Enhanced context_files and reference_files Format

Enhanced subtask_NN.json Schema

New Fields

TypeScript Interfaces

Field Examples

bounded_context

module

vertical_slice

contracts

design_components

related_adrs

rice_score

wsjf_score

release_slice

Line-Number Precision Format

Purpose

Format

Line Range Syntax

Examples

Backward Compatibility Rules

Rule 1: All new fields are optional

Rule 2: Mixed formats allowed

Rule 3: Agent handling

Rule 4: Gradual migration

Complete Example

Enhanced task.json

Enhanced subtask_NN.json

Migration Guide

For TaskManager Agents

For Working Agents (CoderAgent, etc.)

Related

enhanced-task-schema.md 19 KB

Permalink History Raw