opencastle 0.23.1 → 0.23.2

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

@@ -145,14 +145,14 @@ Before EVERY delegation verify: (1) Tracker issue exists, (2) File partition is
 
 ## 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.
+The convoy engine is the **mandatory** execution mechanism for all project-related work — features, bug fixes, and refactors. This ensures consistent observability, crash recovery, and progress visibility.
 
 ### 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 |
+| Work type | Approach |
+|-----------|----------|
+| Features, bug fixes, refactors (any subtask count) | **Convoy execution** — always generate a `.convoy.yml` spec, even for 1-task fixes |
+| Utility prompts (`bootstrap-customizations`, `create-skill`, `generate-convoy`, `brainstorm`, `quick-refinement`) | **Direct** — these are meta/tooling operations, not project code changes |
 
 ### How to generate a convoy spec
 
@@ -164,7 +164,7 @@ The convoy engine is the preferred execution mechanism for multi-task work. Use
 
 Tell the user to run:
 ```
-npx opencastle run -f <name>.convoy.yml
+npx opencastle run -f .opencastle/convoys/<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).
 

package/src/orchestrator/prompts/bug-fix.prompt.md

@@ -83,9 +83,13 @@ Find WHY the bug happens, not just WHERE:
 
 ### 4. Implement the Fix
 
-Delegate to the appropriate specialist agent via **sub-agent** (inline). For bugs that are clearly isolated and well-understood, a single delegation is usually sufficient.
+All bug fixes are executed via the convoy engine — even single-task fixes — to ensure observability and crash recovery.
 
-#### Delegation Prompt Must Include
+1. **Generate a convoy spec** — use the `generate-convoy` prompt with the root cause analysis, fix approach, and file paths as context.
+2. **Hand the spec to the user** — tell them to run: `npx opencastle run -f .opencastle/convoys/<name>.convoy.yml`
+3. **After convoy completes** — proceed to Step 5 (validation).
+
+#### Convoy Task Prompt Must Include
 
 - **Tracker issue ID and title** — e.g., `TAS-XX — [Bug] Description`
 - **Root cause** — What's wrong and why

package/src/orchestrator/prompts/generate-convoy.prompt.md

@@ -7,7 +7,7 @@ agent: 'Team Lead (OpenCastle)'
 
 # Generate Convoy Spec
 
-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.
+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. Store all generated convoy specs in the `.opencastle/convoys/` directory (create it if it doesn't exist).
 
 ## User Goal
 
@@ -137,7 +137,7 @@ Before presenting the YAML, mentally verify:
 Return the final YAML inside a fenced code block with a filename annotation:
 
 ````yaml
-# <feature-name>.convoy.yml
+# .opencastle/convoys/<feature-name>.convoy.yml
 name: <run name>
 version: 1
 concurrency: <n>
@@ -172,6 +172,6 @@ gates:
 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>.convoy.yml --dry-run`
+3. A `--dry-run` command they can use to validate: `npx opencastle run --file .opencastle/convoys/<feature-name>.convoy.yml --dry-run`
 
 

package/src/orchestrator/prompts/implement-feature.prompt.md

@@ -47,31 +47,20 @@ Every subtask must be tracked. **No issue = no implementation.** This step produ
 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 2.5
 
-### 2.5 Choose Execution Path (BLOCKING — decides how Step 3 proceeds)
+### 2.5 Generate Convoy Spec (BLOCKING — decides how Step 3 proceeds)
 
-With the full task list in hand, decide the execution mechanism:
+All project-related work is executed via the convoy engine — regardless of subtask count. This ensures consistent observability, crash recovery, and live progress.
 
-| 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.
+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. Even single-task fixes go through convoy for observability.
+2. **Hand the spec to the user** — tell them to run: `npx opencastle run -f .opencastle/convoys/<name>.convoy.yml`
+3. **The convoy engine handles** isolated git worktrees, parallel execution, merge queue ordering, crash recovery, and structured logging 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.
+> **Why always convoy?** Convoy execution is the only path that guarantees observability logging, crash recovery, gate validation, and live progress. Direct sub-agent delegation produces no structured logs and cannot be resumed if interrupted.
 
 ### 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.
+> **Convoy execution:** 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
 
@@ -117,7 +106,7 @@ 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.
+> 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