opencastle 0.18.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencastle",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "type": "module",
   "description": "Multi-agent orchestration framework for AI coding assistants",
   "bin": {

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

@@ -1,25 +1,25 @@
 {
-  "hash": "2da8e910",
+  "hash": "37afd6de",
   "configHash": "30f8ea04",
-  "lockfileHash": "d05fc548",
-  "browserHash": "f317e71b",
+  "lockfileHash": "fc91404e",
+  "browserHash": "4ed40789",
   "optimized": {
     "astro > cssesc": {
       "src": "../../../../../node_modules/cssesc/cssesc.js",
       "file": "astro___cssesc.js",
-      "fileHash": "28561a14",
+      "fileHash": "797719d6",
       "needsInterop": true
     },
     "astro > aria-query": {
       "src": "../../../../../node_modules/aria-query/lib/index.js",
       "file": "astro___aria-query.js",
-      "fileHash": "8f623d19",
+      "fileHash": "92b9b174",
       "needsInterop": true
     },
     "astro > axobject-query": {
       "src": "../../../../../node_modules/axobject-query/lib/index.js",
       "file": "astro___axobject-query.js",
-      "fileHash": "31fe5731",
+      "fileHash": "b81bf886",
       "needsInterop": true
     }
   },

package/src/orchestrator/agents/session-guard.agent.md

@@ -72,6 +72,20 @@ If the session summary mentions fast reviews or panel reviews, verify matching r
 
 Only flag if the session produced code changes that should have been committed. Research-only or analysis sessions may not produce commits.
 
+### 7. Convoy Observability (if convoy was executed)
+
+If the session involved running a convoy (check for `.opencastle/convoy.db` or references to convoy execution in the session summary):
+
+**Verify convoy NDJSON export:**
+- `cat .opencastle/logs/convoys.ndjson | tail -1` should show the latest convoy record
+- Record should have `status: done` or `status: failed` (not `running`)
+
+**Verify convoy tasks logged:**
+- Each completed convoy task should have a corresponding event in the NDJSON log
+- Check: `grep '"type":"session"' .github/customizations/logs/events.ndjson | tail -10`
+
+**Fix:** If convoy export is missing, the engine should have auto-exported. Manual export: run `opencastle run --status` to verify the convoy completed.
+
 ## Output
 
 Return a structured report:

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

@@ -17,9 +17,12 @@ 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 Convoy Spec
+  - label: Generate Convoy
     agent: 'Team Lead (OpenCastle)'
-    prompt: 'Use the generate-task-spec prompt to create a .convoy.yml spec for autonomous convoy runs based on:'
+    prompt: 'Use the generate-convoy prompt to create a .convoy.yml spec for autonomous convoy execution based on:'
+  - label: Run Convoy
+    agent: 'Team Lead (OpenCastle)'
+    prompt: 'Run an existing .convoy.yml spec file. Parse the spec, validate the DAG, and execute via the convoy engine:'
   - 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:'
@@ -135,6 +138,46 @@ See the **team-lead-reference** skill for model tiers, token estimates, duration
 
 Before EVERY delegation verify: (1) Tracker issue exists, (2) File partition is clean, (3) Dependencies verified Done, (4) Prompt includes file paths + acceptance criteria, (5) Self-improvement reminder included.
 
+## Convoy Integration
+
+The convoy engine is the preferred execution mechanism for multi-task work. Use it when a request decomposes into 3 or more subtasks.
+
+### When to use convoy vs. direct delegation
+
+| Task count | Approach |
+|------------|----------|
+| 1–2 subtasks | **Direct delegation** — sub-agents inline, standard workflow |
+| 3+ subtasks | **Convoy execution** — generate spec, hand to user to run |
+
+### How to generate a convoy spec
+
+1. Decompose the request into tasks as normal (Steps 1–2)
+2. Use the `generate-convoy` prompt with the decomposed task list as context
+3. The `generate-convoy` prompt produces a valid `.convoy.yml` spec with DAG, agents, file scopes, and gates
+
+### How to execute a convoy
+
+Tell the user to run:
+```
+npx opencastle run -f <name>.convoy.yml
+```
+This gives the user control over when execution starts (preferred — supports overnight/unattended runs and manual review of the spec before execution).
+
+### After convoy completes
+
+1. Run all validation gates (lint, test, build) on the convoy's output branch
+2. Open a PR from the convoy's configured `branch` — do NOT merge
+3. Link the PR in the tracker issue
+4. Log the session record as usual
+
+### What the convoy engine handles automatically
+
+- **Isolated git worktrees** per task — parallel agents never touch the same files
+- **Parallel execution** with configurable concurrency
+- **Merge queue ordering** — respects `depends_on` DAG when merging worktrees
+- **Crash recovery** — `opencastle run --resume` continues from last checkpoint
+- **Progress monitoring** — `opencastle run --status` shows live task state
+
 ## Workflow
 
 ### Step 1: Understand

package/src/orchestrator/prompts/bootstrap-customizations.prompt.md

@@ -270,7 +270,7 @@ Now that your project is configured, here's what you can do:
 3. **Implement a feature** — Use the **"Implement Feature"** prompt to have the Team Lead orchestrate a full feature build with task tracking, delegation, and verification
 4. **Fix a bug** — Use the **"Bug Fix"** prompt for structured triage, root cause analysis, and fix with tracker tracking
 5. **Brainstorm first** — Not sure how to approach something? Use the **"Brainstorm"** prompt to explore requirements and trade-offs before committing to a plan
-6. **Create a task spec** — Use the **"Generate Task Spec"** prompt to create `opencastle.tasks.yml` for autonomous overnight runs with `npx opencastle run` CLI command.
+6. **Generate a convoy spec** — Use the **"Generate Convoy"** prompt to create a `.convoy.yml` spec for autonomous convoy execution with `npx opencastle run` CLI command.
 
 ## Guidelines
 

package/src/orchestrator/prompts/brainstorm.prompt.md

@@ -107,11 +107,12 @@ Not every task needs a brainstorm. Skip this prompt and go directly to `implemen
 - The task is a simple config change or docs update
 - The technical approach is obvious and unambiguous
 - The scope is a single file or component with no design decisions
+- The task is well-understood and can be expressed as a convoy spec directly → use `generate-convoy` instead
 
 ## After Brainstorming
 
 Once the brainstorm is complete and the user confirms (or you're confident in the approach):
 
-1. **Transition to planning** — use the brainstorm report as input for `implement-feature` or the appropriate workflow
+1. **Transition to planning** — use the brainstorm report as input for `implement-feature` (which will choose between direct delegation and convoy execution based on task count)
 2. **Preserve context** — include the brainstorm report in delegation prompts so agents understand *why* an approach was chosen
 3. **Reference in tracker** — link the brainstorm findings in the tracker issue description

package/src/orchestrator/prompts/{generate-task-spec.prompt.md → generate-convoy.prompt.md}

@@ -1,13 +1,13 @@
 ---
-description: 'Generate a valid .convoy.yml spec file for autonomous convoy runs based on a high-level description of what needs to be done.'
+description: 'Generate a .convoy.yml spec file for autonomous convoy execution based on a high-level goal.'
 agent: 'Team Lead (OpenCastle)'
 ---
 
 <!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
 
-# Generate Task Spec for Autonomous Run
+# Generate Convoy Spec
 
-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.
+You are the Team Lead. The user wants to run `opencastle run` to execute a batch of tasks autonomously via the convoy engine. 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
 
@@ -174,4 +174,4 @@ Also provide:
 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>.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/src/orchestrator/prompts/implement-feature.prompt.md

@@ -45,10 +45,34 @@ Every subtask must be tracked. **No issue = no implementation.** This step produ
    - **Acceptance criteria:** Verifiable checklist
    - **Dependencies:** Links to prerequisite issues
 5. **Link to roadmap** — Reference the roadmap section in the issue description so context is never lost
-6. **Verify issues exist** — List all created issue IDs. If count is 0, do NOT proceed to Step 3
+6. **Verify issues exist** — List all created issue IDs. If count is 0, do NOT proceed to Step 2.5
+
+### 2.5 Choose Execution Path (BLOCKING — decides how Step 3 proceeds)
+
+With the full task list in hand, decide the execution mechanism:
+
+| Condition | Execution path |
+|-----------|----------------|
+| 1–2 subtasks | **Direct delegation** — delegate to sub-agents as today (proceed to Step 3 as-is) |
+| 3+ subtasks | **Convoy execution** — generate a `.convoy.yml` spec using the `generate-convoy` prompt, then hand it to the user |
+
+#### Direct delegation (1–2 subtasks)
+
+Proceed with the normal Step 3 delegation workflow. Sub-agents handle each task inline.
+
+#### Convoy execution (3+ subtasks)
+
+1. **Generate the spec** — use the `generate-convoy` prompt with the decomposed task list as context. The spec IS the implementation plan — no manual per-task delegation is needed.
+2. **Hand the spec to the user** — tell them to run: `npx opencastle run -f <name>.convoy.yml`
+3. **The convoy engine handles** isolated git worktrees, parallel execution, merge queue ordering, and crash recovery automatically.
+4. **After convoy completes** — proceed to Step 4 (validation) and Step 5 (delivery/PR). The convoy engine will have created its own commits on the configured branch.
+
+> **Why convoy for 3+ tasks?** Parallel worktree isolation prevents file conflicts. The merge queue ensures safe ordering. Crash recovery means a failing task doesn't block others. Manual delegation of 3+ parallel tasks risks conflicts and is harder to monitor.
 
 ### 3. Implementation Rules
 
+> **For convoy execution (3+ subtasks):** The convoy spec file IS the implementation plan — skip the manual delegation workflow below and jump to Step 4 after the user runs the convoy. The convoy engine delegates tasks internally using the agents and prompts defined in the spec.
+
 #### Issue Traceability
 
 - **Pass issue ID to every agent** — When delegating a subtask (sub-agent or background), include the tracker issue ID and title in the prompt so the agent knows which tracked task it is completing
@@ -93,6 +117,8 @@ Every subtask must pass ALL gates before being marked Done:
 
 Follow the **Delivery Outcome** defined in the **git-workflow** skill — commit, push, open PR (not merged), and link to the tracker.
 
+> **For convoy execution:** The convoy engine creates commits on the configured `branch` directly. After validation passes, open the PR from that branch. No additional commits from the Team Lead are needed unless gates failed and required manual fixes.
+
 ### 6. Documentation & Traceability
 
 Keep documentation current so future sessions have full context:

package/src/orchestrator/prompts/quick-refinement.prompt.md

@@ -127,6 +127,8 @@ Stop the follow-up workflow and switch to a full roadmap task if:
 
 When escalating, explain to the user what you found and why it needs proper tracking.
 
+- **Multi-task escalation** — If the refinement decomposes into 3+ subtasks, switch to `implement-feature` (which will use convoy execution for multi-task work)
+
 ### 8. Completion
 
 The follow-up is complete when: