tasks.json

{
  "project": {
    "name": "agent-orchestrator",
    "description": "Lightweight two-part system for autonomous software development. An LLM planner organizes work from project management tools, and a deterministic state machine executes that work by dispatching headless coding agents through YAML-defined workflows.",
    "language": "TypeScript",
    "runtime": "Node.js",
    "rootDir": "."
  },
  "sharedContext": {
    "conventions": [
      "Use Zod for all schema validation and type inference (z.infer<typeof Schema>)",
      "Use named exports, not default exports",
      "Use async/await throughout, no callbacks",
      "Use path.resolve and path.join for all file paths",
      "Use fs/promises (not sync fs) for all file I/O",
      "Error handling: throw typed errors, let callers decide recovery",
      "Use console-level logging via the logger utility, not raw console.log",
      "All config paths are relative to the orchestrator repo root and resolved at load time",
      "Template variables use {{variable}} syntax (Nunjucks)",
      "State files are the contract between planner and runner — planner writes, runner reads/updates"
    ],
    "coreTypes": {
      "note": "These are the canonical type shapes all modules must conform to. Task 02 (core-types) produces the Zod schemas. Other tasks should code against these shapes.",
      "OrchestratorConfig": {
        "defaultAgent": "string",
        "agents": "Record<string, { command: string, defaultArgs: string[] }>",
        "stateDir": "string",
        "logDir": "string",
        "workflowDir": "string",
        "promptDir": "string",
        "scriptDir": "string",
        "pollInterval": "number (seconds, default 10)",
        "maxConcurrency": "number (default 3)",
        "ghCommand": "string (default 'gh')"
      },
      "PlanFile": {
        "id": "string (slug, matches directory name)",
        "name": "string",
        "createdAt": "string (ISO 8601)",
        "createdBy": "string",
        "repo": "string (absolute path to target repo)",
        "workflow": "string (workflow name from registry)",
        "agent": "string | null (agent provider name)",
        "worktreeRoot": "string (absolute path)",
        "status": "'active' | 'paused' | 'complete'",
        "tickets": "Array<{ ticketId: string, order: number, blockedBy: string[] }>"
      },
      "TicketState": {
        "planId": "string",
        "ticketId": "string",
        "title": "string",
        "description": "string",
        "acceptanceCriteria": "string[]",
        "linearUrl": "string | null",
        "repo": "string (absolute path, overrides plan)",
        "workflow": "string (overrides plan)",
        "branch": "string",
        "worktree": "string (absolute path)",
        "agent": "string | null (overrides plan)",
        "status": "'queued' | 'ready' | 'running' | 'paused' | 'complete' | 'failed' | 'needs_attention'",
        "currentPhase": "string (phase ID from workflow)",
        "phaseHistory": "Array<{ phase: string, status: string, startedAt: string, completedAt: string | null, output?: string }>",
        "context": "Record<string, string> (accumulated captured values)",
        "retries": "Record<string, number> (phase ID → retry count)",
        "error": "string | null"
      },
      "WorkflowDefinition": {
        "name": "string",
        "description": "string",
        "phases": "PhaseDefinition[]"
      },
      "PhaseDefinition": {
        "id": "string",
        "type": "'script' | 'agent' | 'poll' | 'terminal'",
        "command?": "string (for script/poll phases)",
        "args?": "string[] (for script/poll, supports {{var}} interpolation)",
        "promptTemplate?": "string (for agent phases, filename in prompts/)",
        "allowedTools?": "string[] (for agent phases)",
        "maxTurns?": "number (for agent phases)",
        "maxRetries?": "number",
        "agent?": "string | null (phase-level agent override)",
        "intervalSeconds?": "number (for poll phases)",
        "timeoutSeconds?": "number (for poll phases)",
        "capture?": "Record<string, string> (key → shell command or 'stdout')",
        "notify?": "boolean (for terminal phases)",
        "onSuccess?": "string (next phase ID)",
        "onFailure?": "string (next phase ID, 'retry', or 'abort')"
      },
      "WorkflowRegistryEntry": {
        "name": "string",
        "file": "string",
        "description": "string",
        "tags": "string[]"
      }
    }
  },
  "verticalSlices": {
    "description": "Work is organized into vertical slices. Each slice delivers a runnable, testable piece of functionality end-to-end.",
    "slice1": {
      "name": "I can load config and read state files",
      "goal": "`orchestrator status` works — create state files by hand, CLI reads and displays them.",
      "tasks": [
        "03-config-loader",
        "04-state-manager",
        "05-logger",
        "06-cli-init-status"
      ],
      "testableOutcome": "Create state/test-plan/ with _plan.json and TICKET-1.json by hand. Run `orchestrator status` and see formatted output. Run `orchestrator init` and see directories created."
    },
    "slice2": {
      "name": "I can run a script phase",
      "goal": "The runner picks up a ticket, executes a script phase, and updates the state file.",
      "tasks": [
        "07-shell-util",
        "08-template-renderer",
        "09-workflow-loader",
        "10-minimal-workflow",
        "11-setup-worktree",
        "12-phase-executor-script",
        "13-runner-single-ticket",
        "14-cli-run"
      ],
      "testableOutcome": "Create a minimal workflow with a script phase. Create state files pointing to it. Run `orchestrator run test-plan TICKET-1` and see the phase execute, state file update, and phase history recorded."
    },
    "slice3": {
      "name": "I can run an agent phase",
      "goal": "A headless coding agent is invoked with a rendered prompt and its output is captured.",
      "tasks": [
        "15-agent-invoker",
        "16-phase-executor-agent",
        "17-implement-prompt",
        "18-standard-workflow"
      ],
      "testableOutcome": "Create a ticket pointing at a real repo. Run `orchestrator run test-plan TICKET-1`. Watch the agent get invoked, implement a feature, and see the state file progress through phases."
    },
    "slice4": {
      "name": "I can run the daemon loop",
      "goal": "The daemon scans plans, resolves dependencies, and processes tickets concurrently.",
      "tasks": [
        "19-runner-daemon",
        "20-cli-daemon-commands",
        "21-cleanup-worktree"
      ],
      "testableOutcome": "Create a plan with 3 tickets (2 independent, 1 blocked). Run `orchestrator daemon`. Watch it pick up the 2 ready tickets concurrently, complete them, unblock the third, and process it."
    },
    "slice5": {
      "name": "I can handle PR review cycles",
      "goal": "The full standard workflow works end-to-end including the PR review loop.",
      "tasks": [
        "22-phase-executor-poll",
        "23-pr-scripts",
        "24-remaining-prompts",
        "25-full-standard-workflow",
        "26-bugfix-workflow",
        "27-workflow-registry"
      ],
      "testableOutcome": "Run a ticket against a real repo, watch it create a PR, wait for review, address comments, and complete. Test the bugfix workflow variant."
    },
    "slice6": {
      "name": "Documentation & Skills",
      "goal": "The LLM planner can use skills to create plans from project management tools.",
      "tasks": [
        "28-planner-skill",
        "29-workflow-skill",
        "30-linear-provider-skill",
        "31-github-issues-provider-skill",
        "32-claude-md-update"
      ],
      "testableOutcome": "Point an interactive Claude Code session at the orchestrator repo, ask it to create a plan from GitHub Issues, and confirm it produces valid state files."
    }
  },
  "tasks": [
    {
      "id": "01-project-scaffolding",
      "name": "Project Scaffolding",
      "slice": 0,
      "description": "Set up the TypeScript project foundation.",
      "files": [
        "package.json",
        "tsconfig.json",
        ".gitignore",
        "orchestrator.yaml"
      ],
      "dependsOn": [],
      "priority": 0,
      "estimatedComplexity": "low",
      "prompt": "Already complete. See task-status.json."
    },
    {
      "id": "02-core-types",
      "name": "Zod Schemas & Types",
      "slice": 0,
      "description": "Define all Zod schemas and TypeScript types that form the contract between all modules.",
      "files": ["src/core/types.ts"],
      "dependsOn": ["01-project-scaffolding"],
      "priority": 0,
      "estimatedComplexity": "medium",
      "prompt": "Already complete. See task-status.json."
    },

    {
      "id": "03-config-loader",
      "name": "Config Loader",
      "slice": 1,
      "description": "Loads orchestrator.yaml, validates with Zod, resolves relative paths to absolute. Single source of runtime configuration.",
      "files": ["src/core/config.ts"],
      "dependsOn": ["02-core-types"],
      "priority": 1,
      "estimatedComplexity": "low",
      "prompt": "Create `src/core/config.ts` — loads and validates the orchestrator configuration.\n\nImports: OrchestratorConfigSchema and OrchestratorConfig from './types.ts'. Uses 'yaml' package to parse YAML.\n\nExport the following:\n\n1. **loadConfig(configPath?: string): Promise<OrchestratorConfig>**\n   - Default configPath: 'orchestrator.yaml' in current working directory\n   - Reads the YAML file, parses it, validates with OrchestratorConfigSchema\n   - Resolves all relative directory paths (stateDir, logDir, workflowDir, promptDir, scriptDir) to absolute paths based on the directory containing the config file\n   - Throws a clear error if file not found or validation fails\n   - Returns the validated config\n\n2. **resolveAgent(config: OrchestratorConfig, phaseAgent: string | null | undefined, ticketAgent: string | null | undefined, planAgent: string | null | undefined): { command: string, defaultArgs: string[] }**\n   - Implements the four-level agent priority chain: phase → ticket → plan → global default\n   - Takes the first non-null value in that chain, falls back to config.defaultAgent\n   - Looks up the resolved agent name in config.agents\n   - Throws if the resolved agent name is not found in config.agents\n   - Returns the AgentConfig (command + defaultArgs)\n\nKeep it simple. No caching, no file watching. Just load, validate, resolve."
    },
    {
      "id": "04-state-manager",
      "name": "State Manager",
      "slice": 1,
      "description": "Reads and writes plan and ticket state files from the state/ directory. Handles multi-plan scanning, dependency resolution, and status transitions.",
      "files": ["src/core/state.ts"],
      "dependsOn": ["02-core-types"],
      "priority": 1,
      "estimatedComplexity": "medium",
      "prompt": "Create `src/core/state.ts` — manages plan and ticket state files on disk.\n\nImports: PlanFile, PlanFileSchema, TicketState, TicketStateSchema from './types.ts'. Uses fs/promises and path.\n\nExport the following:\n\n1. **createStateManager(stateDir: string)** — factory that returns a StateManager. Creates stateDir if it doesn't exist.\n\n2. **StateManager** object with methods:\n\n   **Plan operations:**\n   - **listPlans(): Promise<PlanFile[]>** — Scans stateDir for subdirectories, reads _plan.json from each, validates with Zod, returns all valid plans. Skips directories without _plan.json.\n   - **getPlan(planId: string): Promise<PlanFile>** — Reads and validates state/{planId}/_plan.json. Throws if not found.\n   - **savePlan(plan: PlanFile): Promise<void>** — Writes _plan.json to state/{plan.id}/. Creates directory if needed.\n\n   **Ticket operations:**\n   - **listTickets(planId: string): Promise<TicketState[]>** — Reads all .json files in state/{planId}/ except _plan.json. Validates each with Zod.\n   - **getTicket(planId: string, ticketId: string): Promise<TicketState>** — Reads state/{planId}/{ticketId}.json. Throws if not found.\n   - **saveTicket(ticket: TicketState): Promise<void>** — Writes to state/{ticket.planId}/{ticket.ticketId}.json. Validates before writing.\n   - **updateTicket(planId: string, ticketId: string, updates: Partial<TicketState>): Promise<TicketState>** — Reads, merges updates, validates, saves, returns updated ticket.\n\n   **Scheduling:**\n   - **getReadyTickets(): Promise<TicketState[]>** — Scans ALL plans with status 'active'. For each plan, checks tickets with status 'queued' whose blockedBy dependencies have ALL reached 'complete' status. Returns those tickets plus tickets already in 'ready' status.\n   - **getRunningCount(): Promise<number>** — Counts tickets with status 'running' across all active plans.\n\n   **Dependency resolution:**\n   - **resolveDependencies(planId: string): Promise<string[]>** — For a given plan, finds all 'queued' tickets whose blockedBy are all 'complete', transitions them to 'ready', returns the ticketIds that were unblocked.\n\nAll file reads should handle race conditions gracefully. Use try/catch on individual file reads and skip corrupted files with a warning.\n\nJSON files are pretty-printed with 2-space indent when written."
    },
    {
      "id": "05-logger",
      "name": "Logger Utility",
      "slice": 1,
      "description": "Per-ticket file logging plus console output with color.",
      "files": ["src/utils/logger.ts"],
      "dependsOn": ["01-project-scaffolding"],
      "priority": 1,
      "estimatedComplexity": "low",
      "prompt": "Create `src/utils/logger.ts` — a logging utility that writes to both per-ticket log files and the console.\n\nExport the following:\n\n1. **createLogger(logDir: string)** — factory function that returns a Logger instance. Creates logDir if it doesn't exist.\n\n2. **Logger** class/object with methods:\n   - **info(message: string, ticketId?: string): void** — Logs to console (chalk.blue prefix) and to ticket log file if ticketId provided\n   - **warn(message: string, ticketId?: string): void** — chalk.yellow prefix\n   - **error(message: string, ticketId?: string): void** — chalk.red prefix\n   - **success(message: string, ticketId?: string): void** — chalk.green prefix\n   - **phaseStart(ticketId: string, phaseId: string): void** — Logs phase start with timestamp\n   - **phaseEnd(ticketId: string, phaseId: string, status: 'success' | 'failure', durationMs: number): void** — Logs phase completion with duration\n   - **agentOutput(ticketId: string, output: string): void** — Writes agent stdout to the ticket's log file (not console)\n\nLog file format: `{logDir}/{ticketId}.log`\nEach line: `[ISO timestamp] [LEVEL] message`\n\nUse chalk for console colors. Use fs/promises appendFile for log writes.\n\nConsole format: `[HH:MM:SS] [LEVEL] [ticketId?] message` with colored level tags."
    },
    {
      "id": "06-cli-init-status",
      "name": "CLI: init + status commands",
      "slice": 1,
      "description": "Commander-based CLI entry point with the first two commands: `orchestrator init` and `orchestrator status`.",
      "files": ["src/cli.ts"],
      "dependsOn": ["03-config-loader", "04-state-manager", "05-logger"],
      "priority": 1,
      "estimatedComplexity": "medium",
      "prompt": "Create `src/cli.ts` — the Commander-based CLI entry point. This initial version implements only `init` and `status`. Later tasks extend this file.\n\nImports: Command from 'commander', loadConfig from './core/config.ts', createStateManager from './core/state.ts', createLogger from './utils/logger.ts', chalk, fs/promises, path.\n\nSet up:\n```typescript\nconst program = new Command()\n  .name('orchestrator')\n  .description('Agent orchestrator — deterministic state machine for autonomous software development')\n  .version('0.1.0');\n```\n\n**orchestrator init**\n- Scaffolds the directory structure: state/, logs/, workflows/, prompts/, scripts/, skills/\n- Copies default orchestrator.yaml if it doesn't exist\n- Prints a summary of created directories\n\n**orchestrator status [--plan <planId>] [--json]**\n- Loads all plans and their tickets from state manager\n- Without --json: prints a formatted table showing plan name, ticket ID, status, current phase\n- With --json: outputs raw JSON\n- With --plan: filters to just that plan\n- Use chalk for colored status indicators (green=complete, yellow=running, red=failed, gray=queued)\n\nEnd with `program.parse()`. Add `#!/usr/bin/env node` at the top."
    },

    {
      "id": "07-shell-util",
      "name": "Shell Execution Utility",
      "slice": 2,
      "description": "Subprocess execution wrapper for running bash scripts and CLI commands.",
      "files": ["src/utils/shell.ts"],
      "dependsOn": ["01-project-scaffolding"],
      "priority": 2,
      "estimatedComplexity": "low",
      "prompt": "Create `src/utils/shell.ts` — a utility for executing shell commands as child processes.\n\nExport the following:\n\n1. **ShellResult** interface: { stdout: string, stderr: string, exitCode: number }\n\n2. **execCommand(command: string, args: string[], options?: { cwd?: string, timeout?: number, env?: Record<string, string> }): Promise<ShellResult>**\n   - Uses child_process.spawn (import from 'node:child_process')\n   - Captures stdout and stderr as strings\n   - Resolves with ShellResult (does NOT reject on non-zero exit — caller decides)\n   - Supports optional timeout (kills process with SIGTERM after timeout ms)\n   - Merges provided env with process.env\n   - Streams output to buffers, trims final whitespace\n\n3. **execCommandStreaming(command: string, args: string[], options?: { cwd?: string, timeout?: number, env?: Record<string, string>, onStdout?: (chunk: string) => void, onStderr?: (chunk: string) => void }): Promise<ShellResult>**\n   - Same as execCommand but also calls onStdout/onStderr callbacks for real-time output\n   - Still accumulates full stdout/stderr in the result\n\nUse 'node:child_process' for spawn. Keep it simple — no retries, no parsing, just clean subprocess execution."
    },
    {
      "id": "08-template-renderer",
      "name": "Template Renderer",
      "slice": 2,
      "description": "Nunjucks-based template engine that renders prompt templates with ticket state variables and accumulated context.",
      "files": ["src/core/template.ts"],
      "dependsOn": ["02-core-types"],
      "priority": 2,
      "estimatedComplexity": "low",
      "prompt": "Create `src/core/template.ts` — renders Nunjucks templates with variables from ticket state and context.\n\nImports: TicketState from './types.ts'. Uses 'nunjucks' package.\n\nExport the following:\n\n1. **createTemplateRenderer(promptDir: string)** — factory that returns a TemplateRenderer. Configures a Nunjucks environment with:\n   - FileSystemLoader pointing at promptDir\n   - autoescape: false (markdown templates, not HTML)\n   - throwOnUndefined: false (missing variables render as empty string)\n\n2. **TemplateRenderer** object with methods:\n   - **render(templateFile: string, ticket: TicketState): string** — Renders the named template file. Template variable namespace is flat:\n     - All ticket fields directly: ticket_id, title, description, acceptance_criteria (joined with newlines), repo, branch, worktree, linear_url, plan_id\n     - All keys from ticket.context spread in (so {{pr_url}}, {{git_diff_stat}}, etc. work)\n     - A special `acceptance_criteria_list` that formats criteria as a markdown bullet list\n   - **renderString(template: string, ticket: TicketState): string** — Same but renders an inline template string. Useful for interpolating {{var}} in script args."
    },
    {
      "id": "09-workflow-loader",
      "name": "Workflow Loader",
      "slice": 2,
      "description": "Parses YAML workflow definition files, validates them, and provides lookup by name via the workflow registry.",
      "files": ["src/core/workflow.ts"],
      "dependsOn": ["02-core-types"],
      "priority": 2,
      "estimatedComplexity": "low",
      "prompt": "Create `src/core/workflow.ts` — loads and caches YAML workflow definitions.\n\nImports: WorkflowDefinition, WorkflowDefinitionSchema, WorkflowRegistryEntry, WorkflowRegistryEntrySchema from './types.ts'. Uses 'yaml' package.\n\nExport the following:\n\n1. **createWorkflowLoader(workflowDir: string)** — factory returning a WorkflowLoader.\n\n2. **WorkflowLoader** with methods:\n   - **loadRegistry(): Promise<WorkflowRegistryEntry[]>** — Reads workflows/registry.yaml, validates with Zod.\n   - **loadWorkflow(name: string): Promise<WorkflowDefinition>** — Looks up name in registry, reads YAML, validates. Caches in Map<string, WorkflowDefinition>.\n   - **getPhase(workflowName: string, phaseId: string): Promise<PhaseDefinition>** — Loads workflow, returns specific phase.\n   - **getNextPhase(workflowName: string, currentPhaseId: string, outcome: 'success' | 'failure'): Promise<string | null>** — Returns next phase ID from onSuccess/onFailure. Null if terminal.\n   - **clearCache(): void** — Clears in-memory workflow cache."
    },
    {
      "id": "10-minimal-workflow",
      "name": "Minimal Workflow YAML",
      "slice": 2,
      "description": "A simple 2-phase workflow for testing: one script phase → terminal. Validates the executor and runner before agent phases.",
      "files": ["workflows/minimal.yaml", "workflows/registry.yaml"],
      "dependsOn": [],
      "priority": 2,
      "estimatedComplexity": "low",
      "prompt": "Create two files:\n\n**workflows/minimal.yaml** — minimal test workflow:\n```yaml\nname: minimal\ndescription: \"Minimal test workflow: one script phase then done.\"\nphases:\n  - id: run_script\n    type: script\n    command: setup-worktree.sh\n    args: [\"{{repo}}\", \"{{branch}}\", \"{{worktree}}\"]\n    onSuccess: complete\n    onFailure: abort\n  - id: complete\n    type: terminal\n    notify: false\n  - id: abort\n    type: terminal\n    notify: true\n```\n\n**workflows/registry.yaml** — initial registry:\n```yaml\n- name: minimal\n  file: minimal.yaml\n  description: \"Minimal test workflow: one script phase then done.\"\n  tags: [test, minimal]\n```\n\nThe registry will be extended in later tasks."
    },
    {
      "id": "11-setup-worktree",
      "name": "Setup Worktree Script",
      "slice": 2,
      "description": "Bash script that creates a git worktree for a ticket.",
      "files": ["scripts/setup-worktree.sh"],
      "dependsOn": [],
      "priority": 2,
      "estimatedComplexity": "low",
      "prompt": "Create `scripts/setup-worktree.sh` — creates a git worktree.\n\nExecutable, `#!/usr/bin/env bash`, `set -euo pipefail`.\n\nArgs: $1=repo_path, $2=branch_name, $3=worktree_path\n\nSteps:\n1. Validate all three args\n2. cd into repo path\n3. Fetch latest: `git fetch origin`\n4. Create worktree: `git worktree add \"$3\" -b \"$2\" origin/main`\n   - If branch exists, try `git worktree add \"$3\" \"$2\"` instead\n5. Verify worktree was created\n6. Print success message\n\nExit 0 on success, exit 1 on failure."
    },
    {
      "id": "12-phase-executor-script",
      "name": "Phase Executor: script + terminal types",
      "slice": 2,
      "description": "Executes script and terminal workflow phases. Agent and poll types stubbed as errors — added in tasks 16 and 22.",
      "files": ["src/phases/executor.ts"],
      "dependsOn": [
        "03-config-loader",
        "07-shell-util",
        "08-template-renderer"
      ],
      "priority": 2,
      "estimatedComplexity": "medium",
      "prompt": "Create `src/phases/executor.ts` — executes workflow phases by type. This version handles **script** and **terminal** only.\n\nImports: PhaseDefinition, TicketState, OrchestratorConfig from '../core/types.ts', execCommand from '../utils/shell.ts', resolveAgent from '../core/config.ts', TemplateRenderer from '../core/template.ts', Logger from '../utils/logger.ts'.\n\nExport:\n\n1. **PhaseResult** interface: { success: boolean, output: string, captured: Record<string, string>, nextPhase: string | null }\n\n2. **createPhaseExecutor(config: OrchestratorConfig, templateRenderer: TemplateRenderer, logger: Logger)** → PhaseExecutor\n\n3. **PhaseExecutor.execute(phase: PhaseDefinition, ticket: TicketState, planAgent: string | null): Promise<PhaseResult>**\n\n   **Script handler:** Resolve script path from config.scriptDir + phase.command. Interpolate args via templateRenderer.renderString. Run via execCommand with cwd=ticket.worktree. Success = exitCode 0. Run capture rules.\n\n   **Terminal handler:** Always succeeds. If phase.notify is true, flag it. nextPhase is always null.\n\n   **Agent/poll handlers:** Throw 'not yet implemented' errors (added in tasks 16/22).\n\n   **Capture logic:** For each key in phase.capture: if value is 'stdout', capture phase output; otherwise render value as shell command template, execute it, capture stdout.\n\n   **Next phase:** success → phase.onSuccess ?? null. Failure + 'retry' → phase.id. Failure + 'abort' → 'abort'. Otherwise → phase.onFailure ?? null."
    },
    {
      "id": "13-runner-single-ticket",
      "name": "Runner: single-ticket mode",
      "slice": 2,
      "description": "Runs a single ticket through its workflow phases to completion. Daemon loop added in task 19.",
      "files": ["src/core/runner.ts"],
      "dependsOn": [
        "04-state-manager",
        "05-logger",
        "09-workflow-loader",
        "12-phase-executor-script"
      ],
      "priority": 2,
      "estimatedComplexity": "medium",
      "prompt": "Create `src/core/runner.ts` — drives ticket execution. This version: single-ticket mode only.\n\nImports: types from './types.ts', loadConfig/resolveAgent from './config.ts', createStateManager from './state.ts', createWorkflowLoader from './workflow.ts', createTemplateRenderer from './template.ts', createPhaseExecutor/PhaseResult from '../phases/executor.ts', createLogger from '../utils/logger.ts'.\n\nExport:\n\n1. **createRunner(config: OrchestratorConfig)** — initializes all subsystems, returns Runner.\n\n2. **Runner.executeTicketPhase(ticket: TicketState): Promise<void>**\n   a. Load plan for planAgent\n   b. Load workflow, get current phase definition\n   c. Log phase start\n   d. Check retries vs maxRetries\n   e. Execute phase via PhaseExecutor\n   f. Log phase end with duration\n   g. Record in phaseHistory\n   h. Merge captured values into ticket.context\n   i. Determine next phase: retry → increment retries + stay ready; abort/null+failure → failed; terminal+notify → needs_attention; terminal → complete; otherwise → update currentPhase + ready\n   j. Save ticket state\n   k. Wrap in try/catch — unexpected errors → failed status\n\n3. **Runner.runSingleTicket(planId: string, ticketId: string): Promise<void>**\n   Blocking loop: load ticket → executeTicketPhase → check terminal status → repeat."
    },
    {
      "id": "14-cli-run",
      "name": "CLI: run command",
      "slice": 2,
      "description": "Adds `orchestrator run <planId> <ticketId>` to the CLI.",
      "files": ["src/cli.ts"],
      "dependsOn": ["06-cli-init-status", "13-runner-single-ticket"],
      "priority": 2,
      "estimatedComplexity": "low",
      "prompt": "Extend `src/cli.ts` to add the `run` command.\n\nImport createRunner from './core/runner.ts'.\n\n**orchestrator run <planId> <ticketId>**\n- Loads config, creates runner, calls runSingleTicket(planId, ticketId)\n- Blocks until the ticket reaches a terminal state\n- Prints final status with chalk coloring"
    },

    {
      "id": "15-agent-invoker",
      "name": "Agent Invoker",
      "slice": 3,
      "description": "Abstraction layer for invoking headless coding agents (Claude Code, Codex) as subprocesses.",
      "files": ["src/agents/invoke.ts"],
      "dependsOn": ["02-core-types", "07-shell-util"],
      "priority": 3,
      "estimatedComplexity": "medium",
      "prompt": "Create `src/agents/invoke.ts` — invokes headless coding agents.\n\nImports: execCommandStreaming from '../utils/shell.ts'.\n\nExport:\n\n1. **AgentInvocation**: { prompt: string, cwd: string, allowedTools?: string[], maxTurns?: number }\n\n2. **AgentResult**: { stdout: string, stderr: string, exitCode: number, success: boolean }\n\n3. **invokeAgent(agentConfig: { command: string, defaultArgs: string[] }, invocation: AgentInvocation, callbacks?: { onOutput?: (chunk: string) => void }): Promise<AgentResult>**\n\n   Builds CLI args by agent command:\n   - **claude**: `claude -p \"<prompt>\" --output-format text` + defaultArgs + --allowedTools + --max-turns\n   - **codex**: `codex exec \"<prompt>\"` + defaultArgs\n   - **other**: `<command> \"<prompt>\"` + defaultArgs\n\n   Uses execCommandStreaming. Pass args as array (not shell string). 30-minute default timeout."
    },
    {
      "id": "16-phase-executor-agent",
      "name": "Phase Executor: agent type",
      "slice": 3,
      "description": "Adds agent phase handling to the executor — renders prompts, resolves agent config, invokes agent, captures output.",
      "files": ["src/phases/executor.ts"],
      "dependsOn": ["12-phase-executor-script", "15-agent-invoker"],
      "priority": 3,
      "estimatedComplexity": "medium",
      "prompt": "Extend `src/phases/executor.ts` to handle **agent** phase type.\n\nAdd import: invokeAgent from '../agents/invoke.ts'.\n\nReplace the 'not yet implemented' error with:\n\n**Agent handler:** Render prompt via templateRenderer.render(phase.promptTemplate, ticket). Resolve agent via resolveAgent(config, phase.agent, ticket.agent, planAgent). Invoke via invokeAgent. Pass logger.agentOutput as onOutput callback. Success = exitCode 0. Run capture rules.\n\nEverything else (script, terminal, capture, next phase) unchanged."
    },
    {
      "id": "17-implement-prompt",
      "name": "Implement Prompt Template",
      "slice": 3,
      "description": "The first real prompt template — sent to the agent during the implement phase.",
      "files": ["prompts/implement.md"],
      "dependsOn": [],
      "priority": 3,
      "estimatedComplexity": "low",
      "prompt": "Create `prompts/implement.md`:\n\nYou are implementing a feature for ticket {{ticket_id}}.\n\nTitle: {{title}}\n\nDescription:\n{{description}}\n\nAcceptance Criteria:\n{{acceptance_criteria_list}}\n\nInstructions:\n1. Read the project's CLAUDE.md or AGENTS.md to understand conventions, build commands, and test commands\n2. Explore the codebase to understand the relevant architecture\n3. Implement the feature according to the description and acceptance criteria\n4. Write tests that cover the acceptance criteria\n5. Run the project's test suite and fix any failures\n6. Run the project's linter and fix any issues\n7. Commit your changes with a clear commit message referencing {{ticket_id}}\n\nDo not create unnecessary abstractions. Keep changes focused and minimal."
    },
    {
      "id": "18-standard-workflow",
      "name": "Standard Workflow YAML (initial)",
      "slice": 3,
      "description": "Initial standard workflow: setup → implement → verify → create_pr → await_merge → cleanup → complete. No review cycle yet (added in task 25).",
      "files": ["workflows/standard.yaml", "workflows/registry.yaml"],
      "dependsOn": ["10-minimal-workflow"],
      "priority": 3,
      "estimatedComplexity": "medium",
      "prompt": "Create `workflows/standard.yaml` — initial standard workflow without the review cycle.\n\nPhase graph: setup → implement → verify → create_pr → await_merge → cleanup → complete\n\nPhases:\n- setup (script): setup-worktree.sh, args [{{repo}}, {{branch}}, {{worktree}}], onSuccess: implement, onFailure: abort\n- implement (agent): implement.md, tools [Read,Write,Edit,Bash,Grep,Glob], maxTurns 50, maxRetries 2, capture git_diff_stat, onSuccess: verify, onFailure: retry\n- verify (agent): verify.md, tools [Read,Write,Edit,Bash,Grep,Glob], maxTurns 30, maxRetries 2, capture test_output, onSuccess: create_pr, onFailure: retry\n- create_pr (agent): create-pr.md, tools [Bash], maxTurns 10, capture pr_url + pr_number, onSuccess: await_merge, onFailure: escalate\n- await_merge (poll): check-pr-merged.sh, args [{{repo}}, {{pr_number}}], interval 120, timeout 86400, onSuccess: cleanup, onFailure: escalate\n- cleanup (script): cleanup-worktree.sh, args [{{worktree}}], onSuccess: complete, onFailure: complete\n- complete (terminal): notify false\n- escalate (terminal): notify true\n- abort (terminal): notify true\n\nAlso update `workflows/registry.yaml` to add:\n```yaml\n- name: standard\n  file: standard.yaml\n  description: \"Standard implementation workflow.\"\n  tags: [feature, default]\n```"
    },

    {
      "id": "19-runner-daemon",
      "name": "Runner: daemon loop + dependency resolution",
      "slice": 4,
      "description": "Extends runner with tick-based daemon loop, concurrency management, and dependency resolution.",
      "files": ["src/core/runner.ts"],
      "dependsOn": ["13-runner-single-ticket"],
      "priority": 4,
      "estimatedComplexity": "high",
      "prompt": "Extend `src/core/runner.ts` with daemon loop and tick logic.\n\nAdd to Runner:\n\n**tick(): Promise<void>**\na. Resolve dependencies across all active plans (queued → ready where blockers complete)\nb. Get running count\nc. Get ready tickets\nd. For each ready ticket (up to maxConcurrency - runningCount): set to 'running', start executeTicketPhase (fire-and-forget)\ne. Return after dispatching\n\n**startDaemon(options?: { signal?: AbortSignal }): Promise<void>**\nRun tick() in loop with pollInterval seconds between ticks. Respect AbortSignal for graceful shutdown.\n\nUse Set<string> to track in-flight ticket IDs to prevent double-dispatch."
    },
    {
      "id": "20-cli-daemon-commands",
      "name": "CLI: daemon, tick, pause, resume, skip, retry",
      "slice": 4,
      "description": "Adds remaining operational CLI commands.",
      "files": ["src/cli.ts"],
      "dependsOn": ["14-cli-run", "19-runner-daemon"],
      "priority": 4,
      "estimatedComplexity": "medium",
      "prompt": "Extend `src/cli.ts` with remaining commands:\n\n**orchestrator daemon [--concurrency <n>] [--agent <name>]** — Start daemon loop with SIGINT/SIGTERM graceful shutdown.\n\n**orchestrator tick** — Run tick() once, then exit.\n\n**orchestrator pause <planId> <ticketId>** — Set ticket status to 'paused'.\n\n**orchestrator resume <planId> <ticketId>** — Set ticket status to 'ready'.\n\n**orchestrator skip <planId> <ticketId> <phase>** — Set currentPhase and status to 'ready'.\n\n**orchestrator retry <planId> <ticketId>** — Reset retry counter, set status to 'ready'.\n\n**orchestrator pause-plan <planId>** — Set plan status to 'paused'.\n\n**orchestrator resume-plan <planId>** — Set plan status to 'active'."
    },
    {
      "id": "21-cleanup-worktree",
      "name": "Cleanup Worktree Script",
      "slice": 4,
      "description": "Bash script to remove a git worktree after ticket completion.",
      "files": ["scripts/cleanup-worktree.sh"],
      "dependsOn": [],
      "priority": 4,
      "estimatedComplexity": "low",
      "prompt": "Create `scripts/cleanup-worktree.sh`.\n\nExecutable, `#!/usr/bin/env bash`, `set -euo pipefail`.\n\nArgs: $1=worktree_path\n\n1. Validate arg\n2. `git worktree remove \"$1\" --force`\n3. `git worktree prune`\n4. Print success\n\nIdempotent — don't fail if worktree doesn't exist."
    },

    {
      "id": "22-phase-executor-poll",
      "name": "Phase Executor: poll type",
      "slice": 5,
      "description": "Adds poll phase handling — runs a command at intervals until success or timeout.",
      "files": ["src/phases/executor.ts"],
      "dependsOn": ["12-phase-executor-script"],
      "priority": 5,
      "estimatedComplexity": "medium",
      "prompt": "Extend `src/phases/executor.ts` to handle **poll** phase type.\n\nReplace 'not yet implemented' error with:\n\n**Poll handler:** Resolve script path. Interpolate args. Run command at intervalSeconds intervals. Continue until exitCode 0 (success) or timeoutSeconds exceeded (failure). Wait between polls with setTimeout. Run capture rules on final successful execution."
    },
    {
      "id": "23-pr-scripts",
      "name": "PR Review & Merge Check Scripts",
      "slice": 5,
      "description": "Bash scripts for checking PR review status and merge status via gh CLI.",
      "files": ["scripts/check-pr-review.sh", "scripts/check-pr-merged.sh"],
      "dependsOn": [],
      "priority": 5,
      "estimatedComplexity": "low",
      "prompt": "Create two executable bash scripts:\n\n**scripts/check-pr-review.sh** — Args: $1=repo_path, $2=pr_number\n- APPROVED → echo 'approved', exit 0\n- CHANGES_REQUESTED or unresolved comments → echo 'changes_requested', exit 0\n- Waiting (no reviews) → exit 1\n- Error → exit 2\n\n**scripts/check-pr-merged.sh** — Args: $1=repo_path, $2=pr_number\n- MERGED → echo 'merged', exit 0\n- CLOSED (not merged) → echo 'closed', exit 2\n- Otherwise → exit 1\n\nBoth use `gh` CLI."
    },
    {
      "id": "24-remaining-prompts",
      "name": "Remaining Prompt Templates",
      "slice": 5,
      "description": "All prompt templates except implement.md: self-review, simplify, verify, create-pr, handle-review, push-fixes, implement-bugfix.",
      "files": [
        "prompts/implement-bugfix.md",
        "prompts/self-review.md",
        "prompts/simplify.md",
        "prompts/verify.md",
        "prompts/create-pr.md",
        "prompts/handle-review.md",
        "prompts/push-fixes.md"
      ],
      "dependsOn": [],
      "priority": 5,
      "estimatedComplexity": "medium",
      "prompt": "Create all remaining prompt templates in `prompts/`. Nunjucks markdown templates rendered with ticket variables.\n\nVariables: {{ticket_id}}, {{title}}, {{description}}, {{acceptance_criteria_list}}, {{repo}}, {{branch}}, {{worktree}}, {{linear_url}}, {{plan_id}}, {{git_diff_stat}}, {{pr_url}}, {{pr_number}}, {{test_output}}, {{review_verdict}}\n\n- **implement-bugfix.md** — Bug fix. Root cause, minimal changes, regression test.\n- **self-review.md** — Read-only diff review. Checklist. Output VERDICT: PASS or VERDICT: FAIL.\n- **simplify.md** — Clean up: dead code, abstractions, conditionals. Don't change functionality.\n- **verify.md** — Run tests and linter. Fix failures. All checks must pass.\n- **create-pr.md** — Push branch, `gh pr create` with summary and acceptance criteria.\n- **handle-review.md** — Address PR review comments. Make changes, resolve threads.\n- **push-fixes.md** — Push fix commits. No force push."
    },
    {
      "id": "25-full-standard-workflow",
      "name": "Full Standard Workflow",
      "slice": 5,
      "description": "Updates standard workflow with self-review, simplify, and full PR review cycle.",
      "files": ["workflows/standard.yaml", "workflows/registry.yaml"],
      "dependsOn": ["18-standard-workflow"],
      "priority": 5,
      "estimatedComplexity": "medium",
      "prompt": "Update `workflows/standard.yaml` to full phase graph:\n\nsetup → implement → self_review → simplify → verify → create_pr → await_review ←→ handle_review → verify_post_review → push_fixes → await_merge → cleanup → complete\n\nAdd between implement and verify:\n- self_review (agent): self-review.md, read-only tools, maxTurns 10, capture review_verdict, onSuccess: simplify, onFailure: implement\n- simplify (agent): simplify.md, all tools, maxTurns 20, onSuccess: verify, onFailure: verify\n\nAdd PR review cycle after create_pr:\n- await_review (poll): check-pr-review.sh, interval 120, timeout 86400\n- handle_review (agent): handle-review.md, maxTurns 30\n- verify_post_review (agent): verify.md, maxTurns 30, maxRetries 1\n- push_fixes (agent): push-fixes.md, maxTurns 5, onSuccess: await_review (loop)\n\nUpdate registry.yaml description."
    },
    {
      "id": "26-bugfix-workflow",
      "name": "Bugfix Workflow YAML",
      "slice": 5,
      "description": "Abbreviated workflow for bug fixes — skips self-review and simplify.",
      "files": ["workflows/bugfix.yaml", "workflows/registry.yaml"],
      "dependsOn": [],
      "priority": 5,
      "estimatedComplexity": "low",
      "prompt": "Create `workflows/bugfix.yaml` — abbreviated bug fix workflow.\n\nPhase graph: setup → implement → verify → create_pr → await_review ←→ handle_review → verify_post_review → push_fixes → await_merge → cleanup → complete\n\nUses implement-bugfix.md prompt, maxTurns 30. Skips self_review and simplify.\n\nAdd to registry.yaml:\n```yaml\n- name: bugfix\n  file: bugfix.yaml\n  description: \"Abbreviated workflow for bug fixes.\"\n  tags: [bug, hotfix]\n```"
    },
    {
      "id": "27-workflow-registry",
      "name": "Workflow Registry & Docs",
      "slice": 5,
      "description": "Final registry listing all workflows, plus README documenting phase types for workflow authors.",
      "files": ["workflows/registry.yaml", "workflows/README.md"],
      "dependsOn": ["25-full-standard-workflow", "26-bugfix-workflow"],
      "priority": 5,
      "estimatedComplexity": "low",
      "prompt": "Finalize `workflows/registry.yaml` with all workflows (minimal, standard, bugfix).\n\nCreate `workflows/README.md` — reference for workflow authors:\n- Overview of workflows and state machine\n- Phase types reference (script, agent, poll, terminal) with all fields and examples\n- Template variables list\n- Capture rules\n- Transitions (onSuccess/onFailure, retry, abort)\n- How to add a new workflow\n- Common patterns (review cycles, read-only agents, retry limits)"
    },

    {
      "id": "28-planner-skill",
      "name": "Planner Skill",
      "slice": 6,
      "description": "SKILL.md teaching the LLM planner to create plans and ticket state files.",
      "files": ["skills/planner/SKILL.md"],
      "dependsOn": [],
      "priority": 6,
      "estimatedComplexity": "medium",
      "prompt": "Create `skills/planner/SKILL.md` — core planner skill.\n\nTeach: creating plan directories, writing _plan.json (full schema + examples), writing ticket state files, dependency management, workflow selection, agent selection, CLI commands. Include 2-3 complete examples."
    },
    {
      "id": "29-workflow-skill",
      "name": "Workflow Skill",
      "slice": 6,
      "description": "SKILL.md for creating custom YAML workflows.",
      "files": ["skills/workflows/SKILL.md"],
      "dependsOn": [],
      "priority": 6,
      "estimatedComplexity": "low",
      "prompt": "Create `skills/workflows/SKILL.md` — workflow authoring skill.\n\nCover: phase type reference, all fields, template variables, capture rules, transitions, registry, example 'review-only' workflow."
    },
    {
      "id": "30-linear-provider-skill",
      "name": "Linear Provider Skill",
      "slice": 6,
      "description": "SKILL.md for fetching Linear tickets and mapping to orchestrator state files.",
      "files": ["skills/providers/linear/SKILL.md"],
      "dependsOn": [],
      "priority": 6,
      "estimatedComplexity": "low",
      "prompt": "Create `skills/providers/linear/SKILL.md` — Linear integration skill.\n\nCover: fetching tickets via Linear MCP/API, mapping fields to ticket state, branch naming, example sprint → plan generation."
    },
    {
      "id": "31-github-issues-provider-skill",
      "name": "GitHub Issues Provider Skill",
      "slice": 6,
      "description": "SKILL.md for fetching GitHub Issues and mapping to orchestrator state files.",
      "files": ["skills/providers/github-issues/SKILL.md"],
      "dependsOn": [],
      "priority": 6,
      "estimatedComplexity": "low",
      "prompt": "Create `skills/providers/github-issues/SKILL.md` — GitHub Issues skill.\n\nCover: fetching via `gh` CLI, mapping fields to ticket state, branch naming, example milestone → plan generation."
    },
    {
      "id": "32-claude-md-update",
      "name": "CLAUDE.md Update",
      "slice": 6,
      "description": "Update CLAUDE.md with full progressive disclosure docs for the completed orchestrator.",
      "files": ["CLAUDE.md"],
      "dependsOn": [],
      "priority": 6,
      "estimatedComplexity": "medium",
      "prompt": "Update `CLAUDE.md` with progressive disclosure:\n\n## Quick Reference — project summary, language, build/test/dev commands, key CLI commands\n## Architecture — two-process design, state files, YAML workflows, four phase types\n## Project Structure — all directories\n## Conventions — Zod schemas, named exports, async/await, deterministic runner\n## For the LLM Planner — links to skills\n## Adding a New Workflow — steps\n## Adding a New Agent Provider — steps"
    }
  ],
  "dependencyGraph": {
    "description": "Dependencies organized by vertical slice. Each slice delivers testable end-to-end functionality.",
    "foundation": {
      "tasks": ["01-project-scaffolding", "02-core-types"],
      "note": "Already complete."
    },
    "slice1_config_and_state": {
      "tasks": [
        "03-config-loader",
        "04-state-manager",
        "05-logger",
        "06-cli-init-status"
      ],
      "note": "03, 04, 05 in parallel → then 06",
      "testableOutcome": "orchestrator init + orchestrator status with hand-created state files"
    },
    "slice2_script_phases": {
      "tasks": [
        "07-shell-util",
        "08-template-renderer",
        "09-workflow-loader",
        "10-minimal-workflow",
        "11-setup-worktree",
        "12-phase-executor-script",
        "13-runner-single-ticket",
        "14-cli-run"
      ],
      "note": "07, 08, 09, 10, 11 in parallel → 12 → 13 → 14",
      "testableOutcome": "orchestrator run executes a script phase and updates state"
    },
    "slice3_agent_phases": {
      "tasks": [
        "15-agent-invoker",
        "16-phase-executor-agent",
        "17-implement-prompt",
        "18-standard-workflow"
      ],
      "note": "15, 17 in parallel → 16. 18 independent",
      "testableOutcome": "orchestrator run invokes a coding agent and progresses through phases"
    },
    "slice4_daemon": {
      "tasks": [
        "19-runner-daemon",
        "20-cli-daemon-commands",
        "21-cleanup-worktree"
      ],
      "note": "19, 21 in parallel → 20",
      "testableOutcome": "orchestrator daemon processes tickets concurrently with dependency resolution"
    },
    "slice5_review_cycle": {
      "tasks": [
        "22-phase-executor-poll",
        "23-pr-scripts",
        "24-remaining-prompts",
        "25-full-standard-workflow",
        "26-bugfix-workflow",
        "27-workflow-registry"
      ],
      "note": "22, 23, 24, 26 in parallel → 25 → 27",
      "testableOutcome": "Full workflows with PR review loops work end-to-end"
    },
    "slice6_docs_and_skills": {
      "tasks": [
        "28-planner-skill",
        "29-workflow-skill",
        "30-linear-provider-skill",
        "31-github-issues-provider-skill",
        "32-claude-md-update"
      ],
      "note": "All 5 in parallel. No code dependencies.",
      "testableOutcome": "LLM planner can create valid plans from project management tools"
    }
  },
  "parallelizationStrategy": {
    "criticalPath": "02 → 03 → 12 → 13 → 14 → 19 → 20",
    "withinSliceParallelism": {
      "slice1": "03, 04, 05 in parallel → 06",
      "slice2": "07, 08, 09, 10, 11 in parallel → 12 → 13 → 14",
      "slice3": "15, 17 in parallel → 16; 18 independent",
      "slice4": "19, 21 in parallel → 20",
      "slice5": "22, 23, 24, 26 in parallel → 25 → 27",
      "slice6": "all 5 in parallel"
    },
    "integrationNote": "After each slice, verify the testable outcome. Run `pnpm run build` and `pnpm run typecheck` between slices."
  }
}