opencastle 0.14.0 → 0.16.0

package/src/cli/run.ts

@@ -1,26 +1,28 @@
 import { readFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
 import { resolve } from 'node:path'
-import { parseTaskSpec } from './run/schema.js'
+import { parseTaskSpecText, isConvoySpec } from './run/schema.js'
 import { createExecutor, buildPhases } from './run/executor.js'
 import { getAdapter, detectAdapter } from './run/adapters/index.js'
 import { createReporter, printExecutionPlan } from './run/reporter.js'
 import type { CliContext, RunOptions } from './types.js'
+import type { ConvoyResult } from './convoy/engine.js'
 
 const HELP = `
   opencastle run [options]
 
   Process a task queue from a spec file, delegating to AI agents autonomously.
-  Supports two modes: tasks (default phase-based execution) and loop (iterative Ralph Loop).
+  Version 1 specs use the Convoy Engine; legacy specs use the standard executor.
 
   Options:
     --file, -f <path>        Task spec file (default: opencastle.tasks.yml)
     --dry-run                Show execution plan without running
-    --concurrency, -c <n>    Override max parallel tasks (tasks mode)
+    --concurrency, -c <n>    Override max parallel tasks
     --adapter, -a <name>     Override agent runtime adapter
     --report-dir <path>      Where to write run reports (default: .opencastle/runs)
     --verbose                Show full agent output
-    --mode <name>            Execution mode: tasks | loop
-    --max-iterations <n>     Override max loop iterations (loop mode)
+    --resume                 Resume the last interrupted convoy from .opencastle/convoy.db
+    --status                 Print the current convoy state from .opencastle/convoy.db
     --help, -h               Show this help
 `
 
@@ -36,8 +38,8 @@ function parseArgs(args: string[]): RunOptions {
     reportDir: null,
     verbose: false,
     help: false,
-    maxIterations: null,
-    mode: null,
+    resume: false,
+    status: false,
   }
 
   for (let i = 0; i < args.length; i++) {
@@ -79,26 +81,12 @@ function parseArgs(args: string[]): RunOptions {
       case '--verbose':
         opts.verbose = true
         break
-      case '--max-iterations': {
-        if (i + 1 >= args.length) { console.error('  \u2717 --max-iterations requires a number'); process.exit(1) }
-        const val = parseInt(args[++i], 10)
-        if (!Number.isFinite(val) || val < 1) {
-          console.error(`  \u2717 --max-iterations must be an integer >= 1`)
-          process.exit(1)
-        }
-        opts.maxIterations = val
+      case '--resume':
+        opts.resume = true
         break
-      }
-      case '--mode': {
-        if (i + 1 >= args.length) { console.error('  \u2717 --mode requires a name'); process.exit(1) }
-        const modeVal = args[++i]
-        if (modeVal !== 'tasks' && modeVal !== 'loop') {
-          console.error(`  \u2717 --mode must be one of: tasks, loop`)
-          process.exit(1)
-        }
-        opts.mode = modeVal
+      case '--status':
+        opts.status = true
         break
-      }
       default:
         console.error(`  ✗ Unknown option: ${arg}`)
         console.log(HELP)
@@ -109,6 +97,61 @@ function parseArgs(args: string[]): RunOptions {
   return opts
 }
 
+/**
+ * Print a user-friendly adapter unavailable error.
+ */
+function printAdapterError(detectionFailed: boolean, adapterName: string): void {
+  if (detectionFailed) {
+    console.error(
+      `  ✗ No agent CLI found on your PATH.\n` +
+        `    Install one of the following adapters:\n` +
+        `    • copilot    — https://docs.github.com/en/copilot/how-tos/set-up/install-copilot-cli\n` +
+        `    • claude     — npm install -g @anthropic-ai/claude-code\n` +
+        `    • cursor     — https://cursor.com (Cursor > Install CLI)\n` +
+        `\n` +
+        `    Or specify an adapter explicitly: opencastle run --adapter <name>`
+    )
+  } else {
+    const hints: Record<string, string> = {
+      'claude-code':
+        '    Install: npm install -g @anthropic-ai/claude-code\n' +
+        '    Docs:    https://docs.anthropic.com/en/docs/claude-code',
+      copilot:
+        '    Requires the Copilot CLI installed and authenticated:\n' +
+        '    https://docs.github.com/en/copilot/how-tos/set-up/install-copilot-cli\n' +
+        '    Docs:    https://docs.github.com/en/copilot',
+      cursor:
+        '    The Cursor agent CLI ships with the Cursor editor.\n' +
+        '    Install Cursor from https://cursor.com and ensure the\n' +
+        '    "agent" command is on your PATH (Cursor > Install CLI).',
+    }
+    const cliName = adapterName === 'claude-code' ? 'claude' : adapterName
+    const hint = hints[adapterName] ?? ''
+    console.error(
+      `  ✗ Adapter "${adapterName}" is not available.\n` +
+        `    Make sure the "${cliName}" CLI is installed and on your PATH.\n` +
+        hint
+    )
+  }
+}
+
+/**
+ * Print a convoy result summary.
+ */
+function printConvoyResult(result: ConvoyResult): void {
+  console.log(`\n  ──────────────────────────────────────`)
+  console.log(`  Convoy ${result.status}: ${result.duration}`)
+  console.log(
+    `  Done: ${result.summary.done} | Failed: ${result.summary.failed} | Skipped: ${result.summary.skipped} | Timed out: ${result.summary.timedOut}`
+  )
+  if (result.gateResults) {
+    console.log(`  Gates:`)
+    for (const g of result.gateResults) {
+      console.log(`    ${g.passed ? '✓' : '✗'} ${g.command}`)
+    }
+  }
+}
+
 /**
  * CLI entry point for the `run` command.
  */
@@ -120,15 +163,133 @@ export default async function run({ args }: CliContext): Promise<void> {
     return
   }
 
+  const dbPath = resolve(process.cwd(), '.opencastle', 'convoy.db')
+
+  // ── --status flag ─────────────────────────────────────────────
+  if (opts.status) {
+    if (!existsSync(dbPath)) {
+      console.log('  No convoy database found at .opencastle/convoy.db')
+      return
+    }
+    const { createConvoyStore } = await import('./convoy/store.js')
+    const store = createConvoyStore(dbPath)
+    try {
+      const convoy = store.getLatestConvoy()
+      if (!convoy) {
+        console.log('  No convoy records found.')
+        return
+      }
+      const tasks = store.getTasksByConvoy(convoy.id)
+      const byStatus = tasks.reduce((acc, t) => {
+        acc[t.status] = (acc[t.status] ?? 0) + 1
+        return acc
+      }, {} as Record<string, number>)
+      console.log(`\n  Convoy: ${convoy.name}`)
+      console.log(`  ID:     ${convoy.id}`)
+      console.log(`  Status: ${convoy.status}`)
+      console.log(`  Branch: ${convoy.branch ?? '(none)'}`)
+      console.log(`  Created: ${convoy.created_at}`)
+      if (convoy.started_at) console.log(`  Started: ${convoy.started_at}`)
+      if (convoy.finished_at) console.log(`  Finished: ${convoy.finished_at}`)
+      console.log(`\n  Tasks:`)
+      for (const [status, count] of Object.entries(byStatus)) {
+        console.log(`    ${status}: ${count}`)
+      }
+      console.log(`    total: ${tasks.length}`)
+    } finally {
+      store.close()
+    }
+    return
+  }
+
+  // ── --resume flag ─────────────────────────────────────────────
+  if (opts.resume) {
+    if (!existsSync(dbPath)) {
+      console.error('  ✗ No convoy database found at .opencastle/convoy.db')
+      console.error('    Run a convoy spec first: opencastle run convoy.yml')
+      process.exit(1)
+    }
+    const { createConvoyStore } = await import('./convoy/store.js')
+    const store = createConvoyStore(dbPath)
+    const convoy = store.getLatestConvoy()
+    store.close()
+    if (!convoy) {
+      console.error('  ✗ No convoy records found in .opencastle/convoy.db')
+      process.exit(1)
+    }
+    if (convoy.status === 'done' || convoy.status === 'failed') {
+      console.error(
+        `  ✗ Last convoy "${convoy.name}" already finished with status: ${convoy.status}`
+      )
+      console.error(`    Only interrupted (running/pending) convoys can be resumed.`)
+      process.exit(1)
+    }
+
+    const resumeSpec = parseTaskSpecText(convoy.spec_yaml)
+    if (opts.concurrency !== null) resumeSpec.concurrency = opts.concurrency
+    if (opts.adapter !== null) resumeSpec.adapter = opts.adapter
+    if (opts.verbose) resumeSpec._verbose = true
+
+    let resumeDetectionFailed = false
+    if (!resumeSpec.adapter) {
+      const detected = await detectAdapter()
+      if (detected) {
+        resumeSpec.adapter = detected
+        console.log(`  ℹ Auto-detected adapter: ${detected}`)
+      } else {
+        resumeDetectionFailed = true
+        resumeSpec.adapter = 'claude-code'
+      }
+    }
+
+    const resumeAdapter = await getAdapter(resumeSpec.adapter)
+    const resumeAvailable = await resumeAdapter.isAvailable()
+    if (!resumeAvailable) {
+      printAdapterError(resumeDetectionFailed, resumeSpec.adapter)
+      process.exit(1)
+    }
+
+    console.log(`\n  \uD83C\uDFF0 OpenCastle Convoy (Resume): ${convoy.name}`)
+    console.log(`  Convoy ID: ${convoy.id}`)
+    const { createConvoyEngine } = await import('./convoy/engine.js')
+    const resumeEngine = createConvoyEngine({
+      spec: resumeSpec,
+      specYaml: convoy.spec_yaml,
+      adapter: resumeAdapter,
+      verbose: opts.verbose,
+    })
+    const resumeResult = await resumeEngine.resume(convoy.id)
+    printConvoyResult(resumeResult)
+    process.exit(resumeResult.status !== 'done' ? 1 : 0)
+  }
+
   // ── Read and validate spec ────────────────────────────────────
   const specPath = resolve(process.cwd(), opts.file)
-  const spec = await parseTaskSpec(specPath)
+  let specText = ''
+  try {
+    specText = await readFile(specPath, 'utf8')
+  } catch (err: unknown) {
+    const e = err as Error & { code?: string }
+    if (e.code === 'ENOENT') {
+      console.error(`  ✗ Task spec file not found: ${opts.file}`)
+    } else {
+      console.error(`  ✗ Cannot read task spec file: ${e.message}`)
+    }
+    process.exit(1)
+  }
+
+  let spec
+  try {
+    spec = parseTaskSpecText(specText)
+  } catch (err: unknown) {
+    console.error(`  ✗ ${(err as Error).message}`)
+    process.exit(1)
+  }
 
   // Apply CLI overrides
   if (opts.concurrency !== null) spec.concurrency = opts.concurrency
   if (opts.adapter !== null) spec.adapter = opts.adapter
   if (opts.verbose) spec._verbose = true
-  if (opts.mode !== null) spec.mode = opts.mode as 'tasks' | 'loop'
 
   // ── Auto-detect adapter if not specified ─────────────────────
   let detectionFailed = false
@@ -145,22 +306,13 @@ export default async function run({ args }: CliContext): Promise<void> {
 
   // ── Dry run ──────────────────────────────────────────────────
   if (opts.dryRun) {
-    if (spec.mode === 'loop') {
-      const loop = spec.loop!
-      console.log(`\n  \uD83C\uDFF0 Loop Plan: ${spec.name}`)
-      console.log(`  Mode: loop`)
-      console.log(`  Prompt: ${loop.prompt}`)
-      console.log(`  Max iterations: ${loop.max_iterations}`)
-      console.log(`  Timeout: ${loop.timeout}`)
-      if (loop.plan_file) console.log(`  Plan file: ${loop.plan_file}`)
-      if (loop.model) console.log(`  Model: ${loop.model}`)
-      if (loop.backpressure?.length) {
-        console.log(`  Backpressure:`)
-        for (const cmd of loop.backpressure) {
-          console.log(`    - ${cmd}`)
-        }
-      }
-      return
+    if (isConvoySpec(spec)) {
+      console.log(`\n  \uD83C\uDFF0 Convoy Plan: ${spec.name}`)
+      console.log(
+        `  Adapter: ${spec.adapter} | Concurrency: ${spec.concurrency} | Tasks: ${spec.tasks!.length}`
+      )
+      if (spec.branch) console.log(`  Branch: ${spec.branch}`)
+      if (spec.gates?.length) console.log(`  Gates: ${spec.gates.length} validation commands`)
     }
     const phases = buildPhases(spec.tasks!)
     printExecutionPlan(spec, phases)
@@ -171,78 +323,37 @@ export default async function run({ args }: CliContext): Promise<void> {
   const adapter = await getAdapter(spec.adapter)
   const available = await adapter.isAvailable()
   if (!available) {
-    if (detectionFailed) {
-      console.error(
-        `  ✗ No agent CLI found on your PATH.\n` +
-          `    Install one of the following adapters:\n` +
-          `    • copilot    — https://docs.github.com/en/copilot/how-tos/set-up/install-copilot-cli\n` +
-          `    • claude     — npm install -g @anthropic-ai/claude-code\n` +
-          `    • cursor     — https://cursor.com (Cursor > Install CLI)\n` +
-          `\n` +
-          `    Or specify an adapter explicitly: opencastle run --adapter <name>`
-      )
-    } else {
-      const hints: Record<string, string> = {
-        'claude-code':
-          '    Install: npm install -g @anthropic-ai/claude-code\n' +
-          '    Docs:    https://docs.anthropic.com/en/docs/claude-code',
-        copilot:
-          '    Requires the Copilot CLI installed and authenticated:\n' +
-          '    https://docs.github.com/en/copilot/how-tos/set-up/install-copilot-cli\n' +
-          '    Docs:    https://docs.github.com/en/copilot',
-        cursor:
-          '    The Cursor agent CLI ships with the Cursor editor.\n' +
-          '    Install Cursor from https://cursor.com and ensure the\n' +
-          '    "agent" command is on your PATH (Cursor > Install CLI).',
-      }
-      const cliName = spec.adapter === 'claude-code' ? 'claude' : spec.adapter
-      const hint = hints[spec.adapter] ?? ''
-      console.error(
-        `  ✗ Adapter "${spec.adapter}" is not available.\n` +
-          `    Make sure the "${cliName}" CLI is installed and on your PATH.\n` +
-          hint
-      )
-    }
+    printAdapterError(detectionFailed, spec.adapter)
     process.exit(1)
   }
 
-  // ── Execute ──────────────────────────────────────────────────
-  if (spec.mode === 'loop') {
-    const { createLoopExecutor } = await import('./run/loop-executor.js')
-    const { createLoopReporter } = await import('./run/loop-reporter.js')
+  // ── Convoy engine path (version: 1 specs) ────────────────────
+  if (isConvoySpec(spec)) {
+    const { createConvoyEngine } = await import('./convoy/engine.js')
+    console.log(`\n  \uD83C\uDFF0 OpenCastle Convoy: ${spec.name}`)
+    console.log(
+      `  Adapter: ${adapter.name} | Concurrency: ${spec.concurrency} | Tasks: ${spec.tasks!.length}`
+    )
+    if (spec.branch) console.log(`  Branch: ${spec.branch}`)
+    if (spec.gates?.length) console.log(`  Gates: ${spec.gates.length} validation commands`)
 
-    if (opts.maxIterations !== null && spec.loop) {
-      spec.loop.max_iterations = opts.maxIterations
-    }
-
-    const promptPath = resolve(process.cwd(), spec.loop!.prompt)
-    try {
-      await readFile(promptPath)
-    } catch {
-      console.error(`  \u2717 Prompt file not found: ${spec.loop!.prompt}`)
-      process.exit(1)
-    }
-
-    console.log(`\n  \uD83C\uDFF0 OpenCastle Loop: ${spec.name}`)
-    console.log(`  Adapter: ${adapter.name} | Max iterations: ${spec.loop!.max_iterations} | Timeout: ${spec.loop!.timeout}`)
-    if (spec.loop!.backpressure?.length) {
-      console.log(`  Backpressure: ${spec.loop!.backpressure.join(', ')}`)
-    }
-
-    const loopReporter = createLoopReporter(spec.name, {
-      reportDir: opts.reportDir ? resolve(process.cwd(), opts.reportDir) : undefined,
+    const engine = createConvoyEngine({
+      spec,
+      specYaml: specText,
+      adapter,
       verbose: opts.verbose,
     })
 
-    const loopExecutor = createLoopExecutor(spec, adapter, loopReporter)
-    const loopReport = await loopExecutor.run()
-
-    const failed = loopReport.stoppedReason === 'error' || loopReport.stoppedReason === 'backpressure-fail'
-    process.exit(failed ? 1 : 0)
+    const result = await engine.run()
+    printConvoyResult(result)
+    process.exit(result.status !== 'done' ? 1 : 0)
   }
 
+  // ── Legacy executor path ──────────────────────────────────────
   console.log(`\n  \uD83C\uDFF0 OpenCastle Run: ${spec.name}`)
-  console.log(`  Adapter: ${adapter.name} | Concurrency: ${spec.concurrency} | Tasks: ${spec.tasks!.length}`)
+  console.log(
+    `  Adapter: ${adapter.name} | Concurrency: ${spec.concurrency} | Tasks: ${spec.tasks!.length}`
+  )
 
   const reporter = createReporter(spec, {
     reportDir: opts.reportDir

package/src/cli/types.ts

@@ -134,22 +134,6 @@ export interface TaskDefaults {
   agent?: string;
 }
 
-/** Loop execution configuration. */
-export interface LoopConfig {
-  /** Maximum number of agent iterations (default 20). */
-  max_iterations: number;
-  /** Path to the prompt file read each iteration. */
-  prompt: string;
-  /** Path to the plan file (default 'IMPLEMENTATION_PLAN.md'). */
-  plan_file?: string;
-  /** Per-iteration timeout (default '10m'). */
-  timeout: string;
-  /** Model override for loop sessions. */
-  model?: string;
-  /** Shell commands that must exit 0 after each iteration. */
-  backpressure?: string[];
-}
-
 /** Validated task spec from YAML. */
 export interface TaskSpec {
   name: string;
@@ -157,8 +141,6 @@ export interface TaskSpec {
   on_failure: 'continue' | 'stop';
   adapter: string;
   tasks?: Task[];
-  mode?: 'tasks' | 'loop';
-  loop?: LoopConfig;
   _verbose?: boolean;
   /** Spec schema version (1 for Convoy Engine format). */
   version?: number;
@@ -271,8 +253,8 @@ export interface RunOptions {
   reportDir: string | null;
   verbose: boolean;
   help: boolean;
-  maxIterations: number | null;
-  mode: string | null;
+  resume: boolean;
+  status: boolean;
 }
 
 /** Validation result. */
@@ -292,49 +274,3 @@ export interface Executor {
   run(): Promise<RunReport>;
   getPhases(): Task[][];
 }
-
-// ── Loop executor types ────────────────────────────────────────
-
-/** Result of a single backpressure command run. */
-export interface BackpressureResult {
-  command: string;
-  exitCode: number;
-  output: string;
-  passed: boolean;
-}
-
-/** Result of a single loop iteration. */
-export interface LoopIterationResult {
-  iteration: number;
-  status: 'done' | 'failed' | 'backpressure-fail';
-  duration: number;
-  output: string;
-  backpressureResults?: BackpressureResult[];
-}
-
-/** Final report produced by the loop executor. */
-export interface LoopRunReport {
-  name: string;
-  mode: 'loop';
-  startedAt: string;
-  completedAt: string;
-  duration: string;
-  totalIterations: number;
-  completedIterations: number;
-  stoppedReason: 'max-iterations' | 'plan-empty' | 'backpressure-fail' | 'user-abort' | 'error';
-  iterations: LoopIterationResult[];
-}
-
-/** Reporter interface for loop execution progress. */
-export interface LoopReporter {
-  onIterationStart(iteration: number, maxIterations: number): void;
-  onIterationDone(iteration: number, result: LoopIterationResult): void;
-  onBackpressureStart(command: string): void;
-  onBackpressureResult(result: BackpressureResult): void;
-  onComplete(report: LoopRunReport): Promise<void>;
-}
-
-/** Executor for loop-mode run specs. */
-export interface LoopExecutor {
-  run(): Promise<LoopRunReport>;
-}

package/src/dashboard/node_modules/.vite/deps/_metadata.json

@@ -1,25 +1,25 @@
 {
-  "hash": "a6abe049",
+  "hash": "f5f05037",
   "configHash": "30f8ea04",
-  "lockfileHash": "c72e777b",
-  "browserHash": "737e5c4c",
+  "lockfileHash": "99d70434",
+  "browserHash": "d43a2a07",
   "optimized": {
     "astro > cssesc": {
       "src": "../../../../../node_modules/cssesc/cssesc.js",
       "file": "astro___cssesc.js",
-      "fileHash": "3a9e4516",
+      "fileHash": "29d5277e",
       "needsInterop": true
     },
     "astro > aria-query": {
       "src": "../../../../../node_modules/aria-query/lib/index.js",
       "file": "astro___aria-query.js",
-      "fileHash": "774ff115",
+      "fileHash": "4ca620a4",
       "needsInterop": true
     },
     "astro > axobject-query": {
       "src": "../../../../../node_modules/axobject-query/lib/index.js",
       "file": "astro___axobject-query.js",
-      "fileHash": "bd1844a6",
+      "fileHash": "4072a265",
       "needsInterop": true
     }
   },

package/src/orchestrator/agents/team-lead.agent.md

@@ -17,9 +17,9 @@ handoffs:
   - label: Quick Refinement
     agent: 'Team Lead (OpenCastle)'
     prompt: 'Use the quick-refinement prompt to handle these follow-up refinements (UI tweaks, polish, adjustments):'
-  - label: Generate Task Spec
+  - label: Generate Convoy Spec
     agent: 'Team Lead (OpenCastle)'
-    prompt: 'Use the generate-task-spec prompt to create an opencastle.tasks.yml spec for autonomous overnight runs based on:'
+    prompt: 'Use the generate-task-spec prompt to create a .convoy.yml spec for autonomous convoy runs based on:'
   - label: Resolve PR Comments
     agent: 'Team Lead (OpenCastle)'
     prompt: 'Use the resolve-pr-comments prompt to resolve the GitHub PR review comments on this PR:'

package/src/orchestrator/prompts/generate-task-spec.prompt.md

@@ -1,5 +1,5 @@
 ---
-description: 'Generate a valid .tasks.yml spec file for autonomous overnight runs based on a high-level description of what needs to be done.'
+description: 'Generate a valid .convoy.yml spec file for autonomous convoy runs based on a high-level description of what needs to be done.'
 agent: 'Team Lead (OpenCastle)'
 ---
 
@@ -7,7 +7,7 @@ agent: 'Team Lead (OpenCastle)'
 
 # Generate Task Spec for Autonomous Run
 
-You are the Team Lead. The user wants to run `opencastle run` to execute a batch of tasks autonomously (e.g., overnight). Your job is to produce a valid `.tasks.yml` file they can feed to the CLI. Derive a short, descriptive, kebab-case filename from the user's goal (2–4 words max) and use it as the filename — for example `auth-refactor.tasks.yml` or `add-search.tasks.yml`. Always use the `.tasks.yml` extension.
+You are the Team Lead. The user wants to run `opencastle run` to execute a batch of tasks autonomously (e.g., overnight). Your job is to produce a valid `.convoy.yml` file they can feed to the CLI. Derive a short, descriptive, kebab-case filename from the user's goal (2–4 words max) and use it as the filename — for example `auth-refactor.convoy.yml` or `add-search.convoy.yml`. Always use the `.convoy.yml` extension.
 
 ## User Goal
 
@@ -28,9 +28,13 @@ The output file must conform to the following schema. Fields marked **(required)
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
 | `name` | string | **yes** | — | Human-readable name for the run |
+| `version` | integer | **yes** | — | Spec schema version. Always `1` for convoy specs |
 | `concurrency` | integer ≥ 1 | no | `1` | Max tasks executing in parallel |
 | `on_failure` | `continue` \| `stop` | no | `continue` | Behaviour when a task fails |
 | `adapter` | string | no | auto-detect | Default CLI adapter (`claude-code`, `copilot`, `cursor`). Omit to let the CLI auto-detect the first available adapter. |
+| `branch` | string | no | — | Git feature branch name — created if missing |
+| `defaults` | object | no | — | Worker defaults merged into each task. Keys: `timeout`, `model`, `max_retries`, `agent` |
+| `gates` | array of strings | no | — | Shell commands run after all tasks complete; each must exit 0 |
 | `tasks` | list | **yes** | — | Non-empty list of task objects |
 
 ### Task Fields
@@ -44,6 +48,8 @@ The output file must conform to the following schema. Fields marked **(required)
 | `depends_on` | list of ids | no | `[]` | Task ids that must finish before this one starts |
 | `files` | list of globs | no | `[]` | File scope the agent is allowed to modify |
 | `timeout` | duration | no | `30m` | Max wall time (`<number><s|m|h>`, e.g. `10m`, `1h`) |
+| `max_retries` | integer | no | from `defaults` or `1` | Max retry attempts for this task |
+| `model` | string | no | — | AI model override for this task |
 
 ### Agent Roster
 
@@ -97,6 +103,9 @@ For each workstream, break it down into the smallest meaningful unit of work tha
 - `concurrency` — set to 2–3 for overnight runs; keep at 1 if tasks share files or the machine is constrained.
 - `on_failure` — use `continue` (default) when tasks are independent so one failure doesn't waste the whole run. Use `stop` when every subsequent task depends on success.
 - `adapter` — **omit this field** to let the CLI auto-detect the first available adapter (priority: `copilot` → `claude-code` → `cursor`). Only set this explicitly if the user requests a specific adapter.
+- `branch` — derive from the goal, e.g., `feat/auth-refactor`. Use a descriptive branch name.
+- `defaults` — set sensible defaults for timeout and max_retries. Model can be left unset for auto-detection.
+- `gates` — include standard validation gates (lint, type-check, test) unless the user specifies otherwise.
 
 ### 5. Write the Prompts
 
@@ -128,11 +137,16 @@ Before presenting the YAML, mentally verify:
 Return the final YAML inside a fenced code block with a filename annotation:
 
 ````yaml
-# <feature-name>.tasks.yml
+# <feature-name>.convoy.yml
 name: <run name>
+version: 1
 concurrency: <n>
 on_failure: <continue|stop>
-# adapter: <adapter>  # Omit for auto-detection; set only when user requests a specific adapter
+branch: <branch-name>
+
+defaults:
+  timeout: 30m
+  max_retries: 1
 
 tasks:
   - id: <task-id>
@@ -148,9 +162,16 @@ tasks:
     depends_on:
       - <task-id>
     ...
+
+gates:
+  - <lint command>
+  - <type-check command>
+  - <test command>
 ````
 
 Also provide:
 1. A **DAG summary** showing the phase structure so the user can verify execution order.
 2. An **estimated total duration** (sum of timeouts on the critical path).
-3. A `--dry-run` command they can use to validate: `npx opencastle run --file <feature-name>.tasks.yml --dry-run`
+3. A `--dry-run` command they can use to validate: `npx opencastle run --file <feature-name>.convoy.yml --dry-run`
+
+> **Backward compatibility:** `.tasks.yml` files without `version` still work with the legacy executor. Only spec files with `version: 1` are routed to the convoy engine.

package/dist/cli/run/loop-executor.d.ts

@@ -1,3 +0,0 @@
-import type { TaskSpec, AgentAdapter, LoopReporter, LoopExecutor } from '../types.js';
-export declare function createLoopExecutor(spec: TaskSpec, adapter: AgentAdapter, reporter: LoopReporter): LoopExecutor;
-//# sourceMappingURL=loop-executor.d.ts.map

package/dist/cli/run/loop-executor.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"loop-executor.d.ts","sourceRoot":"","sources":["../../../src/cli/run/loop-executor.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,QAAQ,EAIR,YAAY,EACZ,YAAY,EACZ,YAAY,EAEb,MAAM,aAAa,CAAA;AA2DpB,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,YAAY,EACrB,QAAQ,EAAE,YAAY,GACrB,YAAY,CAwHd"}