sdtk-kit 0.3.0

package/assets/toolkit/toolkit/install.ps1

@@ -0,0 +1,155 @@
+param(
+  [string]$ProjectPath,
+  [switch]$Force,
+  [switch]$SkipSkills,
+  [switch]$Quiet,
+  [ValidateSet('codex', 'claude')]
+  [string]$Runtime = 'codex'
+)
+
+$ErrorActionPreference = 'Stop'
+Set-StrictMode -Version Latest
+
+function Get-FileSha256 {
+  param(
+    [Parameter(Mandatory = $true)][string]$Path
+  )
+
+  if (-not (Test-Path -LiteralPath $Path)) {
+    return $null
+  }
+
+  $stream = [System.IO.File]::OpenRead($Path)
+  try {
+    $sha = [System.Security.Cryptography.SHA256]::Create()
+    $hashBytes = $sha.ComputeHash($stream)
+    return [BitConverter]::ToString($hashBytes).Replace('-', '')
+  } finally {
+    $stream.Close()
+  }
+}
+
+function Copy-File {
+  param(
+    [Parameter(Mandatory = $true)][string]$SourcePath,
+    [Parameter(Mandatory = $true)][string]$DestinationPath,
+    [Parameter(Mandatory = $true)][bool]$Overwrite
+  )
+
+  if (-not (Test-Path -LiteralPath $SourcePath)) {
+    throw "Missing source: $SourcePath"
+  }
+
+  if (Test-Path -LiteralPath $DestinationPath) {
+    if (-not $Overwrite) {
+      Write-Warning "Already exists (skipping). Use -Force to overwrite: $DestinationPath"
+      return
+    }
+  }
+
+  $parent = Split-Path -Parent $DestinationPath
+  if ($parent -and -not (Test-Path -LiteralPath $parent)) {
+    New-Item -ItemType Directory -Force -Path $parent | Out-Null
+  }
+
+  Copy-Item -LiteralPath $SourcePath -Destination $DestinationPath -Force
+}
+
+function Install-RuntimeAdapter {
+  param(
+    [Parameter(Mandatory = $true)][string]$ToolkitRoot,
+    [Parameter(Mandatory = $true)][string]$ProjectRoot,
+    [Parameter(Mandatory = $true)][string]$RuntimeName,
+    [Parameter(Mandatory = $true)][bool]$Overwrite
+  )
+
+  if ($RuntimeName -eq 'codex') {
+    $source = Join-Path $ToolkitRoot 'runtimes/codex/CODEX_TEMPLATE.md'
+    $dest = Join-Path $ProjectRoot 'CODEX.md'
+    Copy-File -SourcePath $source -DestinationPath $dest -Overwrite $Overwrite
+    return
+  }
+
+  if ($RuntimeName -eq 'claude') {
+    $source = Join-Path $ToolkitRoot 'runtimes/claude/CLAUDE_TEMPLATE.md'
+    $dest = Join-Path $ProjectRoot 'CLAUDE.md'
+    Copy-File -SourcePath $source -DestinationPath $dest -Overwrite $Overwrite
+    return
+  }
+
+  throw "Unsupported runtime: $RuntimeName"
+}
+
+$toolkitRoot = Resolve-Path $PSScriptRoot
+$canonicalRulesPath = Join-Path $toolkitRoot 'templates/docs/api/FLOWCHART_CREATION_RULES.md'
+$canonicalRulesHash = Get-FileSha256 -Path $canonicalRulesPath
+$apiDesignRulesPath = Join-Path $toolkitRoot 'templates/docs/api/API_DESIGN_CREATION_RULES.md'
+$apiDesignRulesHash = Get-FileSha256 -Path $apiDesignRulesPath
+$flowActionRulesPath = Join-Path $toolkitRoot 'templates/docs/specs/FLOW_ACTION_SPEC_CREATION_RULES.md'
+$flowActionRulesHash = Get-FileSha256 -Path $flowActionRulesPath
+
+if (-not $ProjectPath) {
+  $ProjectPath = (Resolve-Path (Join-Path $toolkitRoot '..')).Path
+}
+$projectRoot = Resolve-Path -LiteralPath $ProjectPath
+
+if (-not $Quiet) {
+  Write-Host "SDTK toolkit : $toolkitRoot"
+  Write-Host "Project root : $projectRoot"
+  Write-Host "Runtime      : $Runtime"
+  if ($canonicalRulesHash) {
+    Write-Host "API ruleset  : $canonicalRulesPath"
+    Write-Host "Ruleset hash : $canonicalRulesHash"
+  } else {
+    Write-Warning "API ruleset not found: $canonicalRulesPath"
+  }
+  if ($apiDesignRulesHash) {
+    Write-Host "API design ruleset: $apiDesignRulesPath"
+    Write-Host "Ruleset hash      : $apiDesignRulesHash"
+  } else {
+    Write-Warning "API design ruleset not found: $apiDesignRulesPath"
+  }
+  if ($flowActionRulesHash) {
+    Write-Host "Flow ruleset : $flowActionRulesPath"
+    Write-Host "Ruleset hash : $flowActionRulesHash"
+  } else {
+    Write-Warning "Flow ruleset not found: $flowActionRulesPath"
+  }
+}
+
+Copy-File -SourcePath (Join-Path $toolkitRoot 'AGENTS.md') -DestinationPath (Join-Path $projectRoot 'AGENTS.md') -Overwrite ([bool]$Force)
+Copy-File -SourcePath (Join-Path $toolkitRoot 'sdtk.config.json') -DestinationPath (Join-Path $projectRoot 'sdtk.config.json') -Overwrite ([bool]$Force)
+Copy-File -SourcePath (Join-Path $toolkitRoot 'sdtk.config.profiles.example.json') -DestinationPath (Join-Path $projectRoot 'sdtk.config.profiles.example.json') -Overwrite ([bool]$Force)
+Install-RuntimeAdapter -ToolkitRoot $toolkitRoot -ProjectRoot $projectRoot -RuntimeName $Runtime -Overwrite ([bool]$Force)
+
+if (($Runtime -eq 'codex') -and (-not $SkipSkills)) {
+  $skillInstaller = Join-Path $toolkitRoot 'scripts/install-codex-skills.ps1'
+  if (-not (Test-Path -LiteralPath $skillInstaller)) {
+    throw "Missing skill installer script: $skillInstaller"
+  }
+
+  Write-Host ""
+  Write-Host "Installing Codex skills globally..."
+  if ($Force) {
+    & $skillInstaller -Force | Out-Host
+  } else {
+    & $skillInstaller | Out-Host
+  }
+}
+elseif (($Runtime -eq 'claude') -and (-not $SkipSkills) -and (-not $Quiet)) {
+  Write-Warning "Runtime 'claude' does not install Codex skills. Skipping skill installation."
+}
+
+if (-not $Quiet) {
+  Write-Host ""
+  Write-Host "Install complete."
+  Write-Host "Next:"
+  Write-Host "1) Edit project config: $((Join-Path $projectRoot 'sdtk.config.json'))"
+  if ($Runtime -eq 'codex') {
+    Write-Host "2) Restart Codex (to load runtime adapter and skills)"
+  } else {
+    Write-Host "2) Restart Claude Code (to load CLAUDE.md adapter)"
+  }
+  Write-Host '3) Generate feature docs:'
+  Write-Host '   sdtk generate --feature-key YOUR_FEATURE --feature-name "Your Feature"'
+}

package/assets/toolkit/toolkit/runtimes/claude/CLAUDE_TEMPLATE.md

@@ -0,0 +1,32 @@
+# CLAUDE.md
+
+Version: 1.0
+Last Updated: 2026-02-25
+Owner: SDTK Core Team
+
+This file defines runtime guidance for Claude Code sessions in projects using SDTK.
+
+## 1) Rule Priority
+1. Explicit user request
+2. `AGENTS.md` (project root)
+3. `toolkit/AGENTS.md`
+4. This file (`CLAUDE.md`)
+5. Other supporting docs
+
+## 2) Runtime Model
+- Primary workflow: PM -> BA -> ARCH -> DEV -> QA
+- Role tags: `/pm`, `/ba`, `/arch`, `/dev`, `/qa`
+- Shared state files:
+  - `SHARED_PLANNING.md`
+  - `QUALITY_CHECKLIST.md`
+
+## 3) Minimal Session Flow
+1. Start with `/pm` to define feature scope.
+2. Move phase-by-phase without skipping gates.
+3. Keep traceability from requirements to design, implementation, and tests.
+4. Require code review completion before QA release decision.
+
+## 4) References
+- `toolkit/SDTK_TOOLKIT.md`
+- `toolkit/AGENTS.md`
+- `sdtk.config.json`

package/assets/toolkit/toolkit/runtimes/codex/CODEX_TEMPLATE.md

@@ -0,0 +1,32 @@
+# CODEX.md
+
+Version: 1.0
+Last Updated: 2026-02-25
+Owner: SDTK Core Team
+
+This file defines runtime guidance for Codex sessions in projects using SDTK.
+
+## 1) Rule Priority
+1. Explicit user request
+2. `AGENTS.md` (project root)
+3. `toolkit/AGENTS.md`
+4. This file (`CODEX.md`)
+5. Other supporting docs
+
+## 2) Runtime Model
+- Primary workflow: PM -> BA -> ARCH -> DEV -> QA
+- Role tags: `/pm`, `/ba`, `/arch`, `/dev`, `/qa`
+- Shared state files:
+  - `SHARED_PLANNING.md`
+  - `QUALITY_CHECKLIST.md`
+
+## 3) Minimal Session Flow
+1. Start with `/pm` to define feature scope.
+2. Move phase-by-phase without skipping gates.
+3. Keep traceability from requirements to design, implementation, and tests.
+4. Require code review completion before QA release decision.
+
+## 4) References
+- `toolkit/SDTK_TOOLKIT.md`
+- `toolkit/AGENTS.md`
+- `sdtk.config.json`

package/assets/toolkit/toolkit/scripts/init-feature.ps1

@@ -0,0 +1,253 @@
+param(
+  [Parameter(Mandatory = $true)]
+  [string]$FeatureKey,
+
+  [Parameter(Mandatory = $true)]
+  [string]$FeatureName,
+
+  [string]$ProjectPath,
+
+  [switch]$Force,
+
+  [switch]$ValidateOnly
+)
+
+$ErrorActionPreference = 'Stop'
+Set-StrictMode -Version Latest
+
+function ConvertTo-PascalCase {
+  param([Parameter(Mandatory = $true)][string]$Text)
+
+  $parts = $Text -split '[^A-Za-z0-9]+' | Where-Object { $_ -and $_.Trim().Length -gt 0 }
+  if (-not $parts -or $parts.Count -eq 0) {
+    return ''
+  }
+
+  return ($parts | ForEach-Object {
+    if ($_.Length -eq 1) { $_.Substring(0, 1).ToUpper() }
+    else { $_.Substring(0, 1).ToUpper() + $_.Substring(1) }
+  }) -join ''
+}
+
+function Render-Template {
+  param(
+    [Parameter(Mandatory = $true)][string]$TemplatePath,
+    [Parameter(Mandatory = $true)][hashtable]$Tokens
+  )
+
+  $content = Get-Content -Raw -Path $TemplatePath
+  # Strip BOM if present (Windows PowerShell 5.1 may read BOM into string)
+  if ($content.Length -gt 0 -and $content[0] -eq [char]0xFEFF) {
+    $content = $content.Substring(1)
+  }
+  foreach ($key in $Tokens.Keys) {
+    $content = $content.Replace("{{${key}}}", [string]$Tokens[$key])
+  }
+  return $content
+}
+
+function Write-RenderedFile {
+  param(
+    [Parameter(Mandatory = $true)][string]$DestinationPath,
+    [Parameter(Mandatory = $true)][string]$TemplatePath,
+    [Parameter(Mandatory = $true)][hashtable]$Tokens,
+    [Parameter(Mandatory = $true)][bool]$Overwrite
+  )
+
+  if ((Test-Path -LiteralPath $DestinationPath) -and -not $Overwrite) {
+    throw "Refusing to overwrite existing file (use -Force): $DestinationPath"
+  }
+
+  $parent = Split-Path -Parent $DestinationPath
+  if ($parent -and -not (Test-Path -LiteralPath $parent)) {
+    New-Item -ItemType Directory -Force -Path $parent | Out-Null
+  }
+
+  $rendered = Render-Template -TemplatePath $TemplatePath -Tokens $Tokens
+  $utf8NoBom = New-Object System.Text.UTF8Encoding($false)
+  [System.IO.File]::WriteAllText($DestinationPath, $rendered, $utf8NoBom)
+}
+
+$config = $null
+function Get-StringOrDefault {
+  param(
+    [AllowNull()][object]$Value,
+    [Parameter(Mandatory = $true)][string]$Default
+  )
+
+  if ($null -eq $Value) {
+    return $Default
+  }
+  $text = ([string]$Value).Trim()
+  if ($text.Length -eq 0) {
+    return $Default
+  }
+  return $text
+}
+
+function Get-PropValue {
+  param(
+    [AllowNull()][object]$Object,
+    [Parameter(Mandatory = $true)][string]$Name
+  )
+
+  if ($null -eq $Object) {
+    return $null
+  }
+  $prop = $Object.PSObject.Properties[$Name]
+  if ($null -eq $prop) {
+    return $null
+  }
+  return $prop.Value
+}
+
+$toolkitRoot = Resolve-Path (Join-Path $PSScriptRoot '..')
+
+if ($ProjectPath) {
+  if (-not (Test-Path -LiteralPath $ProjectPath)) {
+    New-Item -ItemType Directory -Force -Path $ProjectPath | Out-Null
+  }
+  $projectRoot = Resolve-Path -LiteralPath $ProjectPath
+} else {
+  $projectRoot = Resolve-Path (Join-Path $toolkitRoot '..')
+}
+
+$templateRoot = Join-Path $toolkitRoot 'templates'
+
+if (-not (Test-Path -LiteralPath $templateRoot)) {
+  throw "Missing templates directory: $templateRoot"
+}
+
+$configPath = Join-Path $projectRoot 'sdtk.config.json'
+if (-not (Test-Path -LiteralPath $configPath)) {
+  $configPath = Join-Path $toolkitRoot 'sdtk.config.json'
+}
+
+if (Test-Path -LiteralPath $configPath) {
+  try {
+    $config = Get-Content -Raw -LiteralPath $configPath | ConvertFrom-Json
+  } catch {
+    throw "Failed to parse config file: $configPath`n$($_.Exception.Message)"
+  }
+}
+
+$FeatureKey = $FeatureKey.Trim()
+$FeatureName = $FeatureName.Trim()
+
+if (-not $FeatureKey) { throw "FeatureKey is empty." }
+if ($FeatureKey -notmatch '^[A-Z][A-Z0-9_]*$') {
+  throw "Invalid FeatureKey. Use UPPER_SNAKE_CASE (A-Z, 0-9, _)."
+}
+if (-not $FeatureName) { throw "FeatureName is empty." }
+
+$now = Get-Date
+$date = $now.ToString('yyyy-MM-dd')
+$dateTime = $now.ToString('yyyy-MM-dd HH:mm')
+
+$featureSnake = $FeatureKey.ToLower()
+$featurePascal = ConvertTo-PascalCase -Text $FeatureName
+if (-not $featurePascal) {
+  $featurePascal = ConvertTo-PascalCase -Text $FeatureKey
+}
+
+$stack = Get-PropValue -Object $config -Name 'stack'
+$commands = Get-PropValue -Object $config -Name 'commands'
+
+$stackBackend = Get-StringOrDefault -Value (Get-PropValue -Object $stack -Name 'backend') -Default 'TBD'
+$stackFrontend = Get-StringOrDefault -Value (Get-PropValue -Object $stack -Name 'frontend') -Default 'TBD'
+$stackMobile = Get-StringOrDefault -Value (Get-PropValue -Object $stack -Name 'mobile') -Default 'TBD'
+$stackDatabase = Get-StringOrDefault -Value (Get-PropValue -Object $stack -Name 'database') -Default 'TBD'
+$stackAuth = Get-StringOrDefault -Value (Get-PropValue -Object $stack -Name 'auth') -Default 'TBD'
+
+$cmdBackendTests = Get-StringOrDefault -Value (Get-PropValue -Object $commands -Name 'backendTests') -Default 'TBD'
+$cmdBackendTypecheck = Get-StringOrDefault -Value (Get-PropValue -Object $commands -Name 'backendTypecheck') -Default 'TBD'
+$cmdBackendLint = Get-StringOrDefault -Value (Get-PropValue -Object $commands -Name 'backendLint') -Default 'TBD'
+$cmdFrontendTests = Get-StringOrDefault -Value (Get-PropValue -Object $commands -Name 'frontendTests') -Default 'TBD'
+$cmdFrontendLint = Get-StringOrDefault -Value (Get-PropValue -Object $commands -Name 'frontendLint') -Default 'TBD'
+$cmdE2eTests = Get-StringOrDefault -Value (Get-PropValue -Object $commands -Name 'e2eTests') -Default 'TBD'
+
+$tokens = @{
+  FEATURE_KEY   = $FeatureKey
+  FEATURE_NAME  = $FeatureName
+  FEATURE_PASCAL = $featurePascal
+  FEATURE_SNAKE = $featureSnake
+  DATE          = $date
+  DATETIME      = $dateTime
+
+  STACK_BACKEND = $stackBackend
+  STACK_FRONTEND = $stackFrontend
+  STACK_MOBILE = $stackMobile
+  STACK_DATABASE = $stackDatabase
+  STACK_AUTH = $stackAuth
+
+  CMD_BACKEND_TESTS = $cmdBackendTests
+  CMD_BACKEND_TYPECHECK = $cmdBackendTypecheck
+  CMD_BACKEND_LINT = $cmdBackendLint
+  CMD_FRONTEND_TESTS = $cmdFrontendTests
+  CMD_FRONTEND_LINT = $cmdFrontendLint
+  CMD_E2E_TESTS = $cmdE2eTests
+}
+
+$outputs = @(
+  @{ Dest = (Join-Path $projectRoot 'SHARED_PLANNING.md'); Template = (Join-Path $templateRoot 'SHARED_PLANNING.md') },
+  @{ Dest = (Join-Path $projectRoot 'QUALITY_CHECKLIST.md'); Template = (Join-Path $templateRoot 'QUALITY_CHECKLIST.md') },
+
+  @{ Dest = (Join-Path $projectRoot "docs/product/PROJECT_INITIATION_$FeatureKey.md"); Template = (Join-Path $templateRoot 'docs/product/PROJECT_INITIATION_TEMPLATE.md') },
+  @{ Dest = (Join-Path $projectRoot "docs/specs/BA_SPEC_$FeatureKey.md"); Template = (Join-Path $templateRoot 'docs/specs/BA_SPEC_TEMPLATE.md') },
+  @{ Dest = (Join-Path $projectRoot "docs/specs/${FeatureKey}_FLOW_ACTION_SPEC.md"); Template = (Join-Path $templateRoot 'docs/specs/FLOW_ACTION_SPEC_TEMPLATE.md') },
+  @{ Dest = (Join-Path $projectRoot "docs/product/PRD_$FeatureKey.md"); Template = (Join-Path $templateRoot 'docs/product/PRD_TEMPLATE.md') },
+  @{ Dest = (Join-Path $projectRoot "docs/product/BACKLOG_$FeatureKey.md"); Template = (Join-Path $templateRoot 'docs/product/BACKLOG_TEMPLATE.md') },
+  @{ Dest = (Join-Path $projectRoot "docs/architecture/ARCH_DESIGN_$FeatureKey.md"); Template = (Join-Path $templateRoot 'docs/architecture/ARCH_DESIGN_TEMPLATE.md') },
+  @{ Dest = (Join-Path $projectRoot "docs/database/DATABASE_SPEC_$FeatureKey.md"); Template = (Join-Path $templateRoot 'docs/database/DATABASE_SPEC_TEMPLATE.md') },
+
+  @{ Dest = (Join-Path $projectRoot "docs/api/${featurePascal}_API.yaml"); Template = (Join-Path $templateRoot 'docs/api/FEATURE_API_TEMPLATE.yaml') },
+  @{ Dest = (Join-Path $projectRoot "docs/api/${FeatureKey}_ENDPOINTS.md"); Template = (Join-Path $templateRoot 'docs/api/API_ENDPOINTS_TEMPLATE.md') },
+  @{ Dest = (Join-Path $projectRoot "docs/api/${FeatureKey}_API_DESIGN_DETAIL.md"); Template = (Join-Path $templateRoot 'docs/api/API_DESIGN_DETAIL_TEMPLATE.md') },
+  @{ Dest = (Join-Path $projectRoot "docs/api/${featureSnake}_api_flow_list.txt"); Template = (Join-Path $templateRoot 'docs/api/feature_api_flow_list_TEMPLATE.txt') },
+  @{ Dest = (Join-Path $projectRoot "docs/design/DESIGN_LAYOUT_$FeatureKey.md"); Template = (Join-Path $templateRoot 'docs/design/DESIGN_LAYOUT_TEMPLATE.md') },
+
+  @{ Dest = (Join-Path $projectRoot "docs/dev/FEATURE_IMPL_PLAN_$FeatureKey.md"); Template = (Join-Path $templateRoot 'docs/dev/FEATURE_IMPL_PLAN_TEMPLATE.md') },
+  @{ Dest = (Join-Path $projectRoot "docs/qa/${FeatureKey}_TEST_CASE.md"); Template = (Join-Path $templateRoot 'docs/qa/TEST_CASE_TEMPLATE.md') },
+  @{ Dest = (Join-Path $projectRoot "docs/qa/QA_RELEASE_REPORT_$FeatureKey.md"); Template = (Join-Path $templateRoot 'docs/qa/QA_RELEASE_REPORT_TEMPLATE.md') }
+)
+
+if ($ValidateOnly) {
+  foreach ($item in $outputs) {
+    $tmpl = [string]$item.Template
+    if (-not (Test-Path -LiteralPath $tmpl)) {
+      throw "Missing template file: $tmpl"
+    }
+  }
+
+  Write-Host "Validation only: inputs and templates are valid."
+  Write-Host "No files were written because -ValidateOnly was specified."
+  return
+}
+
+$created = New-Object System.Collections.Generic.List[string]
+foreach ($item in $outputs) {
+  $dest = [string]$item.Dest
+  $tmpl = [string]$item.Template
+  if (-not (Test-Path -LiteralPath $tmpl)) {
+    throw "Missing template file: $tmpl"
+  }
+
+  $willOverwrite = (Test-Path -LiteralPath $dest)
+  Write-RenderedFile -DestinationPath $dest -TemplatePath $tmpl -Tokens $tokens -Overwrite ([bool]$Force)
+  if (-not $willOverwrite) {
+    $created.Add($dest) | Out-Null
+  }
+}
+
+Write-Host "Initialized feature: $FeatureKey ($FeatureName)"
+Write-Host "FeaturePascal: $featurePascal"
+Write-Host "FeatureSnake: $featureSnake"
+
+if ($created.Count -gt 0) {
+  Write-Host ""
+  Write-Host "Created files:"
+  $created | ForEach-Object { Write-Host " - $_" }
+} else {
+  Write-Host ""
+  Write-Host "No new files created (all existed); use -Force to overwrite if needed."
+}

package/assets/toolkit/toolkit/scripts/install-codex-skills.ps1

@@ -0,0 +1,181 @@
+param(
+  [switch]$Force
+)
+
+$ErrorActionPreference = 'Stop'
+Set-StrictMode -Version Latest
+
+function Get-FileSha256 {
+  param(
+    [Parameter(Mandatory = $true)][string]$Path
+  )
+
+  if (-not (Test-Path -LiteralPath $Path)) {
+    return $null
+  }
+
+  $stream = [System.IO.File]::OpenRead($Path)
+  try {
+    $sha = [System.Security.Cryptography.SHA256]::Create()
+    $hashBytes = $sha.ComputeHash($stream)
+    return [BitConverter]::ToString($hashBytes).Replace('-', '')
+  } finally {
+    $stream.Close()
+  }
+}
+
+$repoRoot = Resolve-Path (Join-Path $PSScriptRoot '..')
+$skillsSrc = Join-Path $repoRoot 'skills'
+$canonicalRulesPath = Join-Path $repoRoot 'templates/docs/api/FLOWCHART_CREATION_RULES.md'
+$canonicalRulesHash = Get-FileSha256 -Path $canonicalRulesPath
+$canonicalApiDesignRulesPath = Join-Path $repoRoot 'templates/docs/api/API_DESIGN_CREATION_RULES.md'
+$canonicalApiDesignRulesHash = Get-FileSha256 -Path $canonicalApiDesignRulesPath
+$canonicalFlowRulesPath = Join-Path $repoRoot 'templates/docs/specs/FLOW_ACTION_SPEC_CREATION_RULES.md'
+$canonicalFlowRulesHash = Get-FileSha256 -Path $canonicalFlowRulesPath
+$canonicalTestCaseRulesPath = Join-Path $repoRoot 'templates/docs/qa/TEST_CASE_CREATION_RULES.md'
+$canonicalTestCaseRulesHash = Get-FileSha256 -Path $canonicalTestCaseRulesPath
+
+if (-not (Test-Path -LiteralPath $skillsSrc)) {
+  throw "Missing skills directory: $skillsSrc"
+}
+
+$codexHome = $env:CODEX_HOME
+if (-not $codexHome) {
+  $codexHome = Join-Path $HOME '.codex'
+}
+
+$skillsDest = Join-Path $codexHome 'skills'
+New-Item -ItemType Directory -Force -Path $skillsDest | Out-Null
+
+Get-ChildItem -LiteralPath $skillsSrc -Directory | ForEach-Object {
+  $dest = Join-Path $skillsDest $_.Name
+  if (Test-Path -LiteralPath $dest) {
+    if (-not $Force) {
+      Write-Warning "Skill already installed (skipping). Use -Force to overwrite: $($_.Name)"
+      $existingSkillRulesPath = Join-Path $dest 'references/FLOWCHART_CREATION_RULES.md'
+      $existingSkillRulesHash = Get-FileSha256 -Path $existingSkillRulesPath
+      if ($existingSkillRulesHash) {
+        if ($canonicalRulesHash -and ($existingSkillRulesHash -eq $canonicalRulesHash)) {
+          Write-Host "  - Existing ruleset: FLOWCHART_CREATION_RULES.md (SHA256=$existingSkillRulesHash, source-sync=OK)"
+        } elseif ($canonicalRulesHash) {
+          Write-Warning "  - Existing ruleset hash mismatch for $($_.Name): skill=$existingSkillRulesHash template=$canonicalRulesHash"
+        } else {
+          Write-Host "  - Existing ruleset: FLOWCHART_CREATION_RULES.md (SHA256=$existingSkillRulesHash)"
+        }
+      }
+      $existingFlowRulesPath = Join-Path $dest 'references/FLOW_ACTION_SPEC_CREATION_RULES.md'
+      $existingFlowRulesHash = Get-FileSha256 -Path $existingFlowRulesPath
+      if ($existingFlowRulesHash) {
+        if ($canonicalFlowRulesHash -and ($existingFlowRulesHash -eq $canonicalFlowRulesHash)) {
+          Write-Host "  - Existing ruleset: FLOW_ACTION_SPEC_CREATION_RULES.md (SHA256=$existingFlowRulesHash, source-sync=OK)"
+        } elseif ($canonicalFlowRulesHash) {
+          Write-Warning "  - Existing ruleset hash mismatch for $($_.Name): skill=$existingFlowRulesHash template=$canonicalFlowRulesHash"
+        } else {
+          Write-Host "  - Existing ruleset: FLOW_ACTION_SPEC_CREATION_RULES.md (SHA256=$existingFlowRulesHash)"
+        }
+      }
+      $existingApiDesignRulesPath = Join-Path $dest 'references/API_DESIGN_CREATION_RULES.md'
+      $existingApiDesignRulesHash = Get-FileSha256 -Path $existingApiDesignRulesPath
+      if ($existingApiDesignRulesHash) {
+        if ($canonicalApiDesignRulesHash -and ($existingApiDesignRulesHash -eq $canonicalApiDesignRulesHash)) {
+          Write-Host "  - Existing ruleset: API_DESIGN_CREATION_RULES.md (SHA256=$existingApiDesignRulesHash, source-sync=OK)"
+        } elseif ($canonicalApiDesignRulesHash) {
+          Write-Warning "  - Existing ruleset hash mismatch for $($_.Name): skill=$existingApiDesignRulesHash template=$canonicalApiDesignRulesHash"
+        } else {
+          Write-Host "  - Existing ruleset: API_DESIGN_CREATION_RULES.md (SHA256=$existingApiDesignRulesHash)"
+        }
+      }
+      $existingTestCaseRulesPath = Join-Path $dest 'references/TEST_CASE_CREATION_RULES.md'
+      $existingTestCaseRulesHash = Get-FileSha256 -Path $existingTestCaseRulesPath
+      if ($existingTestCaseRulesHash) {
+        if ($canonicalTestCaseRulesHash -and ($existingTestCaseRulesHash -eq $canonicalTestCaseRulesHash)) {
+          Write-Host "  - Existing ruleset: TEST_CASE_CREATION_RULES.md (SHA256=$existingTestCaseRulesHash, source-sync=OK)"
+        } elseif ($canonicalTestCaseRulesHash) {
+          Write-Warning "  - Existing ruleset hash mismatch for $($_.Name): skill=$existingTestCaseRulesHash template=$canonicalTestCaseRulesHash"
+        } else {
+          Write-Host "  - Existing ruleset: TEST_CASE_CREATION_RULES.md (SHA256=$existingTestCaseRulesHash)"
+        }
+      }
+      return
+    }
+    Remove-Item -LiteralPath $dest -Recurse -Force
+  }
+  Copy-Item -LiteralPath $_.FullName -Destination $dest -Recurse -Force
+  Write-Host "Installed: $($_.Name)"
+
+  $skillRulesPath = Join-Path $dest 'references/FLOWCHART_CREATION_RULES.md'
+  $skillRulesHash = Get-FileSha256 -Path $skillRulesPath
+  if ($skillRulesHash) {
+    if ($canonicalRulesHash -and ($skillRulesHash -eq $canonicalRulesHash)) {
+      Write-Host "  - Ruleset: FLOWCHART_CREATION_RULES.md (SHA256=$skillRulesHash, source-sync=OK)"
+    } elseif ($canonicalRulesHash) {
+      Write-Warning "  - Ruleset hash mismatch for $($_.Name): skill=$skillRulesHash template=$canonicalRulesHash"
+    } else {
+      Write-Host "  - Ruleset: FLOWCHART_CREATION_RULES.md (SHA256=$skillRulesHash)"
+    }
+  }
+
+  $skillFlowRulesPath = Join-Path $dest 'references/FLOW_ACTION_SPEC_CREATION_RULES.md'
+  $skillFlowRulesHash = Get-FileSha256 -Path $skillFlowRulesPath
+  if ($skillFlowRulesHash) {
+    if ($canonicalFlowRulesHash -and ($skillFlowRulesHash -eq $canonicalFlowRulesHash)) {
+      Write-Host "  - Ruleset: FLOW_ACTION_SPEC_CREATION_RULES.md (SHA256=$skillFlowRulesHash, source-sync=OK)"
+    } elseif ($canonicalFlowRulesHash) {
+      Write-Warning "  - Ruleset hash mismatch for $($_.Name): skill=$skillFlowRulesHash template=$canonicalFlowRulesHash"
+    } else {
+      Write-Host "  - Ruleset: FLOW_ACTION_SPEC_CREATION_RULES.md (SHA256=$skillFlowRulesHash)"
+    }
+  }
+
+  $skillApiDesignRulesPath = Join-Path $dest 'references/API_DESIGN_CREATION_RULES.md'
+  $skillApiDesignRulesHash = Get-FileSha256 -Path $skillApiDesignRulesPath
+  if ($skillApiDesignRulesHash) {
+    if ($canonicalApiDesignRulesHash -and ($skillApiDesignRulesHash -eq $canonicalApiDesignRulesHash)) {
+      Write-Host "  - Ruleset: API_DESIGN_CREATION_RULES.md (SHA256=$skillApiDesignRulesHash, source-sync=OK)"
+    } elseif ($canonicalApiDesignRulesHash) {
+      Write-Warning "  - Ruleset hash mismatch for $($_.Name): skill=$skillApiDesignRulesHash template=$canonicalApiDesignRulesHash"
+    } else {
+      Write-Host "  - Ruleset: API_DESIGN_CREATION_RULES.md (SHA256=$skillApiDesignRulesHash)"
+    }
+  }
+
+  $skillTestCaseRulesPath = Join-Path $dest 'references/TEST_CASE_CREATION_RULES.md'
+  $skillTestCaseRulesHash = Get-FileSha256 -Path $skillTestCaseRulesPath
+  if ($skillTestCaseRulesHash) {
+    if ($canonicalTestCaseRulesHash -and ($skillTestCaseRulesHash -eq $canonicalTestCaseRulesHash)) {
+      Write-Host "  - Ruleset: TEST_CASE_CREATION_RULES.md (SHA256=$skillTestCaseRulesHash, source-sync=OK)"
+    } elseif ($canonicalTestCaseRulesHash) {
+      Write-Warning "  - Ruleset hash mismatch for $($_.Name): skill=$skillTestCaseRulesHash template=$canonicalTestCaseRulesHash"
+    } else {
+      Write-Host "  - Ruleset: TEST_CASE_CREATION_RULES.md (SHA256=$skillTestCaseRulesHash)"
+    }
+  }
+}
+
+Write-Host ""
+Write-Host "Skills installed into: $skillsDest"
+if ($canonicalRulesHash) {
+  Write-Host "Canonical API ruleset: $canonicalRulesPath"
+  Write-Host "Canonical API ruleset SHA256: $canonicalRulesHash"
+} else {
+  Write-Warning "Canonical API ruleset not found: $canonicalRulesPath"
+}
+if ($canonicalApiDesignRulesHash) {
+  Write-Host "Canonical API design ruleset: $canonicalApiDesignRulesPath"
+  Write-Host "Canonical API design ruleset SHA256: $canonicalApiDesignRulesHash"
+} else {
+  Write-Warning "Canonical API design ruleset not found: $canonicalApiDesignRulesPath"
+}
+if ($canonicalFlowRulesHash) {
+  Write-Host "Canonical Flow Action ruleset: $canonicalFlowRulesPath"
+  Write-Host "Canonical Flow Action ruleset SHA256: $canonicalFlowRulesHash"
+} else {
+  Write-Warning "Canonical Flow Action ruleset not found: $canonicalFlowRulesPath"
+}
+if ($canonicalTestCaseRulesHash) {
+  Write-Host "Canonical Test Case ruleset: $canonicalTestCaseRulesPath"
+  Write-Host "Canonical Test Case ruleset SHA256: $canonicalTestCaseRulesHash"
+} else {
+  Write-Warning "Canonical Test Case ruleset not found: $canonicalTestCaseRulesPath"
+}
+Write-Host "Restart Codex to pick up new skills."