Planning Implementation

Overview

Before Planning Begins

1. Get existing state: Run

   dark-factory list --job $JOB --status pending --include-content

   to see outstanding tasks already in the graph
2. Explore the codebase: Dispatch background explore agents to review files relevant to each section of the document — understand existing patterns, types, and integration points before writing tasks
3. Research dependencies: Use web search to research any libraries, frameworks, or tools referenced in the architecture that you're unfamiliar with

Output Schema

{
  "project": "<project name>",
  "tasks": [
    {
      "id": "T001",
      "title": "Short task title",
      "description": "Detailed description of what to implement",
      "dependencies": ["T000"],
      "files": ["src/path/to/file.ts"],
      "acceptance_criteria": "Specific, verifiable criteria",
      "verification_steps": ["cargo build", "bun test"],
      "context_files": ["specs/ARCHITECTURE.md"],
      "estimated_complexity": "low|medium|high",
      "implementation_details": "Markdown with ### headers"
    }
  ]
}

• Sequential IDs: T001, T002, ...
• Dependencies must reference valid task IDs within the list
• Extract EVERY task mentioned in the document — do not skip or merge

Task Sizing

Field Guide

dependencies

• Organize for maximum parallelism — only add a dependency when a task literally cannot be worked on, or its acceptance criteria cannot be verified, until the dependency completes
• Avoid unnecessary serial chains

files

context_files

implementation_details

acceptance_criteria

• Enumerate all cases that need automated tests, including edge cases not mentioned in the architecture docs
• If automated tests aren't possible, describe steps an agent can perform to verify the work
• Be specific about what behaviour must be proven
• Include specific test fixtures and validation cases

verification_steps

bun test

cargo build

bun run typecheck

implementation_details

• Inline specific sections, patterns, and code examples from the architecture doc(s)
• Include: function signatures, struct/type definitions, trait impls, API shapes
• Include: integration points — existing modules/functions this code must connect to
• Include: edge cases, error handling requirements, known gotchas
• Include: example code snippets showing expected patterns when the docs provide them
• Format with markdown headers:

  ### Pattern

  ,

  ### Integration Points

  ,

  ### Edge Cases

• Self-contained — workers see ONLY their task, not the full architecture

Validation