Task Schema Migration Guide

Purpose: Step-by-step guide for migrating from base task schema to enhanced task schema

Version: 1.0

Last Updated: 2026-02-14

Overview

This guide helps you migrate existing task.json and subtask_NN.json files from the base schema to the enhanced schema with line-number precision, domain modeling, and prioritization features.

Key Points:

✅ 100% backward compatible - No breaking changes
✅ Gradual migration - Adopt features incrementally
✅ Mixed formats - Old and new formats work together
✅ Optional enhancements - Use only what you need

Quick Start

Do I Need to Migrate?

No migration required if:

Your tasks are simple and working well
You don't need line-number precision for large files
You're not doing domain modeling or release planning

Consider migrating if:

Context files are large (>100 lines) and agents read unnecessary sections
You need domain modeling (bounded contexts, modules, vertical slices)
You're tracking API contracts or architectural decisions
You need prioritization (RICE/WSJF scores)
You're planning releases and need to group tasks

Migration Strategy

Recommended approach: Start small, expand gradually

Phase 1: Add line-number precision to large context files
Phase 2: Add domain modeling fields (bounded_context, module)
Phase 3: Add contracts and ADR references
Phase 4: Add prioritization scores for release planning

Field-by-Field Mapping

Base Schema → Enhanced Schema

Base Field	Enhanced Field	Change	Notes
`context_files`	`context_files`	Format change	String → Object with line ranges
`reference_files`	`reference_files`	Format change	String → Object with line ranges
-	`bounded_context`	New (optional)	DDD bounded context
-	`module`	New (optional)	Module/package name
-	`vertical_slice`	New (optional)	Feature slice identifier
-	`contracts`	New (optional)	API/interface contracts
-	`design_components`	New (optional)	Figma/wireframe links
-	`related_adrs`	New (optional)	Architecture Decision Records
-	`rice_score`	New (optional)	RICE prioritization
-	`wsjf_score`	New (optional)	WSJF prioritization
-	`release_slice`	New (optional)	Release identifier

All other fields remain unchanged.

Migration Examples

Example 1: Basic Migration (Line-Number Precision)

Before (base schema):

{
  "id": "auth-system-02",
  "seq": "02",
  "title": "Create JWT service",
  "status": "pending",
  "depends_on": ["01"],
  "parallel": false,
  "context_files": [
    ".opencode/context/core/standards/code-quality.md",
    ".opencode/context/core/standards/security-patterns.md"
  ],
  "reference_files": [
    "src/auth/token-utils.ts"
  ],
  "acceptance_criteria": [
    "JWT tokens signed with RS256",
    "Tests pass"
  ],
  "deliverables": [
    "src/auth/jwt.service.ts"
  ]
}

After (enhanced schema with line-number precision):

{
  "id": "auth-system-02",
  "seq": "02",
  "title": "Create JWT service",
  "status": "pending",
  "depends_on": ["01"],
  "parallel": false,
  "context_files": [
    {
      "path": ".opencode/context/core/standards/code-quality.md",
      "lines": "53-72",
      "reason": "Pure function patterns for service layer"
    },
    {
      "path": ".opencode/context/core/standards/security-patterns.md",
      "lines": "120-145",
      "reason": "JWT signing and validation rules"
    }
  ],
  "reference_files": [
    {
      "path": "src/auth/token-utils.ts",
      "lines": "1-50",
      "reason": "Existing token utility functions to extend"
    }
  ],
  "acceptance_criteria": [
    "JWT tokens signed with RS256",
    "Tests pass"
  ],
  "deliverables": [
    "src/auth/jwt.service.ts"
  ]
}

Benefits:

Agents read only relevant sections (53-72, 120-145) instead of entire files
Reduced cognitive load and faster context loading
Clear reasoning for why each file section is needed

Example 2: Adding Domain Modeling

Before (base schema):

{
  "id": "user-authentication",
  "name": "User Authentication System",
  "status": "active",
  "objective": "Implement JWT-based authentication",
  "context_files": [
    ".opencode/context/core/standards/code-quality.md"
  ],
  "exit_criteria": [
    "All tests passing"
  ],
  "subtask_count": 5,
  "completed_count": 0,
  "created_at": "2026-02-14T10:00:00Z"
}

After (enhanced schema with domain modeling):

{
  "id": "user-authentication",
  "name": "User Authentication System",
  "status": "active",
  "objective": "Implement JWT-based authentication",
  "context_files": [
    {
      "path": ".opencode/context/core/standards/code-quality.md",
      "lines": "53-95",
      "reason": "Pure function patterns"
    }
  ],
  "exit_criteria": [
    "All tests passing"
  ],
  "subtask_count": 5,
  "completed_count": 0,
  "created_at": "2026-02-14T10:00:00Z",
  "bounded_context": "authentication",
  "module": "@app/auth",
  "vertical_slice": "user-login"
}

Benefits:

Clear domain boundaries (bounded_context)
Module organization (module)
Feature slice tracking (vertical_slice)
Better architecture visibility

Example 3: Adding Contracts and ADRs

Before (base schema):

{
  "id": "auth-system-03",
  "seq": "03",
  "title": "Implement auth API endpoints",
  "status": "pending",
  "depends_on": ["02"],
  "acceptance_criteria": [
    "POST /auth/login works",
    "POST /auth/refresh works"
  ],
  "deliverables": [
    "src/api/auth.controller.ts"
  ]
}

After (enhanced schema with contracts and ADRs):

{
  "id": "auth-system-03",
  "seq": "03",
  "title": "Implement auth API endpoints",
  "status": "pending",
  "depends_on": ["02"],
  "acceptance_criteria": [
    "POST /auth/login works",
    "POST /auth/refresh works"
  ],
  "deliverables": [
    "src/api/auth.controller.ts"
  ],
  "contracts": [
    {
      "type": "api",
      "name": "AuthAPI",
      "path": "src/api/auth.contract.ts",
      "status": "defined",
      "description": "REST endpoints for login, logout, refresh"
    }
  ],
  "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"
    }
  ]
}

Benefits:

Contract tracking ensures API consistency
ADR references document architectural decisions
Clear dependencies on interface definitions

Example 4: Adding Prioritization

Before (base schema):

{
  "id": "user-dashboard",
  "name": "User Dashboard",
  "status": "active",
  "objective": "Build user dashboard with analytics",
  "subtask_count": 8,
  "completed_count": 0,
  "created_at": "2026-02-14T10:00:00Z"
}

After (enhanced schema with prioritization):

{
  "id": "user-dashboard",
  "name": "User Dashboard",
  "status": "active",
  "objective": "Build user dashboard with analytics",
  "subtask_count": 8,
  "completed_count": 0,
  "created_at": "2026-02-14T10:00:00Z",
  "rice_score": {
    "reach": 5000,
    "impact": 2,
    "confidence": 80,
    "effort": 3,
    "score": 2666.67
  },
  "wsjf_score": {
    "business_value": 8,
    "time_criticality": 6,
    "risk_reduction": 5,
    "job_size": 3,
    "score": 6.33
  },
  "release_slice": "v1.2.0"
}

Benefits:

RICE score helps prioritize features
WSJF score for SAFe/Agile planning
Release grouping for roadmap planning

When to Use Enhanced Fields

Line-Number Precision (`lines` field)

Use when:

Context file is >100 lines
Only specific sections are relevant
You want to reduce agent cognitive load

Example:

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

Don't use when:

File is small (<50 lines)
Entire file is relevant
You're unsure which sections matter (use entire file first, refine later)

Domain Modeling Fields

Use bounded_context when:

You're doing Domain-Driven Design (DDD)
You have clear domain boundaries (auth, billing, inventory)
You want to track which domain each task belongs to

Use module when:

You have a modular architecture
You're using monorepo with packages
You want to track which module/package is affected

Use vertical_slice when:

You're using vertical slice architecture
You want to track end-to-end features
You need to group tasks by user-facing feature

Example:

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

Contracts

Use when:

You're defining or implementing APIs
You have interface contracts between modules
You're using event-driven architecture
You need to track schema definitions

Example:

{
  "contracts": [
    {
      "type": "api",
      "name": "UserAPI",
      "path": "src/api/user.contract.ts",
      "status": "defined",
      "description": "REST API for user CRUD"
    }
  ]
}

Design Components

Use when:

Task involves UI implementation
You have Figma designs or wireframes
You need to link mockups to implementation

Example:

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

ADR References

Use when:

Task implements an architectural decision
You have ADR documents
You want to link decisions to implementation

Example:

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

Prioritization Scores

Use RICE when:

You need to prioritize features by impact
You're doing product planning
You want data-driven prioritization

Use WSJF when:

You're using SAFe or Agile at scale
You need weighted prioritization
You're optimizing for shortest job first

Use release_slice when:

You're planning releases
You need to group tasks by version/sprint
You're doing roadmap planning

Migration Script

Use the provided migration script to automatically upgrade task files:

# Migrate a single task
npx ts-node .opencode/skill/task-management/scripts/migrate-schema.ts \
  --task multi-stage-orchestration-workflow

# Migrate all tasks
npx ts-node .opencode/skill/task-management/scripts/migrate-schema.ts --all

# Dry run (preview changes without writing)
npx ts-node .opencode/skill/task-management/scripts/migrate-schema.ts \
  --task auth-system --dry-run

# Add line-number precision only
npx ts-node .opencode/skill/task-management/scripts/migrate-schema.ts \
  --task auth-system --lines-only

# Add domain modeling fields
npx ts-node .opencode/skill/task-management/scripts/migrate-schema.ts \
  --task auth-system --add-domain \
  --bounded-context authentication \
  --module @app/auth

Script Options

Option	Description
`--task <name>`	Migrate specific task
`--all`	Migrate all tasks in .tmp/tasks/
`--dry-run`	Preview changes without writing
`--lines-only`	Add line-number precision only
`--add-domain`	Add domain modeling fields
`--bounded-context <name>`	Set bounded_context
`--module <name>`	Set module
`--vertical-slice <name>`	Set vertical_slice
`--release <name>`	Set release_slice

Backward Compatibility Guarantees

1. Old Format Still Works

Guarantee: All existing task.json and subtask_NN.json files work without modification.

Example:

// This still works perfectly
"context_files": [
  ".opencode/context/core/standards/code-quality.md"
]

2. Mixed Formats Allowed

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

Example:

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

3. All New Fields Optional

Guarantee: No new fields are required. Add them only when needed.

4. Agent Compatibility

Guarantee: All agents handle both old and new formats automatically.

Implementation:

function loadContextFile(ref: string | ContextFileReference): string {
  if (typeof ref === 'string') {
    // Old 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;
  }
}

Common Migration Pitfalls

Pitfall 1: Breaking String Format

Wrong ❌:

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

Right ✅:

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

Fix: Use path field, not bare string in object.

Pitfall 2: Invalid Line Ranges

Wrong ❌:

{
  "lines": "10-5"  // End before start
}

Wrong ❌:

{
  "lines": "abc-def"  // Non-numeric
}

Right ✅:

{
  "lines": "10-50"  // Valid range
}

Right ✅:

{
  "lines": "1-20,45-60"  // Multiple ranges
}

Fix: Use format "start-end" or "start1-end1,start2-end2" with valid numbers.

Pitfall 3: Mixing Standards and Source Files

Wrong ❌:

"context_files": [
  ".opencode/context/core/standards/code-quality.md",
  "src/auth/service.ts"  // Source file in context_files!
]

Right ✅:

"context_files": [
  ".opencode/context/core/standards/code-quality.md"
],
"reference_files": [
  "src/auth/service.ts"
]

Fix: Standards go in context_files, source code goes in reference_files.

Pitfall 4: Forgetting `path` Field

Wrong ❌:

{
  "lines": "10-50",
  "reason": "Pure functions"
  // Missing path!
}

Right ✅:

{
  "path": ".opencode/context/core/standards/code-quality.md",
  "lines": "10-50",
  "reason": "Pure functions"
}

Fix: Always include path field in object format.

Pitfall 5: Over-Engineering Simple Tasks

Wrong ❌:

{
  "id": "simple-task-01",
  "title": "Fix typo in README",
  "context_files": [
    {
      "path": ".opencode/context/core/standards/code-quality.md",
      "lines": "1-165",
      "reason": "All standards"
    }
  ],
  "bounded_context": "documentation",
  "module": "@app/docs",
  "rice_score": { "reach": 1, "impact": 0.25, "confidence": 100, "effort": 0.1 }
}

Right ✅:

{
  "id": "simple-task-01",
  "title": "Fix typo in README",
  "deliverables": ["README.md"]
}

Fix: Don't add enhanced fields to simple tasks. Use them only when they add value.

Integration with Existing Workflows

TaskManager Agent

No changes required. TaskManager can create tasks in either format.

Recommendation: Use enhanced format for new tasks, especially:

Line-number precision for large context files
Domain modeling for architecture visibility
Contracts for API-driven development

CoderAgent

No changes required. CoderAgent handles both formats automatically.

Behavior:

String format → reads entire file
Object format → reads specified lines only
Logs line ranges and reasons for transparency

Task CLI

No changes required. All CLI commands work with both formats.

Commands:

# Works with both old and new formats
npx ts-node .opencode/skill/task-management/scripts/task-cli.ts status
npx ts-node .opencode/skill/task-management/scripts/task-cli.ts next auth-system
npx ts-node .opencode/skill/task-management/scripts/task-cli.ts validate auth-system

Orchestrator

No changes required. Orchestrator reads both formats.

Benefit: Enhanced fields (contracts, ADRs) provide better context for orchestration decisions.

Migration Checklist

Phase 1: Line-Number Precision

Identify large context files (>100 lines)
Determine relevant line ranges for each task
Add lines and reason fields
Test with CoderAgent to verify correct sections loaded
Update reference_files with line ranges if needed

Phase 2: Domain Modeling

Define bounded contexts for your project
Map tasks to bounded contexts
Add bounded_context field to task.json files
Add module field if using modular architecture
Add vertical_slice field if using vertical slices

Phase 3: Contracts and ADRs

Identify API contracts in your project
Add contracts field to relevant tasks
Link ADR documents to tasks
Add related_adrs field with ADR references
Update contract status as implementation progresses

Phase 4: Prioritization

Calculate RICE scores for features
Add rice_score to task.json files
Calculate WSJF scores if using SAFe
Add wsjf_score to task.json files
Group tasks by release using release_slice

Phase 5: Validation

Run migration script with --dry-run
Review generated changes
Run task-cli.ts validate on migrated tasks
Test with CoderAgent on sample tasks
Verify backward compatibility with old tasks

FAQ

Q: Do I have to migrate all tasks at once?

A: No. You can migrate incrementally. Old and new formats work together.

Q: Will old tasks break after migration?

A: No. All old tasks continue to work without modification.

Q: Can I mix old and new formats in the same file?

A: Yes. You can have some context_files as strings and others as objects.

Q: What if I don't know the line ranges?

A: Use the old string format first. Refine to line ranges later when you know which sections matter.

Q: Do I need to add all enhanced fields?

A: No. Add only the fields that provide value for your use case.

Q: How do I find the right line ranges?

Read the file manually
Use grep -n to find relevant sections
Use the migration script's --dry-run mode to preview
Refine based on agent feedback

Q: What if line numbers change when files are updated?

A: Update line ranges when you update the referenced files. Consider using section headers instead of line numbers for more stable references (future enhancement).

Q: Can I use the enhanced schema for new projects?

A: Yes. Start with enhanced schema from day one if you know you'll need the features.

Q: Is there a performance benefit to line-number precision?

A: Yes. Agents load less content, reducing token usage and processing time.

Q: How do I validate migrated tasks?

A: Use task-cli.ts validate <feature> to check JSON structure and dependencies.

Support

For issues or questions:

Check this migration guide
Review enhanced-task-schema.md for field definitions
Run migration script with --dry-run to preview changes
Test with small tasks first before migrating large features

task-schema-migration.md 20 KB Постоянная ссылка История Исходник

Task Schema Migration Guide

Overview

Quick Start

Do I Need to Migrate?

Migration Strategy

Field-by-Field Mapping

Base Schema → Enhanced Schema

Migration Examples

Example 1: Basic Migration (Line-Number Precision)

Example 2: Adding Domain Modeling

Example 3: Adding Contracts and ADRs

Example 4: Adding Prioritization

When to Use Enhanced Fields

Line-Number Precision (lines field)

Domain Modeling Fields

Contracts

Design Components

ADR References

Prioritization Scores

Migration Script

Script Options

Backward Compatibility Guarantees

1. Old Format Still Works

2. Mixed Formats Allowed

3. All New Fields Optional

4. Agent Compatibility

Common Migration Pitfalls

Pitfall 1: Breaking String Format

Pitfall 2: Invalid Line Ranges

Pitfall 3: Mixing Standards and Source Files

Pitfall 4: Forgetting path Field

Pitfall 5: Over-Engineering Simple Tasks

Integration with Existing Workflows

TaskManager Agent

CoderAgent

Task CLI

Orchestrator

Migration Checklist

Phase 1: Line-Number Precision

Phase 2: Domain Modeling

Phase 3: Contracts and ADRs

Phase 4: Prioritization

Phase 5: Validation

FAQ

Q: Do I have to migrate all tasks at once?

Q: Will old tasks break after migration?

Q: Can I mix old and new formats in the same file?

Q: What if I don't know the line ranges?

Q: Do I need to add all enhanced fields?

Q: How do I find the right line ranges?

Q: What if line numbers change when files are updated?

Q: Can I use the enhanced schema for new projects?

Q: Is there a performance benefit to line-number precision?

Q: How do I validate migrated tasks?

Related Documentation

Support

task-schema-migration.md 20 KB

Постоянная ссылка История Исходник

Line-Number Precision (`lines` field)

Pitfall 4: Forgetting `path` Field