prizmkit 1.1.57 → 1.1.60

package/bundled/dev-pipeline-windows/assets/prizm-dev-team-integration.md

@@ -0,0 +1,138 @@
+# prizm-dev-team Integration Guide
+
+## Overview
+
+dev-pipeline drives the prizm-dev-team multi-agent team through an outer shell loop. Each iteration spawns a new AI CLI session with a bootstrap prompt that instructs the agent to create and orchestrate the team for one feature.
+
+## Architecture
+
+```
+dev-pipeline (outer loop)
+    │
+    ├── run-feature.ps1                    PowerShell runner — picks next feature, spawns CLI
+    ├── scripts/                  Python state management scripts
+    ├── templates/bootstrap-prompt.md  Session prompt template
+    │
+    └── [per session] AI CLI
+            │
+            ├── Phase 0: Init (Orchestrator)
+            ├── Phase 1-2: Context snapshot + Specify + Plan (Orchestrator)
+            ├── Phase 3: Analyze (Reviewer agent) [tier2] / Phase 4: Analyze [tier3]
+            ├── Phase 4: Implement (Dev agent) [tier2] / Phase 5: Implement [tier3]
+            ├── Phase 4.5/6: Review (Reviewer agent)
+            └── Phase 5/7: Retrospective & Commit (Orchestrator)
+            │
+            └── Write session-status.json → exit
+```
+
+## Agent Definitions (Source of Truth)
+
+| Agent | Definition Path | Type |
+|-------|----------------|------|
+| Dev | `.claude/agents/prizm-dev-team-dev.md` (or `.codebuddy/agents/`) | prizm-dev-team-dev |
+| Reviewer | `.claude/agents/prizm-dev-team-reviewer.md` (or `.codebuddy/agents/`) | prizm-dev-team-reviewer |
+| Critic | `.claude/agents/prizm-dev-team-critic.md` (or `.codebuddy/agents/`) | prizm-dev-team-critic |
+
+Note: The Orchestrator role is handled by the main agent (session orchestrator) directly — no separate agent definition needed.
+
+## Pipeline Scripts
+
+Located at `.prizmkit/dev-pipeline/scripts/`:
+
+| Script | Purpose |
+|--------|---------|
+| `init-dev-team.py` | Initialize `.dev-team/` + `.prizmkit/` directories |
+| `init-pipeline.py` | Initialize pipeline state directories and config |
+| `init-bugfix-pipeline.py` | Initialize bugfix pipeline state |
+| `generate-bootstrap-prompt.py` | Render tier-specific bootstrap prompt with feature context |
+| `generate-bugfix-prompt.py` | Render bugfix bootstrap prompt with bug context |
+| `update-feature-status.py` | Update feature status in feature-list.json after session |
+| `update-bug-status.py` | Update bug status in bug-fix-list.json after session |
+| `check-session-status.py` | Read and validate session-status.json output |
+| `detect-stuck.py` | Detect stuck/hung pipeline sessions via heartbeat |
+| `parse-stream-progress.py` | Parse AI CLI output stream for progress tracking |
+| `cleanup-logs.py` | Clean up old pipeline logs and state files |
+| `utils.py` | Shared utility functions for pipeline scripts |
+
+## Artifact Mapping
+
+### PrizmKit Artifacts (.prizmkit/)
+
+| Phase | File | Content |
+|-------|------|---------|
+| 1 | `specs/spec.md` | Feature specification (WHAT/WHY) |
+| 2 | `plans/plan.md` | Technical plan (architecture, API, tests) |
+| 3 | `tasks/tasks.md` | Executable task list with `[ ]` / `[x]` (legacy — now part of plan.md Tasks section) |
+| 4 | `analysis/analyze-report.md` | Consistency analysis |
+
+### Dev-Team Artifacts (.dev-team/)
+
+| Phase | File | Content |
+|-------|------|---------|
+| 1 | `specs/requirements.md` | Requirements with REQ-NNN IDs |
+| 2 | `contracts/*.contract.json` | Interface contracts |
+| 2 | `contracts/data-models.json` | Data entity definitions |
+| 3 | `tasks/task-manifest.json` | Structured tasks with T-NNN IDs |
+| 3 | `tasks/dependency-graph.json` | Task DAG |
+| 6 | `reports/dev/self-test-*.md` | Dev self-test reports |
+| 7 | `reports/qa/integration-test.md` | QA integration test report |
+| 7 | `reports/review/code-review.md` | Review report |
+
+## Session Lifecycle
+
+### 1. Session Start
+
+The bootstrap prompt instructs the agent to:
+- Execute phases directly as the session orchestrator
+- Spawn Dev and Reviewer agents as subagents for implementation and review phases
+- The orchestrator handles context building, planning, retrospective, and commit phases directly
+
+### 2. Pipeline Execution
+
+The Orchestrator drives the pipeline phases with checkpoints (CP-0 through CP-3). Each checkpoint validates artifacts.
+
+### 3. Session End
+
+The agent MUST write `session-status.json` before exiting:
+
+```json
+{
+  "session_id": "F-001-20260304100000",
+  "feature_id": "F-001",
+  "status": "success",
+  "completed_phases": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
+  "current_phase": 9,
+  "checkpoint_reached": "CP-7",
+  "tasks_completed": 12,
+  "tasks_total": 12,
+  "errors": [],
+  "can_resume": false,
+  "resume_from_phase": null,
+  "artifacts": {
+    "spec_path": ".prizmkit/specs/spec.md",
+    "plan_path": ".prizmkit/plans/plan.md"
+  },
+  "timestamp": "2026-03-04T11:30:00Z"
+}
+```
+
+## Failure Recovery
+
+| Session Outcome | Pipeline Action |
+|-----------------|-----------------|
+| `status: "success"` | Mark feature completed, pick next |
+| `status: "partial"`, `can_resume: true` | Resume from `resume_from_phase` |
+| `status: "partial"`, `can_resume: false` | Retry from scratch |
+| `status: "failed"` | Retry (up to MAX_RETRIES) |
+| No status file (crash) | Treat as failed, retry |
+| Timeout (exit 124) | Treat as timed_out, retry |
+
+## Team Naming Convention
+
+Each feature gets its own team instance: `prizm-dev-team-{FEATURE_ID}`
+
+Examples:
+- `prizm-dev-team-F-001` — User Authentication
+- `prizm-dev-team-F-002` — Dashboard
+
+This ensures clean isolation between features and allows multiple features to have separate artifact histories.

package/bundled/dev-pipeline-windows/launch-bugfix-daemon.ps1

@@ -0,0 +1,9 @@
+#!/usr/bin/env pwsh
+. "$PSScriptRoot\lib\daemon.ps1"
+try {
+  Invoke-PrizmDaemon -Kind bugfix -ScriptRoot $PSScriptRoot -RunScript (Join-Path $PSScriptRoot 'run-bugfix.ps1') -Args $args
+  exit $global:PRIZM_DAEMON_EXIT_CODE
+} catch {
+  Write-PrizmError $_.Exception.Message
+  exit 1
+}

package/bundled/dev-pipeline-windows/launch-feature-daemon.ps1

@@ -0,0 +1,9 @@
+#!/usr/bin/env pwsh
+. "$PSScriptRoot\lib\daemon.ps1"
+try {
+  Invoke-PrizmDaemon -Kind feature -ScriptRoot $PSScriptRoot -RunScript (Join-Path $PSScriptRoot 'run-feature.ps1') -Args $args
+  exit $global:PRIZM_DAEMON_EXIT_CODE
+} catch {
+  Write-PrizmError $_.Exception.Message
+  exit 1
+}

package/bundled/dev-pipeline-windows/launch-refactor-daemon.ps1

@@ -0,0 +1,9 @@
+#!/usr/bin/env pwsh
+. "$PSScriptRoot\lib\daemon.ps1"
+try {
+  Invoke-PrizmDaemon -Kind refactor -ScriptRoot $PSScriptRoot -RunScript (Join-Path $PSScriptRoot 'run-refactor.ps1') -Args $args
+  exit $global:PRIZM_DAEMON_EXIT_CODE
+} catch {
+  Write-PrizmError $_.Exception.Message
+  exit 1
+}

package/bundled/dev-pipeline-windows/lib/common.ps1

@@ -0,0 +1,432 @@
+Set-StrictMode -Version 2.0
+$ErrorActionPreference = 'Stop'
+
+$script:PrizmAiProcess = $null
+
+function Write-PrizmInfo { param([string]$Message) Write-Host "[INFO]    $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss') $Message" -ForegroundColor Blue }
+function Write-PrizmWarn { param([string]$Message) Write-Host "[WARN]    $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss') $Message" -ForegroundColor Yellow }
+function Write-PrizmError { param([string]$Message) Write-Host "[ERROR]   $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss') $Message" -ForegroundColor Red }
+function Write-PrizmSuccess { param([string]$Message) Write-Host "[SUCCESS] $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss') $Message" -ForegroundColor Green }
+
+function Initialize-PrizmPaths {
+  param([string]$ScriptRoot)
+  $pipelineDir = Resolve-Path $ScriptRoot
+  $pipelineParent = Split-Path $pipelineDir -Parent
+  if ((Split-Path $pipelineParent -Leaf) -eq '.prizmkit') {
+    $prizmkitDir = $pipelineParent
+    $projectRoot = Split-Path $pipelineParent -Parent
+  } else {
+    $projectRoot = Split-Path $pipelineDir -Parent
+    $prizmkitDir = Join-Path $projectRoot '.prizmkit'
+  }
+  [pscustomobject]@{
+    PipelineDir = $pipelineDir.Path
+    PrizmkitDir = $prizmkitDir
+    ProjectRoot = $projectRoot
+    ScriptsDir = Join-Path $pipelineDir.Path 'scripts'
+    TemplatesDir = Join-Path $pipelineDir.Path 'templates'
+  }
+}
+
+function Import-PrizmEnv {
+  param([string]$EnvPath)
+  if (-not (Test-Path $EnvPath)) { return }
+  foreach ($line in Get-Content $EnvPath) {
+    $trimmed = $line.Trim()
+    if (-not $trimmed -or $trimmed.StartsWith('#')) { continue }
+    $idx = $trimmed.IndexOf('=')
+    if ($idx -lt 1) { continue }
+    $key = $trimmed.Substring(0, $idx).Trim()
+    $rawValue = $trimmed.Substring($idx + 1).Trim()
+    $valueBuilder = [System.Text.StringBuilder]::new()
+    $inSingleQuote = $false
+    $inDoubleQuote = $false
+    for ($i = 0; $i -lt $rawValue.Length; $i++) {
+      $char = $rawValue[$i]
+      if ($char -eq "'" -and -not $inDoubleQuote) { $inSingleQuote = -not $inSingleQuote }
+      if ($char -eq '"' -and -not $inSingleQuote) { $inDoubleQuote = -not $inDoubleQuote }
+      if ($char -eq '#' -and -not $inSingleQuote -and -not $inDoubleQuote) { break }
+      [void]$valueBuilder.Append($char)
+    }
+    $value = $valueBuilder.ToString().Trim().Trim('"').Trim("'")
+    if (-not [Environment]::GetEnvironmentVariable($key, 'Process')) {
+      [Environment]::SetEnvironmentVariable($key, $value, 'Process')
+    }
+  }
+}
+
+function Resolve-PrizmPython {
+  $python = Get-Command python -ErrorAction SilentlyContinue
+  if ($python) {
+    & $python.Source -c 'import sys; raise SystemExit(0 if sys.version_info[0] == 3 else 1)' *> $null
+    if ($LASTEXITCODE -eq 0) { return @($python.Source) }
+  }
+  $py = Get-Command py -ErrorAction SilentlyContinue
+  if ($py) {
+    & $py.Source -3 -c 'import sys; raise SystemExit(0 if sys.version_info[0] == 3 else 1)' *> $null
+    if ($LASTEXITCODE -eq 0) { return @($py.Source, '-3') }
+  }
+  throw 'Python 3 is required. Install Python and ensure python or py is in PATH.'
+}
+
+function Resolve-PrizmPowerShellHost {
+  $pwsh = Get-Command pwsh -ErrorAction SilentlyContinue
+  if ($pwsh) { return $pwsh.Source }
+  $powershell = Get-Command powershell -ErrorAction SilentlyContinue
+  if ($powershell) { return $powershell.Source }
+  throw 'PowerShell host not found. Install PowerShell or ensure powershell.exe is in PATH.'
+}
+
+function Invoke-PrizmPythonOutput {
+  param([string[]]$PythonCommand, [string[]]$Arguments)
+  $cmd = $PythonCommand[0]
+  $prefix = @()
+  if ($PythonCommand.Count -gt 1) { $prefix = $PythonCommand[1..($PythonCommand.Count - 1)] }
+  $output = & $cmd @prefix @Arguments
+  if ($LASTEXITCODE -ne 0) { throw "Python command failed: $($Arguments -join ' ')" }
+  if (-not $output) { return '' }
+  return ($output -join "`n")
+}
+
+function Invoke-PrizmPythonJson {
+  param([string[]]$PythonCommand, [string[]]$Arguments)
+  $text = Invoke-PrizmPythonOutput $PythonCommand $Arguments
+  if (-not $text) { return $null }
+  return $text | ConvertFrom-Json
+}
+
+function Invoke-PrizmPythonText {
+  param([string[]]$PythonCommand, [string[]]$Arguments)
+  $cmd = $PythonCommand[0]
+  $prefix = @()
+  if ($PythonCommand.Count -gt 1) { $prefix = $PythonCommand[1..($PythonCommand.Count - 1)] }
+  & $cmd @prefix @Arguments
+  if ($LASTEXITCODE -ne 0) { throw "Python command failed: $($Arguments -join ' ')" }
+}
+
+function Get-PrizmConfigValue {
+  param([string]$ConfigPath, [string]$Key)
+  if (-not (Test-Path $ConfigPath)) { return $null }
+  try {
+    $json = Get-Content $ConfigPath -Raw | ConvertFrom-Json
+    return $json.$Key
+  } catch { return $null }
+}
+
+function Split-PrizmCommandLine {
+  param([string]$CommandLine)
+  $trimmed = if ($CommandLine) { $CommandLine.Trim() } else { '' }
+  if (-not $trimmed) { throw 'AI CLI command is empty.' }
+  if (Test-Path $trimmed) {
+    return [pscustomobject]@{ Command = $trimmed; Arguments = '' }
+  }
+  if ($trimmed -match '^"([^"]+)"\s*(.*)$') {
+    return [pscustomobject]@{ Command = $matches[1]; Arguments = $matches[2].Trim() }
+  }
+  if ($trimmed -match "^'([^']+)'\s*(.*)$") {
+    return [pscustomobject]@{ Command = $matches[1]; Arguments = $matches[2].Trim() }
+  }
+  if ($trimmed -match '^(\S+)\s*(.*)$') {
+    return [pscustomobject]@{ Command = $matches[1]; Arguments = $matches[2].Trim() }
+  }
+  throw "Unable to parse AI CLI command: $CommandLine"
+}
+
+function Resolve-PrizmExecutableShim {
+  param([string]$Source)
+  if (-not $Source) { return $Source }
+
+  $extension = [System.IO.Path]::GetExtension($Source).ToLowerInvariant()
+  if ($extension -ne '.ps1') { return $Source }
+
+  $directory = [System.IO.Path]::GetDirectoryName($Source)
+  $baseName = [System.IO.Path]::GetFileNameWithoutExtension($Source)
+  if (-not $directory -or -not $baseName) { return $Source }
+
+  foreach ($candidateExtension in @('.cmd', '.bat', '.exe')) {
+    $candidate = Join-Path $directory ($baseName + $candidateExtension)
+    if (Test-Path $candidate) { return $candidate }
+  }
+
+  return $Source
+}
+
+function Resolve-PrizmCommandLine {
+  param([string]$CommandLine)
+  $parsed = Split-PrizmCommandLine $CommandLine
+  $command = @(Get-Command $parsed.Command -ErrorAction SilentlyContinue)[0]
+  if (-not $command) { return $CommandLine }
+  $source = if ($command.Source) { $command.Source } else { $command.Definition }
+  if (-not $source) { return $CommandLine }
+  $source = Resolve-PrizmExecutableShim $source
+  if ($source -match '\s') { $source = '"' + $source + '"' }
+  if ($parsed.Arguments) {
+    return "$source $($parsed.Arguments)"
+  }
+  return $source
+}
+
+function Get-PrizmCliNamesForPlatform {
+  param([string]$Platform)
+  $normalized = if ($Platform) { $Platform.ToLowerInvariant() } else { '' }
+  switch ($normalized) {
+    'codex' { return @('codex') }
+    'claude' { return @('claude') }
+    'codebuddy' { return @('cbc') }
+    'both' { return @('claude', 'cbc') }
+    'all' { return @('codex', 'claude', 'cbc') }
+    default { return @() }
+  }
+}
+
+function Resolve-PrizmCliName {
+  param([string]$CliName)
+  if ($CliName -eq 'cbc' -and $env:CODEBUDDY_CLI) {
+    return Resolve-PrizmCommandLine $env:CODEBUDDY_CLI
+  }
+  if (Get-Command $CliName -ErrorAction SilentlyContinue) {
+    return Resolve-PrizmCommandLine $CliName
+  }
+  return ''
+}
+
+function Resolve-PrizmCliForPlatform {
+  param([string]$Platform)
+  foreach ($candidate in (Get-PrizmCliNamesForPlatform $Platform)) {
+    $cli = Resolve-PrizmCliName $candidate
+    if ($cli) { return $cli }
+  }
+  return ''
+}
+
+function Resolve-PrizmCliForPlatformRequirement {
+  param([string]$Platform, [string]$Source)
+  $expectedCliNames = @(Get-PrizmCliNamesForPlatform $Platform)
+  if ($expectedCliNames.Count -eq 0) { return '' }
+  $cli = Resolve-PrizmCliForPlatform $Platform
+  if ($cli) { return $cli }
+  $expectedCliText = $expectedCliNames -join ', '
+  throw "$Source PrizmKit platform '$Platform' requires one of: $expectedCliText. Install it or set AI_CLI."
+}
+
+function Resolve-PrizmAiCli {
+  param([string]$ProjectRoot, [string]$PrizmkitDir)
+  Import-PrizmEnv (Join-Path $PrizmkitDir '.env')
+  if ($env:AI_CLI) { return Resolve-PrizmCommandLine $env:AI_CLI }
+  $configured = Get-PrizmConfigValue (Join-Path $PrizmkitDir 'config.json') 'ai_cli'
+  if ($configured) { return Resolve-PrizmCommandLine $configured }
+
+  $manifestPlatform = Get-PrizmConfigValue (Join-Path $PrizmkitDir 'manifest.json') 'platform'
+  if ($manifestPlatform) {
+    $manifestCli = Resolve-PrizmCliForPlatformRequirement ([string]$manifestPlatform) 'Installed'
+    if ($manifestCli) { return $manifestCli }
+  }
+
+  $configuredPlatform = Get-PrizmConfigValue (Join-Path $PrizmkitDir 'config.json') 'platform'
+  if ($configuredPlatform) {
+    $configuredPlatformCli = Resolve-PrizmCliForPlatformRequirement ([string]$configuredPlatform) 'Configured'
+    if ($configuredPlatformCli) { return $configuredPlatformCli }
+  }
+
+  if ($env:CODEBUDDY_CLI) { return Resolve-PrizmCommandLine $env:CODEBUDDY_CLI }
+
+  if (((Test-Path (Join-Path $ProjectRoot '.codex\agents\prizm-dev-team-dev.toml')) -or (Test-Path (Join-Path $ProjectRoot '.agents\skills\prizm-kit\SKILL.md'))) -and (Get-Command codex -ErrorAction SilentlyContinue)) { return Resolve-PrizmCommandLine 'codex' }
+  if ((Test-Path (Join-Path $ProjectRoot '.claude\commands\prizm-kit.md')) -and (Get-Command claude -ErrorAction SilentlyContinue)) { return Resolve-PrizmCommandLine 'claude' }
+  if (((Test-Path (Join-Path $ProjectRoot '.codebuddy\agents\prizm-dev-team-dev.md')) -or (Test-Path (Join-Path $ProjectRoot '.codebuddy\skills\prizm-kit\SKILL.md'))) -and (Resolve-PrizmCliName 'cbc')) { return Resolve-PrizmCliName 'cbc' }
+  foreach ($candidate in @('codex', 'claude', 'cbc')) {
+    $cli = Resolve-PrizmCliName $candidate
+    if ($cli) { return $cli }
+  }
+  throw 'No AI CLI found. Install Codex (codex), Claude Code (claude), or CodeBuddy (cbc), or set AI_CLI.'
+}
+
+function Get-PrizmConcretePlatform {
+  param([string]$Platform)
+  $normalized = if ($Platform) { $Platform.ToLowerInvariant() } else { '' }
+  if (@('codex', 'claude', 'codebuddy') -contains $normalized) { return $normalized }
+  return ''
+}
+
+function Get-PrizmKnownPlatformFromCli {
+  param([string]$CliCommand)
+  $parsed = Split-PrizmCommandLine $CliCommand
+  $cliName = [System.IO.Path]::GetFileNameWithoutExtension($parsed.Command).ToLowerInvariant()
+  if ($cliName -match 'claude') { return 'claude' }
+  if ($cliName -match 'codex') { return 'codex' }
+  if ($cliName -match 'cbc|codebuddy') { return 'codebuddy' }
+  return ''
+}
+
+function ConvertTo-PrizmProcessArgument {
+  param([string]$Argument)
+  if ($Argument -eq $null) { return '""' }
+  if ($Argument -notmatch '[\s"]') { return $Argument }
+  return '"' + ($Argument -replace '"', '\"') + '"'
+}
+
+function Join-PrizmProcessArguments {
+  param([string[]]$Arguments)
+  return (($Arguments | ForEach-Object { ConvertTo-PrizmProcessArgument $_ }) -join ' ')
+}
+
+function Get-PrizmPlatformFromCli {
+  param([string]$CliCommand)
+  $platform = Get-PrizmKnownPlatformFromCli $CliCommand
+  if ($platform) { return $platform }
+  return 'codebuddy'
+}
+
+function Get-PrizmPlatformFromProject {
+  param([string]$ProjectRoot, [string]$PrizmkitDir, [string]$CliCommand)
+  $cliPlatform = Get-PrizmKnownPlatformFromCli $CliCommand
+  if ($cliPlatform) { return $cliPlatform }
+  $envPlatform = Get-PrizmConcretePlatform $env:PRIZMKIT_PLATFORM
+  if ($envPlatform) { return $envPlatform }
+  $manifestPlatform = Get-PrizmConcretePlatform (Get-PrizmConfigValue (Join-Path $PrizmkitDir 'manifest.json') 'platform')
+  if ($manifestPlatform) { return $manifestPlatform }
+  $configuredPlatform = Get-PrizmConcretePlatform (Get-PrizmConfigValue (Join-Path $PrizmkitDir 'config.json') 'platform')
+  if ($configuredPlatform) { return $configuredPlatform }
+  return Get-PrizmPlatformFromCli $CliCommand
+}
+
+function Get-PrizmSessionPlatform {
+  param([string]$CliCommand)
+  $cliPlatform = Get-PrizmKnownPlatformFromCli $CliCommand
+  if ($cliPlatform) { return $cliPlatform }
+  $platform = Get-PrizmConcretePlatform $env:PRIZMKIT_PLATFORM
+  if ($platform) { return $platform }
+  return Get-PrizmPlatformFromCli $CliCommand
+}
+
+function Stop-PrizmProcessTreeById {
+  param([int]$ProcessId)
+  if ($ProcessId -le 0) { return }
+
+  $process = Get-Process -Id $ProcessId -ErrorAction SilentlyContinue
+  if (-not $process) { return }
+
+  try {
+    $process.Kill($true)
+    return
+  } catch {
+    try {
+      $children = Get-CimInstance Win32_Process -Filter "ParentProcessId=$ProcessId" -ErrorAction SilentlyContinue
+      foreach ($child in $children) {
+        Stop-PrizmProcessTreeById -ProcessId ([int]$child.ProcessId)
+      }
+    } catch {
+      try {
+        $children = Get-WmiObject Win32_Process -Filter "ParentProcessId=$ProcessId" -ErrorAction SilentlyContinue
+        foreach ($child in $children) {
+          Stop-PrizmProcessTreeById -ProcessId ([int]$child.ProcessId)
+        }
+      } catch {}
+    }
+    try {
+      Stop-Process -Id $ProcessId -Force -ErrorAction SilentlyContinue
+    } catch {}
+  }
+}
+
+function Invoke-PrizmAiSession {
+  param(
+    [string]$CliCommand,
+    [string]$PromptPath,
+    [string]$LogPath,
+    [string]$ProjectRoot,
+    [string]$Model = '',
+    [string]$PidPath = ''
+  )
+  $prompt = Get-Content $PromptPath -Raw
+  $logDir = Split-Path $LogPath -Parent
+  New-Item -ItemType Directory -Force -Path $logDir | Out-Null
+
+  $psi = [System.Diagnostics.ProcessStartInfo]::new()
+  $psi.UseShellExecute = $false
+  $psi.RedirectStandardInput = $true
+  $psi.RedirectStandardOutput = $true
+  $psi.RedirectStandardError = $true
+  $psi.WorkingDirectory = $ProjectRoot
+  [void]$psi.Environment.Remove('CLAUDECODE')
+  $cliArgs = @()
+  $parsedCli = Split-PrizmCommandLine $CliCommand
+  $cliExecutable = $parsedCli.Command
+  $sessionPlatform = Get-PrizmSessionPlatform $CliCommand
+
+  if ($sessionPlatform -eq 'claude') {
+    $cliArgs += @('-p', '--dangerously-skip-permissions')
+    if ($Model) { $cliArgs += @('--model', $Model) }
+  } elseif ($sessionPlatform -eq 'codex') {
+    $cliArgs += @('--ask-for-approval', 'never', '--sandbox', 'danger-full-access', 'exec', '--cd', $ProjectRoot, '--skip-git-repo-check')
+    if ($Model) { $cliArgs += @('--model', $Model) }
+    $cliArgs += '-'
+  } else {
+    $cliArgs += @('--print', '-y')
+    if ($Model) { $cliArgs += @('--model', $Model) }
+  }
+  $generatedArgs = (($cliArgs | ForEach-Object { ConvertTo-PrizmProcessArgument $_ }) -join ' ')
+  $fullArgs = @()
+  if ($parsedCli.Arguments) { $fullArgs += $parsedCli.Arguments }
+  if ($generatedArgs) { $fullArgs += $generatedArgs }
+  $argumentString = ($fullArgs -join ' ')
+
+  $cliExtension = [System.IO.Path]::GetExtension($cliExecutable).ToLowerInvariant()
+
+  if ($cliExtension -in @('.cmd', '.bat')) {
+    $psi.FileName = if ($env:ComSpec) { $env:ComSpec } else { 'cmd.exe' }
+    $childCommand = (ConvertTo-PrizmProcessArgument $cliExecutable)
+    if ($argumentString) { $childCommand = "$childCommand $argumentString" }
+    $psi.Arguments = '/d /s /c "' + $childCommand + '"'
+  } elseif ($cliExtension -eq '.ps1') {
+    $psi.FileName = Resolve-PrizmPowerShellHost
+    $scriptArgs = @('-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', $cliExecutable)
+    $scriptArgumentString = Join-PrizmProcessArguments $scriptArgs
+    if ($argumentString) { $scriptArgumentString = "$scriptArgumentString $argumentString" }
+    $psi.Arguments = $scriptArgumentString
+  } else {
+    $psi.FileName = $cliExecutable
+    $psi.Arguments = $argumentString
+  }
+
+  $process = [System.Diagnostics.Process]::Start($psi)
+  $script:PrizmAiProcess = $process
+  if ($PidPath) {
+    $pidDir = Split-Path $PidPath -Parent
+    if ($pidDir) { New-Item -ItemType Directory -Force -Path $pidDir | Out-Null }
+    Set-Content -Path $PidPath -Value ([string]$process.Id) -Encoding UTF8
+  }
+  $process.StandardInput.Write($prompt)
+  $process.StandardInput.Close()
+  $stdoutTask = $process.StandardOutput.ReadToEndAsync()
+  $stderrTask = $process.StandardError.ReadToEndAsync()
+  $process.WaitForExit()
+  $stdout = $stdoutTask.Result
+  $stderr = $stderrTask.Result
+  Set-Content -Path $LogPath -Value ($stdout + $stderr) -Encoding UTF8
+  return $process.ExitCode
+}
+
+function New-PrizmSessionId {
+  param([string]$Prefix)
+  return "$Prefix-$(Get-Date -Format 'yyyyMMdd-HHmmss')-$([guid]::NewGuid().ToString('N').Substring(0, 8))"
+}
+
+function Get-PrizmListDefault {
+  param([string]$Kind, [string]$ProjectRoot)
+  switch ($Kind) {
+    'feature' { return Join-Path $ProjectRoot '.prizmkit\plans\feature-list.json' }
+    'bugfix' { return Join-Path $ProjectRoot '.prizmkit\plans\bug-fix-list.json' }
+    'refactor' { return Join-Path $ProjectRoot '.prizmkit\plans\refactor-list.json' }
+    default { throw "Unknown pipeline kind: $Kind" }
+  }
+}
+
+function Get-PrizmStateDir {
+  param([string]$Kind, [string]$ProjectRoot)
+  switch ($Kind) {
+    'feature' { return Join-Path $ProjectRoot '.prizmkit\state\features' }
+    'bugfix' { return Join-Path $ProjectRoot '.prizmkit\state\bugfix' }
+    'refactor' { return Join-Path $ProjectRoot '.prizmkit\state\refactor' }
+    default { throw "Unknown pipeline kind: $Kind" }
+  }
+}