takomi 2.1.38 → 2.1.39

package/plugins/takomi-codex/scripts/takomi-detect.ps1

@@ -0,0 +1,125 @@
+param(
+  [string]$Root,
+  [switch]$Json
+)
+
+$ErrorActionPreference = "Stop"
+
+function Get-DefaultRoot {
+  $pluginRoot = Split-Path -Parent $PSScriptRoot
+  $pluginsRoot = Split-Path -Parent $pluginRoot
+  return Split-Path -Parent $pluginsRoot
+}
+
+function Resolve-PathSafe([string]$PathValue) {
+  if ([string]::IsNullOrWhiteSpace($PathValue)) { return $null }
+  try { return (Resolve-Path -LiteralPath $PathValue -ErrorAction Stop).Path } catch { return $PathValue }
+}
+
+function Test-File([string]$PathValue) {
+  return [bool](Test-Path -LiteralPath $PathValue -PathType Leaf)
+}
+
+function Test-Dir([string]$PathValue) {
+  return [bool](Test-Path -LiteralPath $PathValue -PathType Container)
+}
+
+function Get-CommandInfo([string]$Name, [string[]]$VersionArgs) {
+  $cmd = Get-Command $Name -ErrorAction SilentlyContinue
+  if (-not $cmd) {
+    return [pscustomobject]@{ available = $false; path = $null; version = $null }
+  }
+
+  $version = $null
+  foreach ($args in $VersionArgs) {
+    try {
+      $parts = $args -split " "
+      $output = & $cmd.Source @parts 2>$null | Select-Object -First 1
+      if ($output) {
+        $version = [string]$output
+        break
+      }
+    } catch { }
+  }
+
+  return [pscustomobject]@{
+    available = $true
+    path = $cmd.Source
+    version = $version
+  }
+}
+
+$projectRoot = Resolve-PathSafe ($(if ($Root) { $Root } else { Get-DefaultRoot }))
+$homeDir = [Environment]::GetFolderPath("UserProfile")
+$pluginRoot = Split-Path -Parent $PSScriptRoot
+
+$projectPi = Join-Path $projectRoot ".pi"
+$projectAgents = Join-Path $projectPi "agents"
+$projectPrompts = Join-Path $projectPi "prompts"
+$projectPolicies = Join-Path $projectPi "takomi\policies"
+$projectSettings = Join-Path $projectPi "settings.json"
+$projectProfile = Join-Path $projectPi "takomi-profile.json"
+$projectRouting = Join-Path $projectPi "takomi\model-routing.md"
+$roadbooks = Join-Path $projectRoot "docs\tasks\orchestrator-sessions"
+
+$userPiAgent = Join-Path $homeDir ".pi\agent"
+$userAgentsSkills = Join-Path $homeDir ".agents\skills"
+
+$result = [pscustomobject]@{
+  projectRoot = $projectRoot
+  pluginRoot = $pluginRoot
+  project = [pscustomobject]@{
+    pi = Test-Dir $projectPi
+    settings = Test-File $projectSettings
+    profile = Test-File $projectProfile
+    routingPolicy = Test-File $projectRouting
+    policies = Test-Dir $projectPolicies
+    agents = Test-Dir $projectAgents
+    prompts = Test-Dir $projectPrompts
+    roadbooks = Test-Dir $roadbooks
+  }
+  user = [pscustomobject]@{
+    piAgent = Test-Dir $userPiAgent
+    agentsSkills = Test-Dir $userAgentsSkills
+  }
+  cli = [pscustomobject]@{
+    takomi = Get-CommandInfo "takomi" @("--version", "version")
+    pi = Get-CommandInfo "pi" @("--version", "version")
+  }
+  paths = [pscustomobject]@{
+    projectPi = $projectPi
+    projectSettings = $projectSettings
+    projectProfile = $projectProfile
+    projectRouting = $projectRouting
+    projectPolicies = $projectPolicies
+    roadbooks = $roadbooks
+    userPiAgent = $userPiAgent
+    userAgentsSkills = $userAgentsSkills
+  }
+}
+
+if ($Json) {
+  $result | ConvertTo-Json -Depth 8
+  exit 0
+}
+
+Write-Output "Takomi Codex detection"
+Write-Output "Project: $($result.projectRoot)"
+Write-Output "Plugin:  $($result.pluginRoot)"
+Write-Output ""
+Write-Output "Project runtime:"
+Write-Output "  .pi:             $($result.project.pi)"
+Write-Output "  settings:        $($result.project.settings)"
+Write-Output "  profile:         $($result.project.profile)"
+Write-Output "  routing policy:  $($result.project.routingPolicy)"
+Write-Output "  policies:        $($result.project.policies)"
+Write-Output "  agents/prompts:  $($result.project.agents) / $($result.project.prompts)"
+Write-Output "  roadbooks:       $($result.project.roadbooks)"
+Write-Output ""
+Write-Output "User runtime:"
+Write-Output "  ~/.pi/agent:     $($result.user.piAgent)"
+Write-Output "  ~/.agents/skills:$($result.user.agentsSkills)"
+Write-Output ""
+Write-Output "CLI:"
+Write-Output "  takomi:          $($result.cli.takomi.available) $($result.cli.takomi.version)"
+Write-Output "  pi:              $($result.cli.pi.available) $($result.cli.pi.version)"

package/plugins/takomi-codex/scripts/takomi-doctor.ps1

@@ -0,0 +1,88 @@
+param(
+  [string]$Root
+)
+
+$ErrorActionPreference = "Stop"
+
+function Get-DefaultRoot {
+  $pluginRoot = Split-Path -Parent $PSScriptRoot
+  $pluginsRoot = Split-Path -Parent $pluginRoot
+  return Split-Path -Parent $pluginsRoot
+}
+
+function Add-Check([System.Collections.Generic.List[object]]$Checks, [string]$Name, [bool]$Ok, [string]$Detail, [string]$Fix = "") {
+  $Checks.Add([pscustomobject]@{
+    name = $Name
+    ok = $Ok
+    detail = $Detail
+    fix = $Fix
+  }) | Out-Null
+}
+
+function Test-JsonFile([string]$PathValue) {
+  try {
+    Get-Content -Raw -LiteralPath $PathValue | ConvertFrom-Json | Out-Null
+    return $true
+  } catch {
+    return $false
+  }
+}
+
+$projectRoot = if ($Root) { $Root } else { Get-DefaultRoot }
+$projectRoot = (Resolve-Path -LiteralPath $projectRoot).Path
+$pluginRoot = Split-Path -Parent $PSScriptRoot
+$manifest = Join-Path $pluginRoot ".codex-plugin\plugin.json"
+$skillFile = Join-Path $pluginRoot "skills\takomi-codex\SKILL.md"
+$detectScript = Join-Path $pluginRoot "scripts\takomi-detect.ps1"
+$boardScript = Join-Path $pluginRoot "scripts\takomi-board.ps1"
+$policyScript = Join-Path $pluginRoot "scripts\takomi-policy.ps1"
+$dispatchScript = Join-Path $pluginRoot "scripts\takomi-pi-dispatch.ps1"
+$harnessScript = Join-Path $pluginRoot "scripts\takomi-harness.ps1"
+
+$checks = [System.Collections.Generic.List[object]]::new()
+
+Add-Check $checks "plugin manifest exists" (Test-Path -LiteralPath $manifest -PathType Leaf) $manifest
+Add-Check $checks "plugin manifest is valid json" (Test-JsonFile $manifest) $manifest
+
+if (Test-Path -LiteralPath $manifest -PathType Leaf) {
+  $parsed = Get-Content -Raw -LiteralPath $manifest | ConvertFrom-Json
+  Add-Check $checks "plugin name" ($parsed.name -eq "takomi-codex") "name=$($parsed.name)"
+  Add-Check $checks "skills path" ($parsed.skills -eq "./skills/") "skills=$($parsed.skills)"
+  Add-Check $checks "default prompts array" ($parsed.interface.defaultPrompt -is [array]) "defaultPrompt type=$($parsed.interface.defaultPrompt.GetType().Name)" "Use an array with up to three prompts."
+}
+
+Add-Check $checks "skill entrypoint exists" (Test-Path -LiteralPath $skillFile -PathType Leaf) $skillFile
+Add-Check $checks "detect script exists" (Test-Path -LiteralPath $detectScript -PathType Leaf) $detectScript
+Add-Check $checks "board script exists" (Test-Path -LiteralPath $boardScript -PathType Leaf) $boardScript
+Add-Check $checks "policy script exists" (Test-Path -LiteralPath $policyScript -PathType Leaf) $policyScript
+Add-Check $checks "dispatch script exists" (Test-Path -LiteralPath $dispatchScript -PathType Leaf) $dispatchScript
+Add-Check $checks "harness script exists" (Test-Path -LiteralPath $harnessScript -PathType Leaf) $harnessScript
+
+$detect = & $detectScript -Root $projectRoot -Json | ConvertFrom-Json
+Add-Check $checks "project root readable" (Test-Path -LiteralPath $projectRoot -PathType Container) $projectRoot
+Add-Check $checks "project .pi detected" ([bool]$detect.project.pi) $detect.paths.projectPi "Run takomi setup project if this repo should have a local Pi runtime."
+Add-Check $checks "project routing policy detected" ([bool]$detect.project.routingPolicy) $detect.paths.projectRouting "Add .pi/takomi/model-routing.md if model routing should be project-owned."
+Add-Check $checks "takomi cli available" ([bool]$detect.cli.takomi.available) ($detect.cli.takomi.path ?? "missing") "Install or expose the takomi CLI if Pi dispatch should be available."
+Add-Check $checks "pi cli available" ([bool]$detect.cli.pi.available) ($detect.cli.pi.path ?? "missing") "Install or expose Pi if direct Pi launch should be available."
+
+$failed = $checks | Where-Object { -not $_.ok }
+
+Write-Output "Takomi Codex doctor"
+Write-Output "Project: $projectRoot"
+Write-Output "Plugin:  $pluginRoot"
+Write-Output ""
+
+foreach ($check in $checks) {
+  $mark = if ($check.ok) { "OK " } else { "WARN" }
+  Write-Output "[$mark] $($check.name): $($check.detail)"
+  if (-not $check.ok -and $check.fix) {
+    Write-Output "      fix: $($check.fix)"
+  }
+}
+
+Write-Output ""
+if ($failed.Count -eq 0) {
+  Write-Output "Takomi Codex doctor passed."
+} else {
+  Write-Output "Takomi Codex doctor found $($failed.Count) item(s) to review."
+}

package/plugins/takomi-codex/scripts/takomi-harness.ps1

@@ -0,0 +1,52 @@
+param(
+  [ValidateSet("status", "harnesses", "sync", "setup", "refresh")]
+  [string]$Action = "status",
+  [string]$Root,
+  [string]$Target = "",
+  [switch]$Execute
+)
+
+$ErrorActionPreference = "Stop"
+
+function Get-DefaultRoot {
+  $pluginRoot = Split-Path -Parent $PSScriptRoot
+  $pluginsRoot = Split-Path -Parent $pluginRoot
+  return Split-Path -Parent $pluginsRoot
+}
+
+function Get-Takomi {
+  $cmd = Get-Command "takomi" -ErrorAction SilentlyContinue
+  if (-not $cmd) { throw "takomi CLI is not available." }
+  return $cmd.Source
+}
+
+$projectRoot = if ($Root) { $Root } else { Get-DefaultRoot }
+$projectRoot = (Resolve-Path -LiteralPath $projectRoot).Path
+$takomi = Get-Takomi
+
+$argsList = switch ($Action) {
+  "status" { @("status") }
+  "harnesses" { @("harnesses") }
+  "sync" { if ($Target) { @("sync", $Target) } else { @("sync") } }
+  "setup" { if ($Target) { @("setup", $Target) } else { @("setup") } }
+  "refresh" { if ($Target) { @("refresh", $Target) } else { @("refresh") } }
+}
+
+Write-Output "Takomi harness bridge"
+Write-Output "Project: $projectRoot"
+Write-Output "Mode:    $(if ($Execute) { "execute" } else { "dry-run" })"
+Write-Output "Command: $takomi $($argsList -join ' ')"
+Write-Output ""
+
+if (-not $Execute) {
+  Write-Output "Dry run only. Re-run with -Execute after confirming the target harness and write scope."
+  exit 0
+}
+
+Push-Location $projectRoot
+try {
+  & $takomi @argsList
+  exit $LASTEXITCODE
+} finally {
+  Pop-Location
+}

package/plugins/takomi-codex/scripts/takomi-pi-dispatch.ps1

@@ -0,0 +1,93 @@
+param(
+  [ValidateSet("status", "doctor", "launch", "takomi", "pi")]
+  [string]$Action = "status",
+  [string]$Root,
+  [string]$ArgsLine = "",
+  [switch]$Execute
+)
+
+$ErrorActionPreference = "Stop"
+
+function Get-DefaultRoot {
+  $pluginRoot = Split-Path -Parent $PSScriptRoot
+  $pluginsRoot = Split-Path -Parent $pluginRoot
+  return Split-Path -Parent $pluginsRoot
+}
+
+function Get-Tool([string]$Name) {
+  return Get-Command $Name -ErrorAction SilentlyContinue
+}
+
+function Split-ArgsLine([string]$Text) {
+  if ([string]::IsNullOrWhiteSpace($Text)) { return @() }
+  return [System.Management.Automation.PSParser]::Tokenize($Text, [ref]$null) |
+    Where-Object { $_.Type -in @("CommandArgument", "String", "Number") } |
+    ForEach-Object { $_.Content }
+}
+
+$projectRoot = if ($Root) { $Root } else { Get-DefaultRoot }
+$projectRoot = (Resolve-Path -LiteralPath $projectRoot).Path
+$takomi = Get-Tool "takomi"
+$pi = Get-Tool "pi"
+
+Write-Output "Takomi Pi dispatch"
+Write-Output "Project: $projectRoot"
+Write-Output "Mode:    $(if ($Execute) { "execute" } else { "dry-run" })"
+Write-Output ""
+
+if (-not $takomi) { Write-Output "takomi CLI: missing" } else { Write-Output "takomi CLI: $($takomi.Source)" }
+if (-not $pi) { Write-Output "pi CLI:     missing" } else { Write-Output "pi CLI:     $($pi.Source)" }
+Write-Output ""
+
+if ($Action -eq "status") {
+  Write-Output "Recommended diagnostics:"
+  Write-Output "  .\takomi-detect.ps1 -Root `"$projectRoot`""
+  Write-Output "  .\takomi-policy.ps1 -Root `"$projectRoot`""
+  Write-Output "  takomi doctor"
+  exit 0
+}
+
+$command = $null
+$commandArgs = @()
+
+switch ($Action) {
+  "doctor" {
+    if (-not $takomi) { throw "takomi CLI is not available." }
+    $command = $takomi.Source
+    $commandArgs = @("doctor")
+  }
+  "launch" {
+    if (-not $takomi) { throw "takomi CLI is not available." }
+    $command = $takomi.Source
+    $commandArgs = @()
+  }
+  "takomi" {
+    if (-not $takomi) { throw "takomi CLI is not available." }
+    $command = $takomi.Source
+    $commandArgs = Split-ArgsLine $ArgsLine
+  }
+  "pi" {
+    if (-not $pi) { throw "pi CLI is not available." }
+    $command = $pi.Source
+    $commandArgs = Split-ArgsLine $ArgsLine
+  }
+}
+
+if (-not $command) { throw "No command resolved for action '$Action'." }
+
+Write-Output "Resolved command:"
+Write-Output "  $command $($commandArgs -join ' ')"
+Write-Output ""
+
+if (-not $Execute) {
+  Write-Output "Dry run only. Re-run with -Execute to execute this command."
+  exit 0
+}
+
+Push-Location $projectRoot
+try {
+  & $command @commandArgs
+  exit $LASTEXITCODE
+} finally {
+  Pop-Location
+}

package/plugins/takomi-codex/scripts/takomi-policy.ps1

@@ -0,0 +1,108 @@
+param(
+  [string]$Root,
+  [switch]$Json
+)
+
+$ErrorActionPreference = "Stop"
+
+function Get-DefaultRoot {
+  $pluginRoot = Split-Path -Parent $PSScriptRoot
+  $pluginsRoot = Split-Path -Parent $pluginRoot
+  return Split-Path -Parent $pluginsRoot
+}
+
+function Read-TextSafe([string]$PathValue) {
+  if (Test-Path -LiteralPath $PathValue -PathType Leaf) {
+    return Get-Content -Raw -LiteralPath $PathValue
+  }
+  return $null
+}
+
+function Read-JsonSafe([string]$PathValue) {
+  if (Test-Path -LiteralPath $PathValue -PathType Leaf) {
+    try { return Get-Content -Raw -LiteralPath $PathValue | ConvertFrom-Json } catch { return $null }
+  }
+  return $null
+}
+
+function Get-PolicyFiles([string]$Dir) {
+  if (-not (Test-Path -LiteralPath $Dir -PathType Container)) { return @() }
+  return Get-ChildItem -LiteralPath $Dir -File -ErrorAction SilentlyContinue |
+    Where-Object { $_.Extension -in @(".md", ".json", ".txt") } |
+    Sort-Object Name |
+    ForEach-Object {
+      [pscustomobject]@{
+        name = $_.Name
+        path = $_.FullName
+        preview = ((Get-Content -Raw -LiteralPath $_.FullName) -split "\r?\n" | Select-Object -First 8) -join "`n"
+      }
+    }
+}
+
+$projectRoot = if ($Root) { $Root } else { Get-DefaultRoot }
+$projectRoot = (Resolve-Path -LiteralPath $projectRoot).Path
+$homeDir = [Environment]::GetFolderPath("UserProfile")
+
+$projectSettingsPath = Join-Path $projectRoot ".pi\settings.json"
+$projectProfilePath = Join-Path $projectRoot ".pi\takomi-profile.json"
+$projectRoutingPath = Join-Path $projectRoot ".pi\takomi\model-routing.md"
+$projectPoliciesDir = Join-Path $projectRoot ".pi\takomi\policies"
+
+$userRoutingPath = Join-Path $homeDir ".pi\agent\takomi\model-routing.md"
+$userPoliciesDir = Join-Path $homeDir ".pi\agent\takomi\policies"
+
+$result = [pscustomobject]@{
+  projectRoot = $projectRoot
+  project = [pscustomobject]@{
+    settingsPath = $projectSettingsPath
+    settings = Read-JsonSafe $projectSettingsPath
+    profilePath = $projectProfilePath
+    profile = Read-JsonSafe $projectProfilePath
+    routingPath = $projectRoutingPath
+    routing = Read-TextSafe $projectRoutingPath
+    policies = Get-PolicyFiles $projectPoliciesDir
+  }
+  user = [pscustomobject]@{
+    routingPath = $userRoutingPath
+    routing = Read-TextSafe $userRoutingPath
+    policies = Get-PolicyFiles $userPoliciesDir
+  }
+}
+
+if ($Json) {
+  $result | ConvertTo-Json -Depth 10
+  exit 0
+}
+
+Write-Output "Takomi policy context"
+Write-Output "Project: $projectRoot"
+Write-Output ""
+Write-Output "Project settings: $projectSettingsPath"
+if ($result.project.settings) { $result.project.settings | ConvertTo-Json -Depth 6 } else { Write-Output "  missing or invalid" }
+Write-Output ""
+Write-Output "Project profile: $projectProfilePath"
+if ($result.project.profile) { $result.project.profile | ConvertTo-Json -Depth 8 } else { Write-Output "  missing or invalid" }
+Write-Output ""
+Write-Output "Project model routing: $projectRoutingPath"
+if ($result.project.routing) { Write-Output $result.project.routing } else { Write-Output "  missing" }
+Write-Output ""
+Write-Output "Project policy files:"
+if ($result.project.policies.Count) {
+  foreach ($policy in $result.project.policies) {
+    Write-Output "  - $($policy.name): $($policy.path)"
+  }
+} else {
+  Write-Output "  none"
+}
+Write-Output ""
+Write-Output "User/global model routing: $userRoutingPath"
+if ($result.user.routing) { Write-Output $result.user.routing } else { Write-Output "  missing" }
+Write-Output ""
+Write-Output "User/global policy files:"
+if ($result.user.policies.Count) {
+  foreach ($policy in $result.user.policies) {
+    Write-Output "  - $($policy.name): $($policy.path)"
+  }
+} else {
+  Write-Output "  none"
+}

package/plugins/takomi-codex/skills/takomi-codex/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: takomi-codex
+description: Use Takomi lifecycle orchestration inside Codex with policy-aware runtime detection, markdown roadbooks, optional Pi/Takomi dispatch, and explicit-consent delegation.
+---
+
+# Takomi Codex
+
+Takomi Codex is the Codex-native adapter for the Takomi protocol. Use it when the user asks for Takomi, orchestration, roadbooks, Genesis/Design/Build lifecycle work, policy-aware execution, Pi/Takomi runtime inspection, or delegated task coordination.
+
+## Operating Principle
+
+Choose the smallest execution mode that can do the work well, then delegate by default once Takomi decomposes the work:
+
+1. Direct Codex work for small, local, one-shot tasks.
+2. Planning mode for unclear or UI/UX-heavy work.
+3. Markdown roadbook orchestration for broad multi-step work.
+4. Delegation-first orchestration when Takomi creates subtasks, roadbook tasks, or an orchestration session.
+
+Do not create a board, launch a harness, or spawn threads for trivial edits.
+
+The main Codex agent remains the orchestrator for decomposed work. It owns context intake, task packets, board updates, synthesis, verification, and final user handoff. It should not act as the primary implementer by default after decomposition begins.
+
+User override is explicit: if the user says "do it yourself", "no subagents", "no new threads", or equivalent, the main agent may execute directly while still keeping any existing roadbook current.
+
+## Required Context Pass
+
+Before complex code or orchestration, inspect the project:
+
+- `docs/features/`
+- `docs/project_requirements.md`
+- `docs/Project_Requirements.md`
+- local `.pi/` if relevant
+- Takomi feature docs related to the request
+
+For major features, create or update a feature markdown file before implementation.
+
+## Runtime Detection
+
+Use `scripts/takomi-detect.ps1` when runtime state affects the answer.
+
+Detection priority:
+
+1. Project-local `.pi/`.
+2. User/global `~/.pi/agent/` and `~/.agents/skills/`.
+3. CLI availability for `takomi` and `pi`.
+4. Plugin-bundled guidance.
+
+Global/user paths are read-only unless the user explicitly approves a write.
+
+## Policy Loading
+
+Use `scripts/takomi-policy.ps1` when model, subagent, review, or lifecycle routing matters.
+
+Respect project policy first:
+
+- `.pi/settings.json`
+- `.pi/takomi-profile.json`
+- `.pi/takomi/model-routing.md`
+- `.pi/takomi/policies/`
+
+Avoid hard-coding personal model names as universal defaults. Prefer provider-qualified model IDs only when the active policy or runtime registry supports them.
+
+## Roadbook Orchestration
+
+Use `scripts/takomi-board.ps1` for broad work that needs durable coordination.
+
+Markdown roadbooks are the durable source of truth for orchestration state, even when Pi, subagents, multi-agent tools, explicitly requested Codex threads, or optional JSON tracking are used.
+
+Roadbooks live at:
+
+```text
+docs/tasks/orchestrator-sessions/<sessionId>/
+```
+
+The markdown layer is primary:
+
+- `master_plan.md`
+- `pending/*.task.md`
+- `in-progress/*.task.md`
+- `completed/*.task.md`
+- `blocked/*.task.md`
+- `Orchestrator_Summary.md`
+
+JSON tracking is optional and should not replace readable markdown.
+
+## Delegation-First Loop
+
+When a request is broad enough to create subtasks, roadbook tasks, or an orchestration session:
+
+1. Create or update the markdown roadbook and task packets.
+2. Delegate implementation to an implementer subagent or child thread.
+3. Delegate review to a separate reviewer subagent or child thread.
+4. Synthesize results in the main thread.
+5. Update the roadbook, then accept the work or redispatch with a tighter packet.
+
+In Pi, prefer `takomi_subagent` for implementer and reviewer runs. In Codex, prefer available multi-agent or subagent tools for delegated subtasks. If those tools are unavailable, create markdown task packets and execute directly as the fallback. Use user-owned Codex child threads only when the user explicitly asks for new threads, handoff threads, or parallel thread orchestration, or when the parent agent recommends that route and the user approves it.
+
+## Lifecycle Modes
+
+### Genesis
+
+Use for project foundations, requirements, feature planning, and issue-style task breakdowns.
+
+Expected artifacts:
+
+- PRD or project requirements update
+- feature docs
+- task/issue docs
+- acceptance criteria
+
+### Design
+
+Use for UI/UX only: visual systems, screen structure, user journeys, interaction flows, mockups, accessibility expectations, and frontend handoff constraints.
+
+Do not use Design for application architecture, data models, API/interface contracts, backend service boundaries, deployment strategy, or implementation task planning. Route that work to Genesis or Architect planning.
+
+Expected artifacts:
+
+- visual design notes or specs
+- screen/component appearance plan
+- interaction and responsive behavior
+- accessibility and usability constraints
+
+### Build
+
+Use for implementation after enough context exists.
+
+Expected behavior:
+
+- implement iteratively
+- keep files focused
+- update docs alongside code
+- verify with available tests or scripts
+
+### Review
+
+Use for bug finding, quality gates, security review, and completion audits.
+
+Expected behavior:
+
+- lead with findings
+- verify artifacts before marking complete
+- record unresolved risks
+
+## Pi/Takomi Bridge
+
+Use `scripts/takomi-pi-dispatch.ps1` conservatively.
+
+Default behavior is dry-run recommendation. Only run real Pi/Takomi commands when:
+
+- the user explicitly asks for it, or
+- an active policy calls for it and the action is safe, or
+- the command is diagnostic/read-only.
+
+Do not assume raw subagent tools are present. Prefer Takomi-facing surfaces when available.
+
+When Pi orchestration is active, prefer `takomi_subagent` over direct implementation for decomposed work.
+
+## Other Harnesses
+
+Use `scripts/takomi-harness.ps1` when a project policy or user request points to other Takomi-supported harnesses.
+
+Default behavior is dry-run. Before running with `-Execute`:
+
+- confirm the target harness or Takomi command
+- understand whether it will write user/global files
+- prefer `status` or `harnesses` before `sync`, `setup`, or `refresh`
+- keep Codex as the parent coordinator unless the user explicitly hands off execution
+
+## Codex Delegation
+
+When Takomi decomposition makes delegation appropriate:
+
+1. Search for available multi-agent or subagent tools with `tool_search` when delegation would materially help.
+2. Give each delegate a self-contained task packet path and definition of done.
+3. Keep the parent thread responsible for synthesis, verification, docs, and board updates.
+4. Do not delegate tasks that require global/user config writes unless the user approved that scope.
+5. Create or fork user-owned Codex threads only when the user explicitly asks for new threads, handoff threads, or parallel thread orchestration, or when the parent agent recommends that route and the user approves it.
+
+If delegation tooling is unavailable, fall back to markdown task packets and direct Codex execution.
+
+## File Size Discipline
+
+Keep plugin scripts and skill files modular. If a file approaches 200 lines, split responsibilities instead of growing one giant file.
+
+## Completion Rule
+
+Before handoff:
+
+- update the relevant feature doc
+- update the roadbook if one exists
+- run the plugin validator when plugin files changed
+- run script smoke checks when scripts changed
+- state what was verified and what remains unverified