OpenWriterControle/.opencode/docs/guides/task-schema-migration.md

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

1. Phase 1: Add line-number precision to large context files
2. Phase 2: Add domain modeling fields (bounded_context, module)
3. Phase 3: Add contracts and ADR references
4. 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?

A:

1. Read the file manually
2. Use grep -n to find relevant sections
3. Use the migration script's --dry-run mode to preview
4. 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.

---

Related Documentation

• Base Schema: .opencode/context/core/task-management/standards/task-schema.md
• Enhanced Schema: .opencode/context/core/task-management/standards/enhanced-task-schema.md
• Task Splitting Guide: .opencode/context/core/task-management/guides/splitting-tasks.md
• Task Management Guide: .opencode/context/core/task-management/guides/managing-tasks.md
• CLI Reference: .opencode/context/core/task-management/lookup/task-commands.md

---

Support

For issues or questions:

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