opencastle 0.30.1 → 0.31.0

package/src/orchestrator/prompts/assess-complexity.prompt.md

@@ -0,0 +1,67 @@
+---
+description: 'Assess PRD complexity and recommend convoy strategy (single vs chain). Returns structured JSON consumed by the pipeline.'
+agent: 'Reviewer'
+output: json
+---
+
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
+
+# Assess PRD Complexity
+
+Analyze the PRD below and produce a complexity assessment as a **single JSON object**. This JSON is consumed programmatically by the pipeline to decide whether to generate one convoy spec or a chain of convoy specs.
+
+## PRD to Analyze
+
+{{goal}}
+
+## Original User Prompt
+
+{{context}}
+
+---
+
+## Output Rules
+
+**CRITICAL:** Return ONLY a single fenced JSON block — no prose, no explanation, no markdown headings. Start your response with the opening fence and end with the closing fence.
+
+## Required JSON Schema
+
+```json
+{
+  "original_prompt": "<string>",
+  "total_tasks": <number>,
+  "total_phases": <number>,
+  "domains": ["<string>", ...],
+  "estimated_duration_minutes": <number>,
+  "complexity": "low" | "medium" | "high",
+  "recommended_strategy": "single" | "chain",
+  "chain_rationale": "<string — empty when strategy is single>",
+  "convoy_groups": [
+    {
+      "name": "<kebab-case-name>",
+      "description": "<one sentence>",
+      "phases": [<phase numbers>],
+      "depends_on": ["<group name>", ...]
+    }
+  ]
+}
+```
+
+## Field Rules
+
+- `original_prompt`: Copy the user's original feature request verbatim from the "Original User Prompt" section above. If that section is empty, extract a one-sentence summary from the PRD's Overview section.
+- `total_tasks`: Count of individual workstreams in the Task Breakdown.
+- `total_phases`: Count of phases in the Task Breakdown.
+- `domains`: List of technical domains involved (e.g., "frontend", "api", "database", "testing", "config").
+- `estimated_duration_minutes`: Rough estimate assuming AI agent execution (not human).
+- `complexity`: `"low"` (1–4 tasks), `"medium"` (5–8 tasks), `"high"` (9+ tasks).
+- `recommended_strategy`:
+  - `"single"` when: total tasks ≤ 8, OR total phases ≤ 3, OR all tasks are tightly coupled with heavy cross-phase file sharing.
+  - `"chain"` when: total tasks > 8 AND total phases > 3 AND domains have natural boundaries — AND splitting improves failure isolation, observability, or retry granularity.
+- `chain_rationale`: Only filled when `recommended_strategy` is `"chain"` — explain WHY splitting benefits this specific feature.
+- `convoy_groups`:
+  - When `"single"`: exactly one group covering all phases.
+  - When `"chain"`: 2–4 groups with explicit `depends_on` order. Each group covers a coherent domain boundary.
+  - **Minimum 3 tasks per group.** Never create a group that would produce a convoy with only 1–2 tasks — merge small groups with adjacent ones. A convoy with a single task is pointless overhead.
+  - **Do NOT map phases 1:1 to groups.** Groups should bundle multiple related phases when tasks are tightly coupled (e.g., config + data in one group, components + pages in another). Only split at genuine domain boundaries where failure isolation matters.
+  - Maximum 3 groups for projects with ≤ 15 tasks. Maximum 4 groups for 16+ tasks.

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

@@ -9,11 +9,13 @@ agent: 'Team Lead (OpenCastle)'
 
 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).
 
+> **⚠️ OUTPUT FORMAT: Your entire response must be a single ` ```yaml ` fenced code block containing the convoy spec. Do NOT output any text, explanations, summaries, or DAG diagrams before or after the YAML block. The parser only reads the ` ```yaml ` fence — everything else causes a failure.**
+
 ## User Goal
 
 {{goal}}
 
-## Additional Context
+## PRD Reference
 
 {{context}}
 
@@ -311,24 +313,17 @@ For complex tasks, consider using `steps` to break the prompt into sequential su
 
 ### Chain Mode (Subset Generation)
 
-When the `{{context}}` field contains a JSON object with `"mode": "chain_subset"`, you are generating ONE convoy spec that is part of a larger convoy chain. The context will look like:
-
-```json
-{
-  "mode": "chain_subset",
-  "group_name": "database-setup",
-  "group_description": "Schema changes and migrations",
-  "group_phases": [1],
-  "depends_on_groups": [],
-  "total_groups": 3,
-  "group_index": 1
-}
-```
-
-When this context is present:
-- **Only** generate tasks for the phases listed in `group_phases`. Do not include tasks from other phases.
+When the `{{goal}}` section contains a "Convoy Group Scope" heading, you are generating ONE convoy spec that is part of a larger convoy chain. The goal will contain:
+
+- The original user prompt
+- The group name, description, phases to cover, and dependency info
+
+The full PRD is available in the `{{context}}` section as reference.
+
+When chain mode is detected:
+- **Only** generate tasks for the phases listed in the group scope. Do not include tasks from other phases.
 - Use `version: 1` — this spec is a single convoy, not a pipeline.
-- Derive the convoy `name` from `group_name` (e.g., "Database Setup").
+- Derive the convoy `name` from the group name (e.g., "Database Setup").
 - Derive the `branch` from the PRD's feature name, but it will be overridden by the pipeline anyway.
 - Keep all other conventions (prompts, files, gates, etc.) the same as for single-spec generation.
 
@@ -346,7 +341,7 @@ Before presenting the YAML, mentally verify:
 
 ### 7. Output
 
-Return the final YAML inside a fenced code block with a filename annotation:
+Your response must contain **ONLY** a single ` ```yaml ` fenced code block — no text before it, no text after it, no explanations, no summaries, no DAG diagrams. The pipeline parser will only extract content from the ` ```yaml ` fence. Any other text in your response is discarded and may cause parsing failures.
 
 ````yaml
 # .opencastle/convoys/<feature-name>.convoy.yml
@@ -393,9 +388,4 @@ gates:
 gate_retries: 1
 ````
 
-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 -f .opencastle/convoys/<feature-name>.convoy.yml --dry-run`
-
 

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

@@ -29,9 +29,13 @@ If the feature request involves a specific person, place, organization, topic, o
    > ℹ️ Content based on training data — verify before launch.
 3. **Never fabricate or hallucinate content.** If you genuinely have no knowledge about a real-world subject and cannot search, state what is unknown and use placeholder text. This applies to all content: bios, descriptions, histories, statistics, quotes, and any factual claims.
 
+## Output Rules
+
+**CRITICAL:** Return the PRD as your text response. Do NOT create any files. Do NOT use file-writing tools. Simply output the full PRD document as text. Do not wrap it in a code fence — start directly with the `#` heading. Do not summarize — output the complete document.
+
 ## Required PRD Structure
 
-Produce the PRD in Markdown using **exactly** the sections below. Do not skip or merge sections. Do not wrap the output in a code fence — output raw Markdown starting directly with the `#` heading.
+Produce the PRD in Markdown using **exactly** the sections below. Do not skip or merge sections.
 
 ---
 
@@ -56,6 +60,12 @@ Explicit exclusions — what this work does **not** cover. If nothing is exclude
 
 For each primary scenario, write a user story + binary acceptance criteria. Criteria must be testable (pass/fail — no subjective language).
 
+**Quality rules for acceptance criteria (the validator WILL reject violations):**
+- Every criterion must be evaluable as deterministic pass/fail — no subjective language ("looks good", "feels responsive", "is clean", "visually distinct")
+- Do NOT use modal verbs that imply optionality: "should", "might", "could", "may"
+- Do NOT use vague qualifiers: "or equivalent", "or similar", "as needed"
+- State exact expected values (e.g., exact heading text, exact attribute names)
+
 **US-1: [Short title]**
 As a [user type], I want [action] so that [benefit].
 
@@ -76,7 +86,7 @@ Specific technical constraints the implementation must respect:
 
 ## Implementation Scope
 
-List **every file and directory** that will be created, modified, or deleted. Use specific paths — not broad paths like `src/`. Group by concern.
+List **every file and directory** that will be created, modified, or deleted. Use specific paths — not broad paths like `src/`. Group by concern. Use compact file lists — group related files with commas instead of separate rows when they share a concern. Do NOT use glob patterns (`*`, `**`). Every concern must list at least one specific file.
 
 | Concern | Files / Directories |
 |---------|---------------------|
@@ -95,6 +105,14 @@ List **every file and directory** that will be created, modified, or deleted. Us
 
 Decompose into the minimum number of phases. Tasks in the same phase run in parallel and **must not share any files**.
 
+Keep task descriptions **brief** — 1 sentence each. List only file paths, not explanations. Prefer compact formatting.
+
+**Quality rules (the validator WILL reject violations):**
+- Each workstream must list exact files it will modify
+- No two parallel workstreams (same phase) may claim the same file
+- Phases must have explicit dependency declarations (`depends on: Phase N`)
+- No circular dependencies
+
 ```
 Phase 1 — Foundation (parallel, no dependencies):
   - [Workstream A title]: [2-sentence description]
@@ -127,35 +145,3 @@ Measurable, binary checks that confirm the feature is shippable:
 - **[Open question]**: [What needs to be decided before implementation can start]
 
 If there are no risks or open questions, write "None identified."
-
-## Complexity Assessment
-
-Produce a fenced JSON block with the following fields. This is consumed programmatically by the pipeline to decide whether to generate a single convoy spec or a convoy chain.
-
-```json
-{
-  "total_tasks": 12,
-  "total_phases": 4,
-  "domains": ["database", "api", "frontend", "testing"],
-  "estimated_duration_minutes": 120,
-  "complexity": "low",
-  "recommended_strategy": "single",
-  "chain_rationale": "",
-  "convoy_groups": [
-    {
-      "name": "full-implementation",
-      "description": "All phases in a single convoy",
-      "phases": [1, 2, 3, 4],
-      "depends_on": []
-    }
-  ]
-}
-```
-
-**Strategy decision rules:**
-- Use `"single"` when: total tasks ≤ 8, or total phases ≤ 3, or all tasks are tightly coupled with heavy cross-phase file sharing.
-- Use `"chain"` when: total tasks > 8 AND total phases > 3 AND domains have natural boundaries (e.g., database changes are independent from frontend components from test suites) — AND splitting would improve failure isolation, observability, or retry granularity.
-- When `"single"`: provide exactly one convoy group covering all phases.
-- When `"chain"`: provide 2–4 convoy groups with explicit `depends_on` order. Each group should cover a coherent domain boundary.
-- `complexity` values: `"low"` (1–4 tasks), `"medium"` (5–8 tasks), `"high"` (9+ tasks).
-- `chain_rationale` is only filled when `recommended_strategy` is `"chain"` — explain WHY splitting benefits this specific feature.

package/src/orchestrator/prompts/validate-prd.prompt.md

@@ -56,7 +56,7 @@ Evaluate **every item** below. If ALL items pass, respond `VALID`. If ANY item f
 
 ### Language Quality
 
-- [ ] No undefined acronyms or jargon used without explanation
+- [ ] No **domain-specific** acronyms or jargon used without explanation (standard software acronyms like API, CSS, HTML, CI/CD, CMS, SDK, CLI, URL, JSON, REST, SQL, SSR, SSG, CDN, DNS, TLS, JWT, OAuth, CRUD, DOM, UI, UX, HTTP, HTTPS, LTS, WCAG, RTL, MCP, PRD, E2E are considered universally understood and do not need expansion)
 - [ ] No conflicting requirements (e.g., "must be fast AND run full suite on every change")
 - [ ] Section content is not placeholder/template text (e.g., "2–3 sentences about…", "Description here")