opencastle 0.35.1 → 0.35.3

package/src/orchestrator/prompts/create-skill.prompt.md

@@ -1,5 +1,5 @@
 ---
-description: 'Scaffold a new skill file with proper frontmatter, structure, and registration. Use when adding a new domain skill to the AI configuration.'
+description: 'Scaffold new skill file with proper frontmatter, structure, registration. Use when adding new domain skill to AI configuration.'
 agent: 'Team Lead (OpenCastle)'
 ---
 
@@ -7,7 +7,7 @@ agent: 'Team Lead (OpenCastle)'
 
 # Create Skill
 
-Scaffold a new skill for the AI agent configuration. Skills encode domain-specific knowledge that agents load on demand.
+Scaffold new skill for AI agent configuration. Skills encode domain-specific knowledge agents load on demand.
 
 ## Skill Request
 
@@ -17,14 +17,14 @@ Scaffold a new skill for the AI agent configuration. Skills encode domain-specif
 
 ## Skill Types
 
-OpenCastle has two kinds of skills with different locations and registration paths:
+OpenCastle has two skill kinds with different locations, registration paths:
 
 | Type | Location | Bound Via | Purpose |
 |------|----------|-----------|---------|
 | **Process skill** | `skills/<name>/SKILL.md` | `directSkills` in skill-matrix.json | Stack-agnostic methodology (testing workflow, self-improvement, validation gates) |
 | **Plugin skill** | `plugins/<plugin>/SKILL.md` | Capability slot in the skill matrix | Technology-specific knowledge (CMS queries, database patterns, deployment config) |
 
-> **Rule of thumb:** If the skill would need to be rewritten when switching technologies (e.g., Supabase → Convex), it belongs in a **plugin**. If it's useful regardless of stack, it's a **process skill**.
+> **Rule of thumb:** If skill would need rewriting when switching technologies (e.g., Supabase → Convex), it belongs in a **plugin**. If useful regardless of stack, it's a **process skill**.
 
 ---
 
@@ -45,7 +45,7 @@ Determine the type:
 - Use `kebab-case`
 - **Process skills:** descriptive domain name (e.g., `testing-workflow`, `context-map`, `security-hardening`)
 - **Plugin skills:** `skillName` field in the plugin's `config.ts` (e.g., `sanity-cms`, `supabase-database`, `nx-workspace`)
-- Check existing skills in `skills/` and `plugins/` to avoid overlap
+- Check existing skills in `skills/`, `plugins/` to avoid overlap
 
 ### Step 3: Create the Skill File
 
@@ -96,7 +96,7 @@ description: "<Verb1> X, <verb2> Y, and <verb3> Z. Use when <scenario1>, <scenar
 | **<related-skill>** skill | <What it contributes> |
 ```
 
-If the skill has large code examples (>30 lines), schema tables, or verbose reference material, create a companion `REFERENCE.md` in the same directory and link to it from SKILL.md. Keep SKILL.md as the lean operational overview. Companion files must start with a backlink: `> Parent: [SKILL.md](./SKILL.md)`.
+If skill has large code examples (>30 lines), schema tables, or verbose reference material, create companion `REFERENCE.md` in same directory; link to it from SKILL.md. Keep SKILL.md as lean operational overview. Companion files must start with backlink: `> Parent: [SKILL.md](./SKILL.md)`.
 
 ### Step 4: Register the Skill
 
@@ -104,30 +104,30 @@ Registration differs by type:
 
 #### Process Skill
 
-1. **Add to the skill matrix** — Add the skill name to the `directSkills` array of each relevant agent in `.opencastle/agents/skill-matrix.json`
-2. **Optional: reference in instructions** — If the skill should be loaded by default, add it to the appropriate `.github/instructions/` file
+1. **Add to skill matrix** — Add skill name to `directSkills` array of each relevant agent in `.opencastle/agents/skill-matrix.json`
+2. **Optional: reference in instructions** — If skill should load by default, add to appropriate `.github/instructions/` file
 
 #### Plugin Skill
 
-1. **Set `skillName` in the plugin's `config.ts`** — This connects the skill to the plugin
-2. **Update the skill matrix** — Add an entry to the matching capability slot's `entries` array in `.opencastle/agents/skill-matrix.json`
-3. **No agent changes needed** — Agents resolve plugin skills through capability slots automatically
+1. **Set `skillName` in plugin's `config.ts`** — Connects skill to plugin
+2. **Update skill matrix** — Add entry to matching capability slot's `entries` array in `.opencastle/agents/skill-matrix.json`
+3. **No agent changes** — Agents resolve plugin skills through capability slots automatically
 
 ### Step 5: Validate
 
-- [ ] File created at the correct path (`skills/` or `plugins/`)
+- [ ] File created at correct path (`skills/` or `plugins/`)
 - [ ] Frontmatter has `name` and `description` fields
-- [ ] Description is a single line (no line breaks)
-- [ ] Content follows the template structure
+- [ ] Description is single line (no line breaks)
+- [ ] Content follows template structure
 - [ ] No overlap with existing skills
 - [ ] Skill matrix updated (`directSkills` array or capability slot binding)
 - [ ] For process skills: at least one agent's `directSkills` array includes it in skill-matrix.json
-- [ ] For plugin skills: `config.ts` `skillName` matches the `name` in frontmatter
+- [ ] For plugin skills: `config.ts` `skillName` matches `name` in frontmatter
 - [ ] Run `npx tessl skill review <path>` — target 100 score (see Scoring Criteria below)
 
 ## Scoring Criteria
 
-Skills are evaluated by `npx tessl skill review` across 8 criteria (3 pts each = 24 total). Target 100.
+Skills evaluated by `npx tessl skill review` across 8 criteria (3 pts each = 24 total). Target 100.
 
 ### Description (frontmatter `description` field)
 
@@ -155,10 +155,10 @@ Skills are evaluated by `npx tessl skill review` across 8 criteria (3 pts each =
 - **Include executable examples** — At least one copy-paste-ready code block (5-15 lines). CLI commands with real flags, not placeholders
 - **Keep it scannable** — Tables over prose. Headings, bullets, code blocks. Agents parse structure, not paragraphs
 - **Number your workflows** — Every multi-step process needs numbered steps, checkpoints ("Gate: X passes"), and recovery ("Fail → fix → re-run step N")
-- **Don't explain what Claude knows** — Skip "what is X" explanations, obvious anti-pattern justifications, and concept definitions. Jump straight to the rules
-- **Avoid duplication** — If a rule exists in another skill or instruction file, reference it: "Load **security-hardening** skill for CSP configuration"
-- **Use REFERENCE.md for bulk** — Large code examples, schema tables, worked examples, and template libraries go in a companion `REFERENCE.md`. Link once from SKILL.md
+- **Don't explain what Claude knows** — Skip "what is X" explanations, obvious anti-pattern justifications, concept definitions. Jump straight to the rules
+- **Avoid duplication** — If rule exists in another skill or instruction file, reference it: "Load **security-hardening** skill for CSP configuration"
+- **Use REFERENCE.md for bulk** — Large code examples, schema tables, worked examples, template libraries go in companion `REFERENCE.md`. Link once from SKILL.md
 - **Stay stack-agnostic in process skills** — Use capability slot references ("the **database** skill" not "Supabase")
-- **Size target** — 80-200 lines in SKILL.md. Under 80 is too thin; over 200 should split content to REFERENCE.md. Over 300 should be split into multiple skills
-- **No standalone trigger-term sections** — Weave trigger terms naturally into the description's `Use when...` clause
+- **Size target** — 80-200 lines in SKILL.md. Under 80 too thin; over 200 split content to REFERENCE.md. Over 300 split into multiple skills
+- **No standalone trigger-term sections** — Weave trigger terms naturally into description's `Use when...` clause
 - **Third-person voice in descriptions** — "Creates X" not "Create X" or "This skill creates X"

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

@@ -1,5 +1,5 @@
 ---
-description: 'Fix validation errors in a convoy task plan by outputting targeted JSON patches.'
+description: 'Fix validation errors in convoy task plan by outputting targeted JSON patches.'
 agent: 'Team Lead (OpenCastle)'
 output: json
 ---
@@ -8,7 +8,7 @@ output: json
 
 # Fix Task Plan
 
-You are the Team Lead. The task plan below has validation errors. Fix every error by outputting targeted JSON patches.
+You are the Team Lead. Task plan below has validation errors. Fix every error by outputting targeted JSON patches.
 
 ## Task Plan
 
@@ -25,13 +25,13 @@ You are the Team Lead. The task plan below has validation errors. Fix every erro
 ## Instructions
 
 1. Read every error before writing patches.
-2. Fix ALL reported errors — do not partially fix.
-3. Preserve intent, agent assignments, and task scope. Only fix what is broken.
+2. Fix ALL reported errors; do not partially fix.
+3. Preserve intent, agent assignments, task scope. Only fix what is broken.
 4. Each patch replaces ONE field on ONE task.
 
 ## Patch Format
 
-Output a single `json` fenced code block with an array of patches:
+Output single `json` fenced code block with array of patches:
 
 ```json
 [
@@ -59,12 +59,12 @@ Output a single `json` fenced code block with an array of patches:
 - `value`: Complete new value (replaces old value entirely)
 
 ### Common fixes
-- **Truncated prompt** → patch `field: "prompt"` with the complete, self-contained prompt text
-- **Missing dependency** → patch `field: "depends_on"` with the corrected array
+- **Truncated prompt** → patch `field: "prompt"` with complete, self-contained prompt text
+- **Missing dependency** → patch `field: "depends_on"` with corrected array
 - **Partition conflict** → patch `field: "files"` to use specific paths, or patch `field: "depends_on"` to add sequencing
 - **Wrong agent** → patch `field: "agent"` with correct value from roster
 - **Vague prompt** → patch with detailed, file-specific prompt including acceptance criteria
 
 ## Output
 
-Your entire response must be a single `json` fenced code block with the patches array. No text before or after.
+Your entire response must be single `json` fenced code block with patches array. No text before or after.

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

@@ -1,5 +1,5 @@
 ---
-description: 'Fix validation errors in a PRD. Goal is the broken PRD markdown; context is the error list from the validation step.'
+description: 'Fix validation errors in PRD. Goal is broken PRD markdown; context is error list from validation step.'
 agent: 'Team Lead (OpenCastle)'
 output: prd
 ---
@@ -8,7 +8,7 @@ output: prd
 
 # Fix PRD
 
-You are the Team Lead. The PRD below failed validation. Fix **every reported issue** and output a complete, corrected PRD.
+You are the Team Lead. The PRD below failed validation. Fix **every reported issue**; output complete, corrected PRD.
 
 ## Failing PRD
 
@@ -23,31 +23,31 @@ You are the Team Lead. The PRD below failed validation. Fix **every reported iss
 ## Fix Instructions
 
 1. Read every reported issue before making changes.
-2. Fix **all** reported issues — do not partially fix.
-3. Do not change the intent, goals, or scope of the feature. Only fix what the validator flagged.
-4. Preserve all content that is not part of the reported issues.
+2. Fix **all** reported issues; do not partially fix.
+3. Do not change intent, goals, or scope of feature. Only fix what validator flagged.
+4. Preserve all content not part of reported issues.
 
 ### Common Fix Patterns
 
 **Missing sections**
-- Add the missing section with concrete, specific content — not placeholder text
-- If the section needs real data you cannot infer, write a reasonable default and mark with `<!-- TODO: verify -->`
+- Add missing section with concrete, specific content — not placeholder text
+- If section needs real data you cannot infer, write reasonable default; mark with `<!-- TODO: verify -->`
 
 **Conflicting requirements**
-- Resolve contradictions between sections — pick the intent that best matches the feature goals
+- Resolve contradictions between sections — pick intent that best matches feature goals
 
 **File partition conflicts**
-- If two parallel workstreams claim the same file, move one to a later phase with explicit dependency
-- Or split the file's responsibilities across the two workstreams so each touches distinct files
+- If two parallel workstreams claim same file, move one to later phase with explicit dependency
+- Or split file's responsibilities across two workstreams so each touches distinct files
 
 **Broad implementation scope**
 - Replace excessively broad paths (`src/`, `the frontend`) with specific subdirectories or file names
 
 **Placeholder text**
-- Replace template filler ("2–3 sentences about…", "Description here") with real content derived from the feature description
+- Replace template filler ("2–3 sentences about…", "Description here") with real content derived from feature description
 
 ---
 
 ## Output
 
-Return the **complete corrected PRD** as raw Markdown starting with the `#` heading. Do not wrap the output in a code fence. Do not add explanatory prose before or after the PRD.
+Return **complete corrected PRD** as raw Markdown starting with `#` heading. Do not wrap output in code fence. Do not add explanatory prose before or after PRD.

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

@@ -1,5 +1,5 @@
 ---
-description: 'Generate a JSON task plan for autonomous convoy execution based on a high-level goal.'
+description: 'Generate JSON task plan for autonomous convoy execution based on a high-level goal.'
 agent: 'Team Lead (OpenCastle)'
 output: json
 ---
@@ -8,7 +8,7 @@ output: json
 
 # Generate Task Plan
 
-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 JSON task plan. The CLI will convert it to a valid convoy spec — **you do not need to know YAML syntax**. Derive a short, descriptive, kebab-case filename from the user's goal (2–4 words max), e.g. `auth-refactor` or `add-search`.
+You are the Team Lead. User wants to run `opencastle run` to execute batch of tasks autonomously via convoy engine. Your job: produce JSON task plan. CLI will convert it to valid convoy spec — **you do not need to know YAML syntax**. Derive short, descriptive, kebab-case filename from user's goal (2–4 words max), e.g. `auth-refactor` or `add-search`.
 
 > **⚠️ OUTPUT FORMAT: Your entire response must be a single ` ```json ` fenced code block. Do NOT output any text, explanations, summaries, or DAG diagrams before or after the JSON block. The parser only reads the ` ```json ` fence — everything else causes a failure.**
 
@@ -56,9 +56,9 @@ You are the Team Lead. The user wants to run `opencastle run` to execute a batch
 
 ### Complexity Scores
 
-If a **Pre-Computed Task Complexity** table is present in the context, use those scores directly — do not re-derive them. Map each convoy task to the closest workstream; for combined workstreams use the highest score.
+If **Pre-Computed Task Complexity** table is present in context, use those scores directly — do not re-derive. Map each convoy task to closest workstream; for combined workstreams use highest score.
 
-If no pre-computed data is available, assess complexity yourself: `1` (trivial), `2` (simple), `3` (moderate), `5` (significant), `8` (complex), `13` (epic).
+If no pre-computed data available, assess complexity yourself: `1` (trivial), `2` (simple), `3` (moderate), `5` (significant), `8` (complex), `13` (epic).
 
 ### Agent Roster
 
@@ -68,16 +68,16 @@ If no pre-computed data is available, assess complexity yourself: `1` (trivial),
 
 ### Content Research Rule
 
-When writing task `prompt` fields that involve creating content about real-world people, places, organizations, or topics — **include an explicit instruction in the prompt** telling the agent to search the internet first using any available web search or fetch tools (e.g. `fetch_webpage`, web search MCP). Agents must never fabricate bios, descriptions, histories, statistics, or any factual claims. If web search is unavailable, the prompt should instruct the agent to use placeholder text clearly marked as `[NEEDS RESEARCH]` rather than inventing content.
+When writing task `prompt` fields involving creating content about real-world people, places, organizations, or topics — **include explicit instruction in prompt** telling agent to search internet first using available web search or fetch tools (e.g. `fetch_webpage`, web search MCP). Agents must never fabricate bios, descriptions, histories, statistics, or factual claims. If web search unavailable, prompt should instruct agent to use placeholder text clearly marked as `[NEEDS RESEARCH]` rather than inventing content.
 
-Example prompt suffix to include when content research is needed:
+Example prompt suffix when content research needed:
 > "Before writing any content about [topic], search the internet for accurate information. Do not make up facts, descriptions, or biographical details. Use verified sources only."
 
 ---
 
 ### Scaffolding Rule
 
-New project from scratch? You MUST load the **backbone-scaffolding** skill and follow it.
+New project from scratch? You MUST load **backbone-scaffolding** skill; follow it.
 
 ---
 
@@ -85,41 +85,41 @@ New project from scratch? You MUST load the **backbone-scaffolding** skill and f
 
 ### 1. Analyse the Goal
 
-- Read the user's goal. Identify the **deliverables** — what must exist or change after the run completes.
-- Search the codebase to understand current state, file layout, and conventions.
-- List the high-level workstreams (e.g. "database changes", "UI components", "tests", "docs").
+- Read user's goal. Identify **deliverables** — what must exist or change after run completes.
+- Search codebase to understand current state, file layout, conventions.
+- List high-level workstreams (e.g. "database changes", "UI components", "tests", "docs").
 
 ### 2. Decompose into Tasks
 
-For each workstream, break it down into the smallest meaningful unit. Follow these rules:
+For each workstream, break down into smallest meaningful unit. Follow these rules:
 
 1. **Single responsibility** — each task does exactly one thing.
-2. **Self-contained prompt** — the `prompt` field must contain everything the agent needs: objective, file paths, constraints, acceptance criteria. The agent has no other context.
-3. **Explicit file scopes** — list every directory or file the task may touch in `files`. Use plain paths only: exact file paths (e.g. `app/page.tsx`) or directory paths (e.g. `app/about/`). **Glob patterns (`*`, `?`, `**`) are not allowed** — the engine rejects them.
+2. **Self-contained prompt** — `prompt` field must contain everything agent needs: objective, file paths, constraints, acceptance criteria. Agent has no other context.
+3. **Explicit file scopes** — list every directory or file task may touch in `files`. Use plain paths only: exact file paths (e.g. `app/page.tsx`) or directory paths (e.g. `app/about/`). **Glob patterns (`*`, `?`, `**`) not allowed** — engine rejects them.
 
-4. **No partition conflicts** — two tasks may not share a `files` entry if they run in parallel (same phase). Resolve conflicts by either:
+4. **No partition conflicts** — two tasks may not share `files` entry if they run in parallel (same phase). Resolve by either:
    - **Specificity**: replace a broad directory path with the specific files each task actually creates (e.g., instead of both tasks claiming `components/`, one gets `components/Hero.tsx` and the other gets `components/ProjectCard.tsx`)
    - **Sequencing**: add a `depends_on` edge from the later task to the earlier one, so they run in different phases
 
-   > **Common mistake:** multiple tasks all depending on a single `setup` task will run in parallel and conflict if they share a directory like `components/`, `app/globals.css`, or `app/layout.tsx`. Always use specific file paths or sequence conflicting tasks.
+   > **Common mistake:** multiple tasks depending on single `setup` task will run in parallel, conflict if sharing directory like `components/`, `app/globals.css`, or `app/layout.tsx`. Always use specific file paths or sequence conflicting tasks.
 
-5. **Appropriate agent** — pick the agent whose speciality matches the task (e.g. `testing-expert` for tests, `database-engineer` for migrations).
+5. **Appropriate agent** — pick agent whose speciality matches task (e.g. `testing-expert` for tests, `database-engineer` for migrations).
 6. **Realistic timeouts** — `30m` for most tasks; `1h` for large refactors; `10m` for small docs or config.
 
 ### 2.5 Foundation Phase for Multi-Page Projects
 
-When the goal involves building **2 or more pages, views, or UI sections**, apply the Foundation-First Pattern to prevent consistency drift across parallel agents:
+When goal involves building **2 or more pages, views, or UI sections**, apply Foundation-First Pattern to prevent consistency drift across parallel agents:
 
-1. **Create a foundation task** (`id: foundation-setup`) as the FIRST task. This task:
+1. **Create foundation task** (`id: foundation-setup`) as FIRST task. This task:
    - Creates a **design tokens file** (CSS custom properties for colors, typography, spacing, motion, shadows, breakpoints)
    - Creates a **shared layout component** (page container with header, footer, navigation)
    - Creates a **UI component library** (Button, Card, Heading, Text, Section, Container, Grid)
-   - Establishes the **style guide** (aesthetic direction, content tone, terminology, navigation labels)
+   - Establishes **style guide** (aesthetic direction, content tone, terminology, navigation labels)
    - Agent: `ui-ux-expert` or `developer`
 
-2. **All page tasks must `depends_on: [foundation-setup]`** — they cannot run until the foundation is in place.
+2. **All page tasks must `depends_on: [foundation-setup]`** — cannot run until foundation in place.
 
-3. **Every page task prompt must include Foundation References** — these 5 mandatory lines constrain the agent to `use` existing artifacts instead of `creating` new ones:
+3. **Every page task prompt must include Foundation References** — 5 mandatory lines constrain agent to `use` existing artifacts instead of `creating` new ones:
    ```
    ### Foundation References (MANDATORY)
    - Design tokens: `[path to tokens file]` — use ONLY these variables. No new color/font/spacing values.
@@ -137,14 +137,14 @@ When the goal involves building **2 or more pages, views, or UI sections**, appl
    - The content tone (formal/casual, active/passive)
    - Terminology choices (e.g., "projects" not "portfolio")
 
-> **Why:** Without this pattern, parallel agents independently choose fonts, colors, component APIs, and content tone. The result looks like it was built by different teams — because it was. Foundation-first makes consistency structural, not aspirational.
+> **Why:** Without this pattern, parallel agents independently choose fonts, colors, component APIs, content tone. Result looks built by different teams — because it was. Foundation-first makes consistency structural, not aspirational.
 
 ### 3. Define the Dependency Graph (DAG)
 
 - Tasks with no dependencies run first (in parallel up to `concurrency`).
 - Tasks consuming output of earlier tasks declare `depends_on`.
 - **Never create cycles.**
-- Verify the implicit phase structure:
+- Verify implicit phase structure:
   ```
   Phase 1: [independent tasks]
   Phase 2: [tasks depending only on Phase 1]
@@ -152,22 +152,22 @@ When the goal involves building **2 or more pages, views, or UI sections**, appl
 
 ### 4. Set Global Options
 
-- `name` — short description of the run.
+- `name` — short description of run.
 - `branch` — derive from the goal, e.g. `feat/auth-refactor`.
-- `concurrency` — 2–3 for overnight runs; 1 if tasks share files or the machine is constrained.
-- `on_failure` — `stop` when every subsequent task depends on success; otherwise `continue`.
-- `gates` — standard validation (lint, type-check, test) unless the user specifies otherwise.
+- `concurrency` — 2–3 for overnight runs; 1 if tasks share files or machine is constrained.
+- `on_failure` — `stop` when every subsequent task depends on success; else `continue`.
+- `gates` — standard validation (lint, type-check, test) unless user specifies otherwise.
 
 ### 5. Write the Prompts
 
-Each task `prompt` must be a **complete, standalone instruction**. Include:
+Each task `prompt` must be **complete, standalone instruction**. Include:
 
 - **What** to build / change / fix.
 - **Where** — exact file paths or directories.
-- **Why** — business context so the agent can make good decisions.
+- **Why** — business context so agent can make good decisions.
 - **Constraints** — coding standards, conventions, do-not-touch files.
 - **Acceptance criteria** — bullet list of pass conditions.
-- **Verification command** — e.g. `Run the project's test command with coverage` so the agent self-checks.
+- **Verification command** — e.g. `Run project's test command with coverage` so the agent self-checks.
 
 > **Weak prompt:** "Add tests for the auth module."
 >
@@ -181,20 +181,20 @@ Each task `prompt` must be a **complete, standalone instruction**. Include:
 
 ### 6. Output
 
-Your response must contain **ONLY** a single ` ```json ` fenced code block — no text before it, no text after it, no explanations, no summaries, no DAG diagrams.
+Your response must contain **ONLY** single ` ```json ` fenced code block — no text before, no text after, no explanations, no summaries, no DAG diagrams.
 
 ---
 
 ## Chain Mode (Subset Generation)
 
-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 `{{context}}` as reference.
+When `{{goal}}` section contains "Convoy Group Scope" heading, you are generating ONE convoy spec that is part of a larger convoy chain. The goal will contain original user prompt, group name, description, phases to cover, dependency info. Full PRD available in `{{context}}` 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.
-- Derive the convoy `name` from the group name (e.g. "Database Setup").
-- Derive the `branch` from the PRD's feature name (it will be overridden by the pipeline anyway).
-- **Keep prompts concise** — write prompts that are complete and self-contained but avoid unnecessary verbosity. Focus on: what to do, which files to create/modify, key constraints, and acceptance criteria.
-- Keep all other conventions the same as for single-spec generation.
+- **Only** generate tasks for phases listed in group scope. Do not include tasks from other phases.
+- Derive convoy `name` from group name (e.g. "Database Setup").
+- Derive `branch` from PRD's feature name (overridden by pipeline anyway).
+- **Keep prompts concise** — write complete, self-contained prompts; avoid unnecessary verbosity. Focus on: what to do, which files to create/modify, key constraints, acceptance criteria.
+- Keep all other conventions same as for single-spec generation.
 
 ---
 
@@ -224,39 +224,39 @@ When chain mode is detected:
 
 ## Self-Validation Checklist (MANDATORY)
 
-Before outputting the JSON, verify **every item** below. The downstream validator will reject your plan if any blocking checks fail — fix them now to avoid expensive retry cycles.
+Before outputting JSON, verify **every item** below. Downstream validator will reject your plan if any blocking checks fail — fix them now to avoid expensive retry cycles.
 
 ### Structural Integrity
 
 - [ ] Every task has a unique `id` (lowercase, kebab-case)
-- [ ] Every `depends_on` reference points to a valid `id` defined in the task list
+- [ ] Every `depends_on` reference points to valid `id` defined in task list
 - [ ] No dependency cycles exist (DAG is acyclic)
 - [ ] No `files` entry contains `*`, `?`, or `**` — plain paths only
-- [ ] Top-level `name` and `tasks` fields are present; `tasks` is non-empty
-- [ ] Every task has both `id` and `prompt` fields (both non-empty strings)
+- [ ] Top-level `name`, `tasks` fields present; `tasks` non-empty
+- [ ] Every task has both `id`, `prompt` fields (both non-empty strings)
 
 ### Partition & Dependency Coherence
 
 - [ ] No two parallel tasks (same phase / no `depends_on` edge) share any `files` entry — resolve with specific file paths or sequencing
-- [ ] **Dependency completeness**: For every task prompt, scan for imports or references to files/types/components produced by other tasks. Each cross-reference MUST have a `depends_on` edge to the producing task.
-- [ ] **File list completeness**: Every file mentioned in a task's prompt that the agent will create or modify appears in that task's `files` list. Don't omit utility files, sub-components, or config files.
+- [ ] **Dependency completeness**: For every task prompt, scan for imports or references to files/types/components produced by other tasks. Each cross-reference MUST have `depends_on` edge to producing task.
+- [ ] **File list completeness**: Every file mentioned in task's prompt that agent will create or modify appears in that task's `files` list. Don't omit utility files, sub-components, or config files.
 - [ ] **Prompt-dependency coherence**: Prompts do not include workarounds (stub files, `@ts-expect-error`, conditional imports) for outputs of tasks listed in `depends_on`, since those outputs are guaranteed to exist.
 
 ### Prompt Quality
 
-- [ ] **Self-contained**: An agent with zero context can execute the prompt without external clarification.
-- [ ] **File-specific**: Names the exact files to create or modify — no vague references ("the frontend", "the codebase").
+- [ ] **Self-contained**: Agent with zero context can execute prompt without external clarification.
+- [ ] **File-specific**: Names exact files to create or modify — no vague references ("the frontend", "the codebase").
 - [ ] **Substantive**: At least 2 meaningful sentences; no stubs (`...`), no placeholders.
 - [ ] **Verifiable**: Contains acceptance criteria or explicit verification steps.
-- [ ] **Agent domain matching**: Each task's `agent` matches the domain — `developer` for code, `testing-expert` for tests, `documentation-writer` for docs, `copywriter` for marketing copy, `ui-ux-expert` for UI, `database-engineer` for migrations, `security-expert` for auth/security, `data-expert` for ETL/scraping.
-- [ ] **Content research compliance**: If a prompt concerns real people, places, or organisations, it includes a research instruction.
-- [ ] **Foundation phase present** (multi-page only): If 2+ pages/UI sections, a `foundation-setup` task exists and all page tasks depend on it with the 5 mandatory Foundation References.
+- [ ] **Agent domain matching**: Each task's `agent` matches domain — `developer` for code, `testing-expert` for tests, `documentation-writer` for docs, `copywriter` for marketing copy, `ui-ux-expert` for UI, `database-engineer` for migrations, `security-expert` for auth/security, `data-expert` for ETL/scraping.
+- [ ] **Content research compliance**: If prompt concerns real people, places, or organisations, includes research instruction.
+- [ ] **Foundation phase present** (multi-page only): If 2+ pages/UI sections, `foundation-setup` task exists; all page tasks depend on it with 5 mandatory Foundation References.
 
 ---
 
 ## Historical Performance Context
 
-When historical execution data is available (via `opencastle insights --json`), the Team Lead should include a compact summary in the context. Example:
+When historical execution data available (via `opencastle insights --json`), Team Lead should include compact summary in context. Example:
 
 ### Historical Performance (auto-generated)
 Based on {N} past convoys:
@@ -264,5 +264,5 @@ Based on {N} past convoys:
 - Recommended concurrency for {task_count} tasks: {recommended}
 - Agents to watch: {high_retry_agents}
 
-Use this data to make evidence-based decisions about agent assignment, concurrency, and timeout settings.
+Use this data to make evidence-based decisions about agent assignment, concurrency, timeout settings.
 

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

@@ -1,5 +1,5 @@
 ---
-description: 'Generate a Product Requirements Document from a high-level feature prompt. Output feeds directly into the generate-convoy step.'
+description: 'Generate Product Requirements Document from high-level feature prompt. Output feeds directly into generate-convoy step.'
 agent: 'Team Lead (OpenCastle)'
 output: prd
 ---
@@ -8,9 +8,9 @@ output: prd
 
 # Generate PRD
 
-You are the Team Lead. Convert the feature request below into a structured Product Requirements Document (PRD). The PRD will be consumed by the `generate-convoy` step to produce an automated agent task spec, so every section must be **concrete**, **specific**, and **implementation-ready**.
+You are the Team Lead. Convert the feature request below into structured Product Requirements Document (PRD). PRD consumed by `generate-convoy` step to produce automated agent task spec, so every section must be **concrete**, **specific**, **implementation-ready**.
 
-> **⚠ QUALITY GATE:** This PRD goes through automated validation. Getting it right on the first attempt is critical — every fix cycle costs a full LLM round-trip. Follow ALL rules below precisely. The self-validation checklist at the end is mandatory.
+> **⚠ QUALITY GATE:** This PRD goes through automated validation. Getting it right on first attempt is critical — every fix cycle costs a full LLM round-trip. Follow ALL rules below precisely. Self-validation checklist at end is mandatory.
 
 ## Feature Request
 
@@ -24,24 +24,24 @@ You are the Team Lead. Convert the feature request below into a structured Produ
 
 ## Research Before Writing
 
-If the feature request involves a specific person, place, organization, topic, or any real-world subject:
+If feature request involves specific person, place, organization, topic, or any real-world subject:
 
-1. **Search the internet first** if web search or fetch tools are available (e.g. `fetch_webpage`, web search MCP, or similar). Use the search results to gather accurate facts, names, dates, descriptions, and other details.
-2. **If web search tools are unavailable or return no useful results**, you may use your training knowledge — but clearly mark any such content with:
+1. **Search the internet first** if web search or fetch tools available (e.g. `fetch_webpage`, web search MCP, or similar). Use the search results to gather accurate facts, names, dates, descriptions, and other details.
+2. **If web search tools unavailable or return no useful results**, you may use your training knowledge — but clearly mark any such content with:
    > ℹ️ 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.
+3. **Never fabricate or hallucinate content.** If you have no knowledge about real-world subject and cannot search, state what is unknown; use placeholder text. Applies to all content: bios, descriptions, histories, statistics, quotes, any factual claims.
 
 ## Scaffolding Awareness
 
-New project from scratch? You MUST load the **backbone-scaffolding** skill and follow it.
+New project from scratch? You MUST load **backbone-scaffolding** skill; follow it.
 
 ## 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.
+**CRITICAL:** Return the PRD as your text response. Do NOT create any files. Do NOT use file-writing tools. Output full PRD document as text. Do not wrap in code fence — start directly with `#` heading. Do not summarize — output complete document.
 
 ## Required PRD Structure
 
-Produce the PRD in Markdown using **exactly** the sections below. Do not skip or merge sections.
+Produce PRD in Markdown using **exactly** sections below. Do not skip or merge sections.
 
 ---
 
@@ -49,22 +49,22 @@ Produce the PRD in Markdown using **exactly** the sections below. Do not skip or
 
 ## Overview
 
-2–3 sentences: what this feature does, who benefits, and why it matters now.
+2–3 sentences: what this feature does, who benefits, why it matters now.
 
 ## Goals
 
-Numbered list of specific, measurable outcomes this feature must achieve. Each goal should be a single sentence with a clear success condition.
+Numbered list of specific, measurable outcomes this feature must achieve. Each goal: single sentence with clear success condition.
 
 1. …
 2. …
 
 ## Non-Goals
 
-Explicit exclusions — what this work does **not** cover. If nothing is excluded, write "None."
+Explicit exclusions — what this work does **not** cover. If nothing excluded, write "None."
 
 ## User Stories & Acceptance Criteria
 
-For each primary scenario, write a user story + binary acceptance criteria. Criteria must be testable (pass/fail — no subjective language).
+For each primary scenario, write 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")
@@ -83,7 +83,7 @@ Acceptance criteria:
 
 ## Technical Requirements
 
-Specific technical constraints the implementation must respect:
+Specific technical constraints implementation must respect:
 - Libraries, framework versions to use or avoid
 - API contracts or interfaces that must not break
 - Performance thresholds (e.g., "<200 ms p95 latency")
@@ -92,7 +92,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. 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.
+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 sharing a concern. Do NOT use glob patterns (`*`, `**`). Every concern must list at least one specific file.
 
 | Concern | Files / Directories |
 |---------|---------------------|
@@ -104,18 +104,18 @@ List **every file and directory** that will be created, modified, or deleted. Us
 | [Config / env] | `.env.example` |
 
 **File partition rules (important for parallel execution):**
-- No two concurrent workstreams may modify the same file
-- If two workstreams need the same file, they must be sequenced (Phase N+1 after Phase N)
+- No two concurrent workstreams may modify same file
+- If two workstreams need same file, must be sequenced (Phase N+1 after Phase N)
 
 ## Task Breakdown
 
-Decompose into the minimum number of phases. Tasks in the same phase run in parallel and **must not share any files**.
+Decompose into minimum number of phases. Tasks in same phase run in parallel; **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
+- No two parallel workstreams (same phase) may claim same file
 - Phases must have explicit dependency declarations (`depends on: Phase N`)
 - No circular dependencies
 
@@ -138,8 +138,8 @@ Phase 3 — Verification (depends on Phase 2):
 
 ## Success Criteria
 
-Measurable, binary checks that confirm the feature is shippable:
-- [ ] All acceptance criteria in User Stories & Acceptance Criteria pass
+Measurable, binary checks confirming feature is shippable:
+- [ ] All acceptance criteria in User Stories All acceptance criteria in User Stories & Acceptance Criteria pass Acceptance Criteria pass
 - [ ] TypeScript compiles with zero errors
 - [ ] Lint passes with zero warnings
 - [ ] Unit test coverage ≥ 95% on all new/changed files
@@ -150,31 +150,31 @@ Measurable, binary checks that confirm the feature is shippable:
 - **[Risk title]**: [Description of the risk] — *Mitigation: [How to handle it]*
 - **[Open question]**: [What needs to be decided before implementation can start]
 
-If there are no risks or open questions, write "None identified."
+If no risks or open questions, write "None identified."
 
 ---
 
 ## Self-Validation Checklist (MANDATORY)
 
-Before outputting the PRD, verify **every item** below. The downstream validator will reject your PRD if any of the blocking checks fail — fix them now to avoid expensive retry cycles.
+Before outputting PRD, verify **every item** below. Downstream validator will reject your PRD if any blocking checks fail — fix them now to avoid expensive retry cycles.
 
 ### Structural Integrity
 
-- [ ] **No conflicting requirements**: Technical Requirements, Non-Goals, Risks & Open Questions, and User Stories must not contradict each other.
-- [ ] **No duplicate open questions**: If a question is already answered elsewhere, do not re-open it in Risks & Open Questions.
+- [ ] **No conflicting requirements**: Technical Requirements, Non-Goals, Risks **No conflicting requirements**: Technical Requirements, Non-Goals, Risks & Open Questions, and User Stories must not contradict each other. Open Questions, User Stories must not contradict each other.
+- [ ] **No duplicate open questions**: If question already answered elsewhere, do not re-open in Risks **No duplicate open questions**: If a question is already answered elsewhere, do not re-open it in Risks & Open Questions. Open Questions.
 - [ ] **No circular dependencies**: Phase dependency graph is acyclic.
 - [ ] **No placeholder text**: Every section has real content, not template filler ("2–3 sentences about…", "Description here").
 
 ### Implementation Coherence
 
-- [ ] **File completeness**: Every file mentioned in User Story acceptance criteria or Technical Requirements appears in the Implementation Scope table AND in the Task Breakdown file lists.
-- [ ] **No file partition conflicts**: No two parallel workstreams (same phase) claim the same file.
-- [ ] **Every workstream lists files**: Including verification-only workstreams — add "Files: none — verification only" if no artifacts are produced.
-- [ ] **No orphan files**: Every file in the Implementation Scope table is assigned to exactly one workstream in Task Breakdown.
+- [ ] **File completeness**: Every file mentioned in User Story acceptance criteria or Technical Requirements appears in Implementation Scope table AND in Task Breakdown file lists.
+- [ ] **No file partition conflicts**: No two parallel workstreams (same phase) claim same file.
+- [ ] **Every workstream lists files**: Including verification-only workstreams — add "Files: none — verification only" if no artifacts produced.
+- [ ] **No orphan files**: Every file in Implementation Scope table is assigned to exactly one workstream in Task Breakdown.
 - [ ] **Scope specificity**: Implementation Scope uses specific subdirectory or file paths — not just `src/` or `the frontend`.
 
 ### Language Quality
 
 - [ ] **Testable acceptance criteria**: Every criterion is evaluable as deterministic pass/fail — no subjective language ("looks good", "feels responsive").
-- [ ] **No optional modals in criteria**: Acceptance criteria do not use "should", "might", "could", "may" — use "must" or "will".
-- [ ] **Domain acronyms expanded**: Non-standard acronyms are expanded on first use (standard ones like API, CLI, JSON, REST, etc. are fine).
+- [ ] **No optional modals**: Acceptance criteria do not use "should", "might", "could", "may" — use "must" or "will".
+- [ ] **Domain acronyms expanded**: Non-standard acronyms expanded on first use (standard ones like API, CLI, JSON, REST, etc. fine).