opencastle 0.30.0 → 0.31.0

package/src/cli/plan.ts

@@ -2,10 +2,11 @@ import { readFile } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { resolve, join, basename } from 'node:path'
 import { mkdir, writeFile } from 'node:fs/promises'
-import { getAdapter, detectAdapter } from './run/adapters/index.js'
+import { getAdapter, detectAdapter, cleanupAdapters } from './run/adapters/index.js'
 import { parseTaskSpecText } from './run/schema.js'
 import { c } from './prompt.js'
 import type { CliContext, Task } from './types.js'
+import type { MCPServerConfig } from './convoy/types.js'
 
 const HELP = `
   opencastle plan [options]
@@ -18,11 +19,13 @@ const HELP = `
     --text, -t <text>        Inline text to use as {{goal}} (alternative to --file)
     --template <name>        Prompt template name (default: generate-convoy)
                              Built-in templates:
-                               generate-prd      — Write a PRD from a feature prompt
-                               validate-prd      — Check a PRD for completeness
-                               generate-convoy   — Generate a convoy spec from a PRD (default)
-                               validate-convoy   — Check a convoy spec for correctness
-                               fix-convoy        — Fix validation errors in a convoy spec
+                               generate-prd        — Write a PRD from a feature prompt
+                               validate-prd        — Check a PRD for completeness
+                               fix-prd             — Fix validation errors in a PRD
+                               assess-complexity   — Assess PRD complexity (returns JSON)
+                               generate-convoy     — Generate a convoy spec from a PRD (default)
+                               validate-convoy     — Check a convoy spec for correctness
+                               fix-convoy          — Fix validation errors in a convoy spec
     --context <path>         Optional path to an additional context file (fills {{context}})
     --context-text <text>    Inline text to fill {{context}} (alternative to --context)
     --output, -o <path>      Output path override (skipped for validation output)
@@ -66,6 +69,8 @@ export interface PromptStepOptions {
   dryRun?: boolean
   /** Absolute path to the opencastle package root (for locating prompt templates) */
   pkgRoot: string
+  /** MCP servers to make available to the AI adapter during execution. */
+  mcpServers?: MCPServerConfig[]
 }
 
 export interface PromptStepResult {
@@ -74,7 +79,7 @@ export interface PromptStepResult {
   /** Raw text returned by the AI adapter (or assembled prompt on dry-run) */
   rawOutput: string
   /** How the output was interpreted */
-  outputType: 'convoy-spec' | 'prd' | 'validation'
+  outputType: 'convoy-spec' | 'prd' | 'validation' | 'json'
   /** Set when outputType === 'validation' */
   isValid?: boolean
   /** Set when outputType === 'validation' and isValid === false */
@@ -147,9 +152,19 @@ function parseFrontmatter(text: string): Record<string, string> {
 
 /** Extract YAML content from a fenced ```yaml ... ``` block. */
 function extractYamlBlock(text: string): string | null {
-  const match = text.match(/```ya?ml\s*\n([\s\S]*?)```/)
-  if (!match) return null
-  return match[1].trim()
+  // 1. Prefer explicit yaml/yml fence
+  const yamlFence = text.match(/```ya?ml\s*\n([\s\S]*?)```/)
+  if (yamlFence) return yamlFence[1].trim()
+
+  // 2. Fallback: any code fence whose content looks like a convoy spec
+  //    Must contain at least `name:` AND `tasks:` to avoid false positives
+  const genericFences = [...text.matchAll(/```\s*\n([\s\S]*?)```/g)]
+  for (const m of genericFences) {
+    const content = m[1].trim()
+    if (/^name:/m.test(content) && /^tasks:/m.test(content)) return content
+  }
+
+  return null
 }
 
 /**
@@ -221,6 +236,34 @@ function parseValidationResult(output: string): { isValid: boolean; errors: stri
   return { isValid: false, errors: errorsMatch ? errorsMatch[1].trim() : trimmed }
 }
 
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
+
+const TEMPLATE_MESSAGES: Record<string, string> = {
+  'generate-prd': 'Generating PRD…',
+  'generate-convoy': 'Generating convoy spec…',
+  'validate-prd': 'Validating PRD…',
+  'validate-convoy': 'Validating convoy spec…',
+  'fix-prd': 'Fixing PRD…',
+  'fix-convoy': 'Fixing convoy spec…',
+}
+
+/** Show an in-place spinner with elapsed time during a long-running adapter call. Returns a stop function. */
+function startProgress(templateName: string): () => void {
+  const message = TEMPLATE_MESSAGES[templateName] ?? `Running ${templateName}…`
+  const startTime = Date.now()
+  let frame = 0
+  const interval = setInterval(() => {
+    const elapsed = Math.floor((Date.now() - startTime) / 1000)
+    const spinner = SPINNER_FRAMES[frame % SPINNER_FRAMES.length]!
+    process.stdout.write(c.dim(`\r  ${spinner} ${message} (${elapsed}s)`))
+    frame++
+  }, 250)
+  return () => {
+    clearInterval(interval)
+    process.stdout.write('\r' + ' '.repeat(60) + '\r')
+  }
+}
+
 // ── Exported programmatic API ───────────────────────────────────────────────
 
 /**
@@ -243,7 +286,7 @@ export async function runPromptStep(opts: PromptStepOptions): Promise<PromptStep
 
   const rawTemplate = await readFile(templatePath, 'utf8')
   const frontmatter = parseFrontmatter(rawTemplate)
-  const outputType = (frontmatter['output'] ?? 'convoy-spec') as 'convoy-spec' | 'prd' | 'validation'
+  const outputType = (frontmatter['output'] ?? 'convoy-spec') as 'convoy-spec' | 'prd' | 'validation' | 'json'
   const template = stripFrontmatter(rawTemplate)
 
   let goalContent = opts.goalText ?? ''
@@ -303,7 +346,16 @@ export async function runPromptStep(opts: PromptStepOptions): Promise<PromptStep
     max_retries: 1,
   }
 
-  const execResult = await adapter.execute(task, { verbose: opts.verbose ?? false })
+  const stop = opts.verbose ? null : startProgress(templateName)
+  let execResult
+  try {
+    execResult = await adapter.execute(task, {
+      verbose: opts.verbose ?? false,
+      ...(opts.mcpServers?.length ? { mcpServers: opts.mcpServers } : {}),
+    })
+  } finally {
+    stop?.()
+  }
   const rawOutput = execResult.output
 
   if (outputType === 'validation') {
@@ -311,6 +363,18 @@ export async function runPromptStep(opts: PromptStepOptions): Promise<PromptStep
     return { outputPath: null, rawOutput, outputType, isValid, errors }
   }
 
+  if (outputType === 'json') {
+    // Extract JSON from fenced block or raw output
+    const jsonMatch = rawOutput.match(/```(?:json)?\s*\n([\s\S]*?)```/)
+    const jsonContent = jsonMatch ? jsonMatch[1].trim() : rawOutput.trim()
+    const outputPath = opts.outputPath ?? null
+    if (outputPath) {
+      await mkdir(resolve(outputPath, '..'), { recursive: true })
+      await writeFile(outputPath, jsonContent + '\n', 'utf8')
+    }
+    return { outputPath, rawOutput: jsonContent, outputType }
+  }
+
   if (outputType === 'prd') {
     const content = extractMarkdownBody(rawOutput)
     let outputPath = opts.outputPath ?? null
@@ -355,6 +419,48 @@ export async function runPromptStep(opts: PromptStepOptions): Promise<PromptStep
   return { outputPath, rawOutput, outputType, isValid: schemaValid }
 }
 
+/**
+ * Read MCP server configurations from the project's MCP config file.
+ * Checks in priority order: .vscode/mcp.json, .cursor/mcp.json, .claude/mcp.json, mcp.json
+ */
+export async function readProjectMcpServers(projectRoot: string): Promise<MCPServerConfig[]> {
+  const candidates = [
+    join(projectRoot, '.vscode', 'mcp.json'),
+    join(projectRoot, '.cursor', 'mcp.json'),
+    join(projectRoot, '.claude', 'mcp.json'),
+    join(projectRoot, 'mcp.json'),
+  ]
+
+  for (const filePath of candidates) {
+    if (!existsSync(filePath)) continue
+    try {
+      const raw = await readFile(filePath, 'utf8')
+      const parsed = JSON.parse(raw) as Record<string, unknown>
+
+      // VS Code format: { servers: { name: { type, command, args } } }
+      // Cursor/Claude format: { mcpServers: { name: { command, args } } }
+      const serversMap =
+        (parsed['servers'] as Record<string, unknown> | undefined) ??
+        (parsed['mcpServers'] as Record<string, unknown> | undefined)
+
+      if (!serversMap || typeof serversMap !== 'object') continue
+
+      return Object.entries(serversMap).map(([name, cfg]) => {
+        const c = cfg as Record<string, unknown>
+        const server: MCPServerConfig = { name, type: (c['type'] as string) ?? 'stdio' }
+        if (typeof c['command'] === 'string') server.command = c['command']
+        if (Array.isArray(c['args'])) server.args = c['args'] as string[]
+        if (typeof c['url'] === 'string') server.url = c['url']
+        return server
+      })
+    } catch {
+      return []
+    }
+  }
+
+  return []
+}
+
 // ── CLI argument parsing ────────────────────────────────────────────────────
 
 function parseArgs(args: string[]): PlanOptions {
@@ -503,6 +609,16 @@ export default async function plan({ args, pkgRoot }: CliContext): Promise<void>
       console.log(`\n  ${c.dim('Next step:')} opencastle plan --file ${relPath} --template validate-prd`)
       break
     }
+    case 'json': {
+      if (result.outputPath) {
+        const relP = result.outputPath.startsWith(process.cwd())
+          ? result.outputPath.slice(process.cwd().length + 1)
+          : result.outputPath
+        console.log(c.green(`  ✓ JSON written to ${relP}`))
+      }
+      console.log(result.rawOutput)
+      break
+    }
     default: {
       const relPath = result.outputPath!.startsWith(process.cwd())
         ? result.outputPath!.slice(process.cwd().length + 1)
@@ -517,4 +633,6 @@ export default async function plan({ args, pkgRoot }: CliContext): Promise<void>
 `)
     }
   }
+
+  await cleanupAdapters()
 }

package/src/cli/run/adapters/copilot.ts

@@ -108,7 +108,7 @@ async function executeViaSdk(task: Task, options: ExecuteOptions = {}): Promise<
     } : undefined
     return {
       success: true,
-      output: output.slice(0, 10_000),
+      output: output.slice(0, 100_000),
       exitCode: 0,
       usage: usageResult,
     }
@@ -246,3 +246,13 @@ export function kill(task: Task): void {
   if (mode === 'sdk') killSdk(task)
   else killCli(task)
 }
+
+export async function cleanup(): Promise<void> {
+  if (clientPromise) {
+    try {
+      const client = await clientPromise
+      await client.stop()
+    } catch { /* ignore */ }
+    clientPromise = null
+  }
+}

package/src/cli/run/adapters/index.ts

@@ -45,6 +45,19 @@ export async function detectAdapter(): Promise<string | null> {
   return null
 }
 
+/**
+ * Clean up all loaded adapters (stop SDK clients, close connections).
+ * Call this before process exit to avoid hanging.
+ */
+export async function cleanupAdapters(): Promise<void> {
+  for (const loader of Object.values(ADAPTERS)) {
+    try {
+      const mod = await loader()
+      await mod.cleanup?.()
+    } catch { /* ignore */ }
+  }
+}
+
 /**
  * List all registered adapters with their availability status.
  */

package/src/cli/run.ts

@@ -756,6 +756,31 @@ export default async function run({ args, pkgRoot }: CliContext): Promise<void>
     if (spec.branch) console.log(`  Branch: ${spec.branch}`)
     if (spec.gates?.length) console.log(`  Gates: ${spec.gates.length} validation commands`)
 
+    // ── Pre-flight: handle uncommitted changes before branch switch ──
+    let pipelineDidStash = false
+    if (spec.branch) {
+      const { execFile: execFileCb } = await import('node:child_process')
+      const { promisify } = await import('node:util')
+      const execFile = promisify(execFileCb)
+      const { stdout: statusOut } = await execFile('git', ['status', '--porcelain'], {
+        cwd: process.cwd(),
+      })
+      if (statusOut.trim()) {
+        console.log(`\n  ${c.yellow('⚠')} Uncommitted changes detected.`)
+        const shouldStash = await confirm('Stash changes and continue?', true)
+        if (!shouldStash) {
+          console.log('  Aborted. Commit or stash your changes manually, then retry.')
+          closePrompts()
+          process.exit(1)
+        }
+        await execFile('git', ['stash', 'push', '-m', 'opencastle: auto-stash before pipeline'], {
+          cwd: process.cwd(),
+        })
+        pipelineDidStash = true
+        console.log(`  ${c.green('✓')} Changes stashed.`)
+      }
+    }
+
     const { startDashboardServer } = await import('./dashboard.js')
     let pipelineDashboardResult: { server: import('node:http').Server; port: number; url: string } | null = null
     try {
@@ -789,12 +814,31 @@ export default async function run({ args, pkgRoot }: CliContext): Promise<void>
       throw err
     }
     printPipelineResult(pipelineResult)
+    if (pipelineDidStash) {
+      const { execFile: execFileCb } = await import('node:child_process')
+      const { promisify } = await import('node:util')
+      const execFile = promisify(execFileCb)
+      try {
+        await execFile('git', ['stash', 'pop'], { cwd: process.cwd() })
+        console.log(`  ${c.green('✓')} Stashed changes restored.`)
+      } catch {
+        console.log(`  ${c.yellow('⚠')} Could not restore stash automatically. Run \`git stash pop\` manually.`)
+      }
+    }
     if (pipelineDashboardResult) {
       console.log(`\n  ${c.dim('Results saved to .opencastle/convoy.db')}`)
-      console.log(`  ${c.dim('View again:')} opencastle dashboard`)
-      pipelineDashboardResult.server.close()
+      console.log(`  ${c.dim('Dashboard:')} ${pipelineDashboardResult.url}`)
+      console.log(`\n  Press Ctrl+C to stop`)
+      const exitCode = pipelineResult.status !== 'done' ? 1 : 0
+      process.on('SIGINT', () => {
+        console.log('\n  Dashboard stopped.\n')
+        pipelineDashboardResult!.server.close()
+        process.exit(exitCode)
+      })
+    } else {
+      process.exit(pipelineResult.status !== 'done' ? 1 : 0)
     }
-    process.exit(pipelineResult.status !== 'done' ? 1 : 0)
+    return
   }
 
   // ── Convoy engine path (version: 1 specs) ────────────────────
@@ -882,11 +926,6 @@ export default async function run({ args, pkgRoot }: CliContext): Promise<void>
       throw err
     }
     printConvoyResult(result)
-    if (dashboardResult) {
-      console.log(`\n  ${c.dim('Results saved to .opencastle/convoy.db')}`)
-      console.log(`  ${c.dim('View again:')} opencastle dashboard`)
-      dashboardResult.server.close()
-    }
     if (didStash) {
       const { execFile: execFileCb } = await import('node:child_process')
       const { promisify } = await import('node:util')
@@ -898,7 +937,19 @@ export default async function run({ args, pkgRoot }: CliContext): Promise<void>
         console.log(`  ${c.yellow('⚠')} Could not restore stash automatically. Run \`git stash pop\` manually.`)
       }
     }
-    process.exit(result.status !== 'done' ? 1 : 0)
+    if (dashboardResult) {
+      console.log(`\n  ${c.dim('Results saved to .opencastle/convoy.db')}`)
+      console.log(`  ${c.dim('Dashboard:')} ${dashboardResult.url}`)
+      console.log(`\n  Press Ctrl+C to stop`)
+      const exitCode = result.status !== 'done' ? 1 : 0
+      process.on('SIGINT', () => {
+        console.log('\n  Dashboard stopped.\n')
+        dashboardResult!.server.close()
+        process.exit(exitCode)
+      })
+    } else {
+      process.exit(result.status !== 'done' ? 1 : 0)
+    }
   }
 
   // ── Legacy executor path ──────────────────────────────────────

package/src/cli/types.ts

@@ -300,6 +300,8 @@ export interface AgentAdapter {
   kill?(_task: Task): void;
   /** Whether the adapter supports reusing sessions across multi-step task steps. Defaults to false. */
   supportsSessionContinuity?(): boolean;
+  /** Clean up any long-lived resources (SDK clients, open connections) so the process can exit. */
+  cleanup?(): Promise<void>;
 }
 
 /** Options for agent execution. */

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

@@ -1,25 +1,25 @@
 {
-  "hash": "572e36d2",
+  "hash": "92391349",
   "configHash": "30f8ea04",
-  "lockfileHash": "197646b6",
-  "browserHash": "744352ae",
+  "lockfileHash": "f32f6327",
+  "browserHash": "a3143d98",
   "optimized": {
     "astro > cssesc": {
       "src": "../../../../../node_modules/cssesc/cssesc.js",
       "file": "astro___cssesc.js",
-      "fileHash": "15f42bbc",
+      "fileHash": "4da4d2a1",
       "needsInterop": true
     },
     "astro > aria-query": {
       "src": "../../../../../node_modules/aria-query/lib/index.js",
       "file": "astro___aria-query.js",
-      "fileHash": "0bfdb9ce",
+      "fileHash": "65e6b113",
       "needsInterop": true
     },
     "astro > axobject-query": {
       "src": "../../../../../node_modules/axobject-query/lib/index.js",
       "file": "astro___axobject-query.js",
-      "fileHash": "97401cc3",
+      "fileHash": "bd7268ed",
       "needsInterop": true
     }
   },

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

@@ -22,13 +22,20 @@ 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 you are not confident you have accurate knowledge about — **you MUST search the internet first** using any available web search or fetch tools (e.g. `fetch_webpage`, web search MCP, or similar). Use the search results to gather accurate facts, names, dates, descriptions, and other details.
+If the feature request involves a specific person, place, organization, topic, or any real-world subject:
 
-**Never fabricate or hallucinate content** about real-world subjects. If you cannot verify a claim through web search, state what is unknown rather than inventing plausible-sounding text. This applies to all content: bios, descriptions, histories, statistics, quotes, and any factual claims.
+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:
+   > ℹ️ 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.
 
 ---
 
@@ -53,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].
 
@@ -73,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 |
 |---------|---------------------|
@@ -92,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]
@@ -124,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")