takomi 2.1.38 → 2.1.40

package/assets/Takomi-Agents/vibe-architect.yaml

@@ -8,8 +8,8 @@ customModes:
       an excellent planner. Your goal is to gather information, understand context,
       and create detailed, actionable plans for accomplishing the user's task.
 
-      You do NOT write implementation code - you design the solution. You create
-      technical specifications, design system architecture, and break down complex
+      You do NOT write implementation code - you create the technical plan. You create
+      technical specifications, system architecture, and break down complex
       problems into clear steps that builders can execute.
     whenToUse: >-
       Use /vibe-architect when:
@@ -21,7 +21,7 @@ customModes:
       - Evaluating different approaches
       - Creating PRDs (Project Requirements Documents)
       - Designing APIs and data models
-      - Creating design systems and mockups
+      - Creating UI/UX design handoff requirements without replacing `/vibe-design`
     groups:
       - read
       - - edit
@@ -39,7 +39,7 @@ customModes:
       │                    ARCHITECT MODE PATTERN                    │
       ├─────────────────────────────────────────────────────────────┤
       │                                                              │
-      │   GATHER ──► ANALYZE ──► DESIGN ──► PLAN ──► HANDOFF        │
+      │   GATHER ──► ANALYZE ──► TECHNICAL DESIGN ──► PLAN ──► HANDOFF │
       │      │          │         │        │        │               │
       │      ▼          ▼         ▼        ▼        ▼               │
       │  Requirements Context   Solution  Steps   Builder           │
@@ -139,7 +139,12 @@ customModes:
       > **Trade-offs:**
       > - [What we give up]
 
-      ## Phase 3: Design
+      ## Phase 3: Technical Design
+
+      This is technical planning, not the Takomi `/vibe-design` lifecycle stage.
+      Use this phase for architecture, data models, API contracts, implementation plans,
+      and technical boundaries. Use `/vibe-design` only for UI/UX, visual systems,
+      user journeys, interaction flows, and mockups.
 
       ### 3.1 Data Models
 
@@ -173,7 +178,7 @@ customModes:
 
       ### 3.3 Component Architecture
 
-      Design the UI structure:
+      Define the technical UI/component structure:
 
       ```
       App

package/assets/Takomi-Agents/vibe-orchestrator.yaml

@@ -157,7 +157,7 @@ customModes:
       |----------|-----------|---------------|---------|
       | /vibe-primeAgent | ✅ Always | ALL tasks | Load project context |
       | /vibe-genesis | ✅ Yes | Phase 1: Planning | Generate PRD + issues |
-      | /vibe-design | ✅ Yes | Phase 2: Design | Design system + mockups |
+      | /vibe-design | ✅ Yes | Phase 2: UI/UX Design | Design system + mockups |
       | /vibe-build | ✅ Yes | Phase 3: Build | Scaffold + implement |
       | /vibe-continueBuild | ⚠️ Maybe | Phase 3b | Resume incomplete builds |
       | /vibe-finalize | ✅ Yes | Phase 4: Quality | Verify + document |
@@ -705,7 +705,7 @@ customModes:
       | Work Type | Assigned Mode | Default Workflow | Default Skills |
       |-----------|---------------|------------------|----------------|
       | Architecture & Planning | `vibe-architect` | `/vibe-genesis` | `nextjs-standards` |
-      | Design & UI | `vibe-architect` | `/vibe-design` | `ui-ux-pro-max`, `frontend-design` |
+      | UI/UX Design | `vibe-architect` | `/vibe-design` | `ui-ux-pro-max`, `frontend-design` |
       | Implementation | `vibe-code` | `/vibe-build` | `nextjs-standards`, `context7` |
       | AI Features | `vibe-code` | — | `ai-sdk` |
       | Debugging | `vibe-debug` | — | — |

package/docs/features/TakomiFlow_Portable_Plugin.md

@@ -0,0 +1,82 @@
+# TakomiFlow Portable Plugin
+
+## Goal
+
+Move the proven TakomiFlow Google Flow automation into this repository as the source-of-truth portable package so users and agents can install it on fresh machines, reuse existing trusted Chrome sessions, and operate through MCP when available or CLI when not.
+
+## Components
+
+### Codex Plugin
+
+- `plugins/takomi-flow/`
+  - source-of-truth plugin package
+  - bundled skill, MCP server, CLI, schemas, prompts, and provider contract
+  - branded icon assets for store listing, dark mode, and composer surfaces
+  - browser automation scripts for trusted Chrome attach and Flow generation
+- `.agents/plugins/marketplace.json`
+  - repo-local marketplace entry for `takomi-flow`
+- `scripts/install-takomi-flow.ps1`
+  - optional installer for copying/registering the plugin into user/global Codex plugin paths
+- `assets/.agent/skills/takomi-flow/SKILL.md`
+  - standalone harness-visible skill for agents that do not load Codex plugin skills
+  - merged install/repair and runtime workflow instructions so agents have one TakomiFlow entrypoint
+
+### Agent Surface
+
+- First-run agents should run `doctor`, then check whether `http://127.0.0.1:9222` is already serving Chrome DevTools Protocol.
+- If CDP is alive, agents should reuse it.
+- If CDP is missing, agents should start `trusted-chrome` and ask the user to sign into Google Flow manually.
+- For repeated generations, agents should reuse the current Flow project tab or pass `projectUrl`; clicking `New project` requires explicit `allowNewProject`.
+- If a project chat is stale or broken, agents should recover by creating a fresh chat inside the same project before asking for manual intervention.
+- Agents should prefer MCP tools when the harness supports MCP and the plugin is installed.
+- Agents should offer plugin installation/repair in Codex only after user approval.
+- Agents should fall back to CLI commands and standalone skill instructions when MCP or plugins are absent.
+
+### Runtime Surface
+
+- CLI-first core: `node scripts/takomi-flow.mjs <command>`.
+- MCP adapter: `node scripts/mcp-server.mjs`.
+- Browser profile: user-local trusted Chrome profile by default.
+- Outputs: run folders with `run.json`, `assets.json`, `report.md`, screenshots, downloads, and optional video frames.
+
+## Data Flow
+
+1. Agent discovers or installs the plugin from this repo.
+2. Agent runs readiness checks.
+3. Agent checks for an existing trusted Chrome CDP instance.
+4. Agent reuses the instance or launches trusted Chrome.
+5. User signs in manually when needed.
+6. Agent resolves the target project from `projectUrl` or the current project tab.
+7. Agent prepares and validates a Flow request.
+8. Agent submits only with explicit spend approval.
+9. Agent records `projectUrl`, downloads assets, catalogs outputs, and writes a report.
+
+## Database Schema
+
+No database is required.
+
+Persistent state is file-based:
+
+- request JSON under `requests/`
+- run metadata in `run.json`
+- asset metadata in `assets.json`
+- Markdown handoff in `report.md`
+
+## Install / Portability Rules
+
+- MCP is optional, not required.
+- A harness without MCP can still use the CLI and skill instructions.
+- A fresh computer can bootstrap by running the repo installer or directly invoking the plugin CLI from this repo.
+- Global/user writes must be explicit installer actions, not hidden side effects.
+- Project URLs must be captured for every generated Flow project.
+- New Flow projects are opt-in; project reuse is the default.
+
+## Verification
+
+- Plugin validation should pass with the Codex plugin validator.
+- Skill validation should pass with the Codex skill validator.
+- MCP smoke should pass when Node dependencies are installed.
+- CLI `doctor`, `capabilities`, `template`, `workflow`, `inspect`, `assets`, and `report` should work without MCP.
+- Store art should resolve from `assets/logo.png`, `assets/logo-dark.png`, and `assets/composer-icon.png`.
+- Store examples should show real creative workflows, not only a generic safe browser workflow prompt.
+- The generated neon TakomiFlow icon is used as the plugin logo and composer icon source.

package/docs/takomi-flow-onboarding.md

@@ -0,0 +1,86 @@
+# TakomiFlow Onboarding
+
+TakomiFlow is packaged in this repo at `plugins/takomi-flow`.
+
+## First Run
+
+If all you have is a skill, use the bundled `takomi-flow` skill. It is the single front door: it can operate an already-installed plugin through MCP or CLI, install or repair the Codex plugin after user approval, or stay in skill/CLI mode for harnesses that do not support Codex plugins.
+
+1. Install or register the plugin:
+
+   ```powershell
+   ./scripts/install-takomi-flow.ps1 -InstallDependencies
+   ```
+
+2. Check the local runtime:
+
+   ```powershell
+   node plugins/takomi-flow/scripts/takomi-flow.mjs doctor
+   ```
+
+3. Check whether a trusted Chrome instance is already running:
+
+   ```powershell
+   Invoke-WebRequest http://127.0.0.1:9222/json/version -UseBasicParsing
+   ```
+
+4. If Chrome is already running on port `9222`, reuse it with:
+
+   ```powershell
+   --cdp-url http://127.0.0.1:9222
+   ```
+
+5. If Chrome is not running, launch it:
+
+   ```powershell
+   node plugins/takomi-flow/scripts/takomi-flow.mjs trusted-chrome
+   ```
+
+6. Sign into Google Flow manually in the opened browser.
+
+7. Run a no-spend observe before generation:
+
+   ```powershell
+   node plugins/takomi-flow/scripts/takomi-flow.mjs observe --allow-browser --cdp-url http://127.0.0.1:9222
+   ```
+
+## Reusing One Flow Project
+
+For repeated generations, leave trusted Chrome open on the Flow project editor and reuse it:
+
+```powershell
+node plugins/takomi-flow/scripts/takomi-flow.mjs workflow --kind video --prompt "cinematic lab scene" --project-url "https://labs.google/fx/tools/flow/project/..." --submit --allow-browser --allow-spend --cdp-url http://127.0.0.1:9222
+```
+
+TakomiFlow does not click `New project` unless `--allow-new-project` is set. If a chat surface is stale or broken, it tries one fresh chat inside the same project before asking for manual help.
+
+## MCP Or CLI
+
+- If the harness supports MCP, use TakomiFlow MCP tools.
+- If MCP is unavailable, use the CLI commands directly.
+- If a harness has neither MCP nor shell access, use the skill instructions as a handoff checklist for a human/operator.
+
+Generation is always spend-gated. Use `--allow-spend` only after explicit approval.
+
+## Finding It In Codex
+
+After this repo is installed or registered, Codex should show:
+
+- `Takomi Codex` under the `J StaR Films Studios` marketplace section.
+- `TakomiFlow` under the same marketplace section.
+
+On the developer machine, a second `TakomiFlow` may also appear under `Personal` if `scripts/install-takomi-flow.ps1` copied the plugin into `~/plugins/takomi-flow` and registered `~/.agents/plugins/marketplace.json`. That personal entry is useful for local testing; the repo entry is the package source other people should install.
+
+People can search for:
+
+- `TakomiFlow`
+- `Flow`
+- `Google Flow`
+- `image generation`
+- `video generation`
+- `asset pipeline`
+- `Takomi`
+
+If they only have the skill and not the plugin, search/install:
+
+- `takomi-flow`

package/docs/takomi-flow-public-distribution.md

@@ -0,0 +1,94 @@
+# TakomiFlow Public Distribution
+
+TakomiFlow is packaged in this repo, but users need one distribution path before it can appear in their Codex Store.
+
+## NPM Package Strategy
+
+Do not create a second npm package by default.
+
+TakomiFlow should ship inside the existing `takomi` / VibeCode Protocol Suite package:
+
+- `plugins/takomi-flow` contains the Codex plugin.
+- `assets/.agent/skills/takomi-flow` contains the standalone non-plugin skill for harnesses that read bundled skills, plus the install/repair instructions for Codex plugin use.
+- `scripts/install-takomi-flow.ps1` installs/registers the bundled plugin into the user's global Codex plugin location.
+
+A separate `takomi-flow` npm package would only be useful later if TakomiFlow needs independent versioning, releases, or dependencies. For now, keeping it inside the existing suite avoids duplicated publishing, duplicated docs, and version drift.
+
+## Best Path
+
+Publish or distribute the VibeCode Protocol Suite, then let users install the TakomiFlow plugin from the suite bundle.
+
+Once they have the suite from GitHub or the published `takomi` package:
+
+```powershell
+git clone https://github.com/JStaRFilms/VibeCode-Protocol-Suite "$HOME\Source\VibeCode-Protocol-Suite"
+cd "$HOME\Source\VibeCode-Protocol-Suite"
+.\scripts\install-takomi-flow.ps1 -InstallDependencies
+```
+
+That installs:
+
+```text
+~/plugins/takomi-flow
+~/.agents/plugins/marketplace.json
+```
+
+Then Codex can show TakomiFlow in the personal/store plugin list.
+
+## Skill-Only Bootstrap
+
+If a user only has skills and no plugin yet, give them the bundled `takomi-flow` skill. That one skill teaches Codex or another harness how to:
+
+1. Check whether TakomiFlow is already installed.
+2. Clone or locate the VibeCode Protocol Suite.
+3. Run `scripts/install-takomi-flow.ps1`.
+4. Install dependencies.
+5. Verify the plugin with `doctor`.
+6. Reuse or launch trusted Chrome.
+
+This is the lightest path when the full plugin is not installed yet, while avoiding a confusing second TakomiFlow installer skill.
+
+## MCP Is Optional
+
+TakomiFlow should be useful in three tiers:
+
+- Full Codex plugin and MCP tools when the harness supports them.
+- CLI-only operation when MCP is unavailable.
+- Skill-only install instructions when the plugin is missing.
+
+The CLI entrypoint remains:
+
+```powershell
+node "$HOME\plugins\takomi-flow\scripts\takomi-flow.mjs" <command>
+```
+
+## Store Search Terms
+
+Users should be able to find it by searching:
+
+- `TakomiFlow`
+- `Takomi Flow`
+- `Google Flow`
+- `Flow automation`
+- `image generation`
+- `video generation`
+- `asset pipeline`
+- `Takomi`
+
+## Publishing Checklist
+
+Before telling users it is public:
+
+1. Push this repo to GitHub.
+2. Confirm `plugins/takomi-flow` is included.
+3. Confirm `assets/.agent/skills/takomi-flow` is included.
+4. Confirm `npm pack --dry-run` includes TakomiFlow files but not `plugins/takomi-flow/node_modules`.
+5. Publish/update the existing `takomi` npm package or release archive.
+6. Test on a clean user profile:
+
+   ```powershell
+   .\scripts\install-takomi-flow.ps1 -InstallDependencies
+   node "$HOME\plugins\takomi-flow\scripts\takomi-flow.mjs" doctor
+   ```
+
+7. Open Codex Store and search `TakomiFlow`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "takomi",
-  "version": "2.1.38",
+  "version": "2.1.40",
   "description": "🎯 Stop wrestling with AI. Start building with purpose. The artisan's toolkit for agent workflows, Codex skills, and original Takomi capabilities like 21st.dev integration.",
   "type": "module",
   "bin": {
@@ -10,6 +10,20 @@
     "bin",
     "src",
     "assets",
+    "docs/takomi-flow-onboarding.md",
+    "docs/takomi-flow-public-distribution.md",
+    "docs/features/TakomiFlow_Portable_Plugin.md",
+    "plugins/takomi-codex",
+    "plugins/takomi-flow/.codex-plugin",
+    "plugins/takomi-flow/.mcp.json",
+    "plugins/takomi-flow/assets",
+    "plugins/takomi-flow/package.json",
+    "plugins/takomi-flow/pnpm-lock.yaml",
+    "plugins/takomi-flow/references",
+    "plugins/takomi-flow/scripts",
+    "plugins/takomi-flow/skills",
+    ".agents/plugins/marketplace.json",
+    "scripts/install-takomi-flow.ps1",
     ".pi/README.md",
     ".pi/agents",
     ".pi/extensions",
@@ -26,7 +40,10 @@
     "test": "npm run test:typecheck && npm run test:regressions && npm run test:skills",
     "test:typecheck": "tsc --noEmit",
     "test:regressions": "node scripts/test-regressions.js",
-    "test:skills": "node scripts/test-skill-selection.js"
+    "test:skills": "node scripts/test-skill-selection.js",
+    "takomi-flow:doctor": "node plugins/takomi-flow/scripts/takomi-flow.mjs doctor",
+    "takomi-flow:selftest": "node plugins/takomi-flow/scripts/takomi-flow.mjs selftest",
+    "takomi-flow:mcp-smoke": "node plugins/takomi-flow/scripts/mcp-smoke.mjs"
   },
   "repository": {
     "type": "git",

package/plugins/takomi-codex/.codex-plugin/plugin.json

@@ -0,0 +1,37 @@
+{
+  "name": "takomi-codex",
+  "version": "0.1.0+codex.20260628231636",
+  "description": "Takomi orchestration, policy, and roadbook adapter for Codex.",
+  "author": {
+    "name": "J StaR Films Studios"
+  },
+  "license": "ISC",
+  "keywords": [
+    "takomi",
+    "codex",
+    "orchestration",
+    "pi",
+    "roadbooks"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Takomi Codex",
+    "shortDescription": "Use Takomi lifecycle orchestration inside Codex.",
+    "longDescription": "Takomi Codex brings Takomi's Genesis, Design, Build, review, policy, and markdown roadbook workflows into Codex while adapting to local Pi/Takomi runtime state when present.",
+    "developerName": "J StaR Films Studios",
+    "category": "Productivity",
+    "capabilities": [
+      "Write",
+      "Interactive"
+    ],
+    "defaultPrompt": [
+      "Use Takomi to plan this feature.",
+      "Create a Takomi roadbook for this work.",
+      "Inspect the local Takomi runtime."
+    ],
+    "brandColor": "#18CFE4",
+    "composerIcon": "./assets/composer-icon.png",
+    "logo": "./assets/logo.png",
+    "logoDark": "./assets/logo-dark.png"
+  }
+}

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

@@ -0,0 +1,197 @@
+param(
+  [ValidateSet("create", "show", "add-task", "update-task", "complete-task", "summary")]
+  [string]$Action = "show",
+  [string]$Root,
+  [string]$SessionId,
+  [string]$Title = "Takomi Codex Session",
+  [string]$TaskId,
+  [string]$TaskTitle,
+  [string]$Objective,
+  [ValidateSet("pending", "in-progress", "completed", "blocked")]
+  [string]$Status,
+  [string]$Notes
+)
+
+$ErrorActionPreference = "Stop"
+
+function Get-DefaultRoot {
+  $pluginRoot = Split-Path -Parent $PSScriptRoot
+  $pluginsRoot = Split-Path -Parent $pluginRoot
+  return Split-Path -Parent $pluginsRoot
+}
+
+function New-SafeSlug([string]$Text) {
+  $value = ($Text ?? "task").ToLowerInvariant()
+  $value = $value -replace "[^a-z0-9]+", "-"
+  $value = $value.Trim("-")
+  if (-not $value) { return "task" }
+  return $value.Substring(0, [Math]::Min(48, $value.Length))
+}
+
+function New-SessionId {
+  return "orch-" + (Get-Date -Format "yyyyMMdd-HHmmss")
+}
+
+function Get-BoardRoot([string]$ProjectRoot) {
+  return Join-Path $ProjectRoot "docs\tasks\orchestrator-sessions"
+}
+
+function Get-SessionRoot([string]$ProjectRoot, [string]$Id) {
+  return Join-Path (Get-BoardRoot $ProjectRoot) $Id
+}
+
+function Assert-SafeId([string]$Value, [string]$Name) {
+  if ($Value -notmatch "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$") {
+    throw "$Name must use only letters, numbers, hyphen, or underscore."
+  }
+}
+
+function Ensure-SessionFolders([string]$PathValue) {
+  foreach ($folder in @("", "pending", "in-progress", "completed", "blocked")) {
+    $target = if ($folder) { Join-Path $PathValue $folder } else { $PathValue }
+    New-Item -ItemType Directory -Force -Path $target | Out-Null
+  }
+}
+
+function Get-TaskPath([string]$SessionRoot, [string]$Folder, [string]$Id, [string]$TaskName) {
+  $slug = New-SafeSlug $TaskName
+  return Join-Path (Join-Path $SessionRoot $Folder) "$Id`_$slug.task.md"
+}
+
+function Find-TaskFile([string]$SessionRoot, [string]$Id) {
+  foreach ($folder in @("pending", "in-progress", "completed", "blocked")) {
+    $dir = Join-Path $SessionRoot $folder
+    $match = Get-ChildItem -LiteralPath $dir -Filter "$Id`_*.task.md" -ErrorAction SilentlyContinue | Select-Object -First 1
+    if ($match) { return $match.FullName }
+  }
+  return $null
+}
+
+function Write-MasterPlan([string]$PathValue, [string]$Name) {
+  $text = @"
+# $Name
+
+## Goal
+
+Define the work, route it through Takomi, and keep progress visible.
+
+## Context Intake
+
+- Project requirements reviewed: pending
+- Feature docs reviewed: pending
+- Runtime policy reviewed: pending
+
+## Execution Mode
+
+- Direct Codex work when sufficient
+- Markdown roadbook for coordination
+- Pi/Takomi or multi-agent/subagent delegation only when useful and available
+- User-owned Codex threads only when explicitly requested or recommended and approved
+
+## Tasks
+
+| Task | Status | Notes |
+| --- | --- | --- |
+
+## Verification
+
+- [ ] Required docs updated
+- [ ] Implementation verified
+- [ ] Summary written
+"@
+  Set-Content -LiteralPath (Join-Path $PathValue "master_plan.md") -Value $text -Encoding UTF8
+}
+
+$projectRoot = if ($Root) { $Root } else { Get-DefaultRoot }
+$projectRoot = (Resolve-Path -LiteralPath $projectRoot).Path
+
+if (-not $SessionId -and $Action -eq "create") { $SessionId = New-SessionId }
+if (-not $SessionId) {
+  $boardRoot = Get-BoardRoot $projectRoot
+  $latest = Get-ChildItem -LiteralPath $boardRoot -Directory -ErrorAction SilentlyContinue |
+    Sort-Object LastWriteTime -Descending |
+    Select-Object -First 1
+  if ($latest) { $SessionId = $latest.Name }
+}
+if (-not $SessionId) { throw "SessionId is required. Use -Action create first." }
+Assert-SafeId $SessionId "SessionId"
+
+$sessionRoot = Get-SessionRoot $projectRoot $SessionId
+
+switch ($Action) {
+  "create" {
+    Ensure-SessionFolders $sessionRoot
+    if (-not (Test-Path -LiteralPath (Join-Path $sessionRoot "master_plan.md"))) {
+      Write-MasterPlan $sessionRoot $Title
+    }
+    Write-Output "Created Takomi roadbook: $sessionRoot"
+    Write-Output "SessionId: $SessionId"
+  }
+  "show" {
+    if (-not (Test-Path -LiteralPath $sessionRoot)) { throw "Roadbook not found: $sessionRoot" }
+    Write-Output "Takomi roadbook: $sessionRoot"
+    foreach ($folder in @("pending", "in-progress", "completed", "blocked")) {
+      $count = @(Get-ChildItem -LiteralPath (Join-Path $sessionRoot $folder) -Filter "*.task.md" -ErrorAction SilentlyContinue).Count
+      Write-Output "  $folder`: $count"
+    }
+  }
+  "add-task" {
+    if (-not $TaskTitle) { throw "TaskTitle is required." }
+    Ensure-SessionFolders $sessionRoot
+    $existing = Get-ChildItem -LiteralPath (Join-Path $sessionRoot "pending") -Filter "*.task.md" -ErrorAction SilentlyContinue
+    if (-not $TaskId) { $TaskId = ("T{0:000}" -f ($existing.Count + 1)) }
+    Assert-SafeId $TaskId "TaskId"
+    $taskPath = Get-TaskPath $sessionRoot "pending" $TaskId $TaskTitle
+    $text = @"
+# $TaskId - $TaskTitle
+
+## Objective
+
+$($Objective ?? $TaskTitle)
+
+## Agent Setup
+
+- Follow the Takomi Codex skill.
+- Load relevant project docs and policies before implementation.
+- Update this task file with outcome notes.
+
+## Definition Of Done
+
+- [ ] Scope completed
+- [ ] Docs updated where needed
+- [ ] Verification recorded
+
+## Notes
+
+$Notes
+"@
+    Set-Content -LiteralPath $taskPath -Value $text -Encoding UTF8
+    Write-Output "Added task: $taskPath"
+  }
+  "update-task" {
+    if (-not $TaskId) { throw "TaskId is required." }
+    if (-not $Status) { $Status = "in-progress" }
+    Assert-SafeId $TaskId "TaskId"
+    $taskPath = Find-TaskFile $sessionRoot $TaskId
+    if (-not $taskPath) { throw "Task not found: $TaskId" }
+    $target = Join-Path (Join-Path $sessionRoot $Status) (Split-Path -Leaf $taskPath)
+    if ($taskPath -ne $target) { Move-Item -LiteralPath $taskPath -Destination $target -Force }
+    if ($Notes) { Add-Content -LiteralPath $target -Value "`n## Update $(Get-Date -Format s)`n`n$Notes" -Encoding UTF8 }
+    Write-Output "Updated task $TaskId -> $Status"
+  }
+  "complete-task" {
+    & $PSCommandPath -Action update-task -Root $projectRoot -SessionId $SessionId -TaskId $TaskId -Status completed -Notes $Notes
+  }
+  "summary" {
+    Ensure-SessionFolders $sessionRoot
+    $summary = Join-Path $sessionRoot "Orchestrator_Summary.md"
+    $lines = @("# Orchestrator Summary", "", "Session: $SessionId", "", "## Task Counts", "")
+    foreach ($folder in @("pending", "in-progress", "completed", "blocked")) {
+      $count = @(Get-ChildItem -LiteralPath (Join-Path $sessionRoot $folder) -Filter "*.task.md" -ErrorAction SilentlyContinue).Count
+      $lines += "- $folder`: $count"
+    }
+    $lines += @("", "## Notes", "", ($Notes ?? "No summary notes recorded."))
+    Set-Content -LiteralPath $summary -Value $lines -Encoding UTF8
+    Write-Output "Wrote summary: $summary"
+  }
+}