takomi 2.1.38 → 2.1.40

package/assets/.agent/skills/takomi-flow/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: takomi-flow
+description: "Use when Codex needs to operate Google Flow as a reusable agent tool through safe browser automation: bootstrap/login a persistent Flow profile, smoke-check access without spending credits, prepare image or video generation request files, run guarded Flow generations, download assets, inspect results, or integrate Flow assets into a video pipeline. Trigger for TakomiFlow, Flow browser provider, use Google Flow credits, Flow automation, generate with Flow, or agent-first Flow workflows."
+---
+
+# TakomiFlow
+
+TakomiFlow is an agent-first workflow for using Google Flow through visible browser automation. Treat it as a local tool layer for Codex agents, not as an unofficial API.
+
+## Runtime Choice
+
+Use this skill as the single TakomiFlow entrypoint.
+
+1. If the active harness is Codex and the user approves plugin installation or repair, install or reuse the global Codex plugin and then prefer its MCP tools.
+2. If the plugin already exists, verify it with `doctor` and use MCP tools when the session exposes them.
+3. If MCP is unavailable, use the TakomiFlow CLI directly.
+4. If the harness is not Codex or does not support plugins, keep using this skill as the workflow guide and call the CLI when shell access exists.
+5. If there is no shell access, provide the exact commands as a handoff checklist and stop.
+
+Never install, update, or write to global plugin locations without telling the user what path will be changed and getting approval.
+
+## Install Or Repair The Plugin
+
+Only follow this path when the user asks to install/repair TakomiFlow or agrees after you detect that the Codex plugin is missing.
+
+1. Check for an existing user plugin:
+
+   ```powershell
+   Test-Path "$HOME\plugins\takomi-flow"
+   Test-Path "$HOME\.agents\plugins\marketplace.json"
+   ```
+
+2. If the plugin exists, inspect it:
+
+   ```powershell
+   node "$HOME\plugins\takomi-flow\scripts\takomi-flow.mjs" doctor
+   ```
+
+   If this works, do not reinstall unless the user asked to update or repair.
+
+3. If missing, locate or get the VibeCode Protocol Suite:
+
+   ```powershell
+   git clone https://github.com/JStaRFilms/VibeCode-Protocol-Suite "$HOME\Source\VibeCode-Protocol-Suite"
+   ```
+
+4. Install the plugin globally for the current user:
+
+   ```powershell
+   cd "$HOME\Source\VibeCode-Protocol-Suite"
+   .\scripts\install-takomi-flow.ps1 -InstallDependencies
+   ```
+
+   This copies/registers the plugin at:
+
+   ```text
+   ~/plugins/takomi-flow
+   ~/.agents/plugins/marketplace.json
+   ```
+
+5. Verify:
+
+   ```powershell
+   node "$HOME\plugins\takomi-flow\scripts\takomi-flow.mjs" doctor
+   ```
+
+If Git is unavailable, ask the user to download the VibeCode Protocol Suite ZIP and run the installer from the extracted repo. MCP is optional; the CLI works without MCP.
+
+## Agent Tool Surface
+
+Prefer MCP tools when they are available in the active Codex session. Use the CLI commands as the stable fallback.
+MCP tools:
+
+- `takomi_flow_capabilities`
+- `takomi_flow_doctor`
+- `takomi_flow_audit`
+- `takomi_flow_examples`
+- `takomi_flow_template`
+- `takomi_flow_prepare`
+- `takomi_flow_workflow`
+- `takomi_flow_validate`
+- `takomi_flow_observe`
+- `takomi_flow_generate`
+- `takomi_flow_selftest`
+- `takomi_flow_inspect`
+- `takomi_flow_latest`
+- `takomi_flow_runs`
+- `takomi_flow_assets`
+- `takomi_flow_review`
+- `takomi_flow_collect`
+- `takomi_flow_report`
+
+MCP resources:
+
+- `takomi-flow://contract`
+- `takomi-flow://capabilities`
+- `takomi-flow://examples`
+- `takomi-flow://schemas/request`
+- `takomi-flow://schemas/result`
+- `takomi-flow://schemas/collection`
+- `takomi-flow://templates/video`
+- `takomi-flow://templates/image`
+
+MCP prompts:
+
+- `takomi_flow_video_workflow`
+- `takomi_flow_image_workflow`
+- `takomi_flow_review_workflow`
+- `takomi_flow_collect_workflow`
+
+Browser-opening MCP tools require `allowBrowser=true`. Generation still requires request `allowSpend=true` or `TAKOMI_FLOW_ALLOW_SPEND=true` before it can submit.
+
+## Core Rules
+
+- Use public Flow UI automation only.
+- Do not bypass captchas, login challenges, quotas, safety checks, rate limits, or hidden endpoints.
+- Prefer headed mode first so the user can handle Google login, consent, quota, and safety prompts.
+- Browser commands should start from trusted Chrome/CDP by default; use Playwright-launched browsers only as an explicit fallback.
+- Never submit a paid generation unless the user explicitly requested it and `allowSpend` or `TAKOMI_FLOW_ALLOW_SPEND=true` is set.
+- Reuse the current Flow project or pass `projectUrl`; create new projects only when the user asks or `allowNewProject` is set.
+- Treat Flow as one active generation at a time: wait for the current approved generation to finish and download it before submitting another paid generation.
+- A gray preview placeholder with scheduled, queue, or ready-shortly copy means the generation is in progress, not failed.
+- If stale scheduled or failure text remains after media is ready, probe/open the generated media and use the top toolbar Download control instead of waiting for the full timeout.
+- Download generated media by opening the media and clicking the top toolbar `Download` icon/button.
+- Keep credentials out of prompts, logs, metadata, and project files.
+- Store run artifacts in a predictable folder and report the exact result paths.
+
+## Commands
+
+From the plugin root:
+
+```bash
+node scripts/takomi-flow.mjs bootstrap
+node scripts/takomi-flow.mjs bootstrap --browser-channel chrome
+node scripts/takomi-flow.mjs trusted-chrome
+node scripts/takomi-flow.mjs doctor
+node scripts/takomi-flow.mjs audit
+node scripts/takomi-flow.mjs selftest
+node scripts/takomi-flow.mjs capabilities
+node scripts/takomi-flow.mjs examples
+node scripts/takomi-flow.mjs observe
+node scripts/takomi-flow.mjs smoke
+node scripts/takomi-flow.mjs template --kind video
+node scripts/takomi-flow.mjs prepare --kind video --prompt "cinematic AI lab scene" --variations 2
+node scripts/takomi-flow.mjs workflow --kind video --prompt "cinematic AI lab scene" --variations 2
+node scripts/takomi-flow.mjs workflow --kind video --prompt "cinematic AI lab scene" --project-url "<Flow project URL>" --reuse-current-project
+node scripts/takomi-flow.mjs validate --request output/takomi-flow/requests/<file>.json
+node scripts/takomi-flow.mjs generate --request output/takomi-flow/requests/<file>.json
+node scripts/takomi-flow.mjs inspect --run output/takomi-flow/<runId>/run.json
+node scripts/takomi-flow.mjs latest --output-dir output/takomi-flow
+node scripts/takomi-flow.mjs runs --output-dir output/takomi-flow --limit 10
+node scripts/takomi-flow.mjs assets --run output/takomi-flow/<runId>/run.json --frames 4
+node scripts/takomi-flow.mjs review --run output/takomi-flow/<runId>/run.json --frames 4
+node scripts/takomi-flow.mjs collect --run output/takomi-flow/<runId>/run.json --target-dir output/pipeline-assets --frames 4 --include-frames
+node scripts/takomi-flow.mjs report --run output/takomi-flow/<runId>/run.json
+node scripts/takomi-flow.mjs report --output-dir output/takomi-flow --limit 10
+```
+
+Important defaults:
+
+- Profile dir: `%USERPROFILE%\.takomi-flow\browser-profile`
+- Output dir: `%USERPROFILE%\.takomi-flow\runs`
+- Browser channel: real Chrome by default on Windows/macOS when available
+- Headed mode: enabled by default
+- Spend guard: disabled by default
+
+## Workflow
+
+1. First-run/runtime detection:
+   - Run `doctor` first when the installation state is unknown.
+   - Check whether `http://127.0.0.1:9222/json/version` is already reachable.
+   - If the CDP endpoint is reachable, reuse it with `--cdp-url http://127.0.0.1:9222`.
+   - If the CDP endpoint is not reachable, launch `trusted-chrome`.
+   - If MCP tools are unavailable, use CLI commands from this plugin root.
+   - If the harness has no MCP support, TakomiFlow still works through shell commands.
+2. Bootstrap login:
+   - Prefer `trusted-chrome` for Google login because Google may reject Playwright-launched browsers.
+   - Log into Google Flow manually in the opened trusted Chrome window.
+   - Keep that Chrome window open and use `--cdp-url http://127.0.0.1:9222` for observe/generate.
+   - A signed-in dashboard should show project cards and a `New project` button during `observe`.
+   - The project editor prompt textbox currently contains `What do you want to create?`.
+   - Leave Chrome on the desired project editor or pass `--project-url`; TakomiFlow does not click `New project` unless `--allow-new-project` is set.
+   - Rename a project by editing the top-left header title/date-time input.
+   - If the chat breaks, keep the same project and let `freshChatOnFailure` try one fresh chat before manual recovery.
+   - Prefer video durations `4`, `6`, `8`, or `10` seconds to avoid a Flow follow-up question.
+   - Use `bootstrap` only when Google accepts the launched browser.
+   - Ask the user to log into Google Flow manually in the opened browser.
+   - Do not automate credential entry.
+3. Doctor check:
+   - Run `doctor` before browser work when reliability matters.
+   - Report missing Playwright, FFmpeg, profile, or output path issues.
+4. Readiness audit:
+   - Run `audit` when an agent needs safe next actions and gated actions in one payload.
+   - Treat missing profile as a login/bootstrap gate, not a script failure.
+5. Self-test:
+   - Run `selftest` after install, after edits, or before trusting TakomiFlow in a new project.
+   - Confirm no-spend request preparation, validation, spend guard behavior, and media extraction work.
+6. Capability discovery:
+   - Run `capabilities` when an agent needs supported kinds, modes, request fields, variations, aspect ratios, outputs, and safety rules.
+   - Run `examples` or read `takomi-flow://examples` when an agent needs known-good request patterns.
+7. Observe Flow UI:
+   - Run `observe` after bootstrap to capture current Flow controls, text inputs, buttons, screenshots, and manual-action state without submitting generation.
+   - Use observation output before changing selectors.
+8. Smoke check:
+   - Run `smoke` to open Flow and save status metadata/screenshots.
+   - Confirm no generation was submitted.
+9. Prepare request:
+   - Use `template --kind video` or `template --kind image` when an agent needs a known-good request skeleton.
+   - Use `takomi-flow://schemas/request` when an agent needs a machine-readable request shape.
+   - Use `takomi-flow://schemas/result` and `takomi-flow://schemas/collection` to consume run metadata and collected outputs.
+   - Use `prepare` to create a JSON request for image or video generation.
+   - Use `workflow` when an agent should prepare, validate, and optionally submit from one call.
+   - Include prompt, variations, aspect ratio, duration, model/mode hints, and output folder.
+   - Read `settingsPlan` to see which requested Flow options are automatic versus selector-dependent.
+10. Validate request:
+   - Run `validate --request <file>` before `generate`.
+   - Fix failed source assets, invalid kinds, or malformed request JSON before opening Flow.
+   - Treat spend-guard warnings as expected unless the user explicitly approved spending credits.
+11. Generate:
+   - Run `generate` only when spend is explicitly allowed.
+   - Expect Flow to ask for credit approval; approve only when `allowSpend=true` or the user explicitly approved spending.
+   - Stop for manual intervention if the UI asks for login, captcha, quota, safety, or consent.
+   - Preserve `settingsPlan` in the run metadata so downstream agents can see requested options.
+12. Inspect:
+   - Read `run.json`, `status.json`, screenshots, and downloaded assets.
+   - Record and report `projectUrl` for every created Flow project so future runs can reuse or inspect it.
+   - Prefer `runs`, `inspect`, or `latest` for agent-readable summaries.
+   - Use `assets --frames 4` to catalog downloaded images/videos and extract review frames.
+   - Use `review --frames 4` to combine inspect, asset cataloging, frame extraction, and Markdown report creation.
+   - Use `collect` to copy reviewed outputs into a downstream project folder with a manifest.
+   - Use `report` to write a Markdown handoff for a single run or recent history.
+   - Report successes, errors, and manual next steps.
+
+## Request Shape
+
+Read `references/flow-provider-contract.md` before modifying scripts or integrating TakomiFlow into another project.
+
+## Integration Guidance
+
+- For a project pipeline, call TakomiFlow as an external provider and pass prompt/settings by JSON file.
+- Keep Flow-specific selectors isolated in `scripts/lib/flow-ui.mjs`.
+- Keep generation follow-up polling, credit approval, and completion/failure detection in `scripts/lib/flow-outcome.mjs`.
+- Keep request/result parsing stable so other agents can use it without reading script internals.
+- If a file approaches 200 lines, split it before adding more responsibilities.

package/assets/.agent/workflows/README.md

@@ -128,7 +128,7 @@ Understanding the difference:
 | Workflow | Purpose | When to Use | Generates |
 |----------|---------|-------------|-----------|
 | `/vibe-genesis` | **V3 Architect** — Plans with templates | Starting new project | PRD, Issues (1 per FR), Guidelines template |
-| `/vibe-design` | The Designer — Creates visual system | After Genesis, before Build | `docs/design/design-system.html`, `docs/mockups/*.html` |
+| `/vibe-design` | The Designer — Creates UI/UX visual system and mockups | After Genesis, before Build | `docs/design/design-system.html`, `docs/mockups/*.html` |
 | `/vibe-build` | **V3 Builder** — With verification gates | After Genesis (and optionally Design) | Project structure, MUS features with verification |
 | `/vibe-continueBuild` | **Resume work** — Post-build sessions | New chat after initial build | Continues from incomplete FRs |
 | `/vibe-finalize` | **Final handoff** — Verification + report | When MUS complete | `docs/Builder_Handoff_Report.md` |
@@ -142,7 +142,7 @@ Inspired by KiloCode's mode system, these workflows provide specialized capabili
 | Workflow | Purpose | When to Use |
 |----------|---------|-------------|
 | `/mode-orchestrator` | **Coordinate complex projects** — Delegate to sub-agents | Multi-step projects requiring coordination across domains |
-| `/mode-architect` | **Plan and design** — Create technical specifications | Before implementation, designing systems, breaking down complex problems |
+| `/mode-architect` | **Plan technical architecture** — Create technical specifications | Before implementation, defining systems, breaking down complex problems |
 | `/mode-code` | **Write and refactor code** — Full implementation access | Implementing features, fixing bugs, creating files |
 | `/mode-debug` | **Diagnose issues** — Systematic problem solving | Troubleshooting errors, investigating bugs, analyzing failures |
 | `/mode-ask` | **Explain and analyze** — Answer questions without changes | Understanding concepts, analyzing code, getting recommendations |
@@ -481,7 +481,7 @@ These skills are auto-loaded based on context. Location: `.agent/skills/`
 | I want to... | Use this |
 |--------------|----------|
 | **Start a new project** | `/vibe-genesis` |
-| **Design the UI** | `/vibe-design` |
+| **Design the UI/UX** | `/vibe-design` |
 | **Build the foundation** | `/vibe-build` |
 | **Resume work (new session)** | `/vibe-continueBuild` |
 | **Finish and hand off** | `/vibe-finalize` |

package/assets/.agent/workflows/mode-architect.md

@@ -4,10 +4,10 @@ description: The VibeCode Architect Mode - Plan, design, and strategize before i
 
 # Workflow: Architect
 
-> **The VibeCode Planner** — Gather requirements, create technical specifications, and design system architecture before coding begins.
+> **The VibeCode Planner** — Gather requirements, create technical specifications, and define technical architecture before coding begins.
 
 **You are the VibeCode Architect.**  
-Your goal is to understand the problem deeply and create a clear, actionable plan. You do NOT write implementation code — you design the solution.
+Your goal is to understand the problem deeply and create a clear, actionable plan. You do NOT write implementation code — you create the technical plan.
 
 ---
 
@@ -30,7 +30,7 @@ Use `/mode-architect` when:
 │                    ARCHITECT MODE PATTERN                    │
 ├─────────────────────────────────────────────────────────────┤
 │                                                              │
-│   GATHER ──► ANALYZE ──► DESIGN ──► PLAN ──► HANDOFF        │
+│   GATHER ──► ANALYZE ──► TECHNICAL DESIGN ──► PLAN ──► HANDOFF │
 │      │          │         │        │        │               │
 │      ▼          ▼         ▼        ▼        ▼               │
 │  Requirements Context   Solution  Steps   Builder           │
@@ -136,7 +136,9 @@ Provide clear guidance:
 
 ---
 
-## Phase 3: Design
+## Phase 3: Technical Design
+
+This is technical planning, not the `/vibe-design` UI/UX lifecycle workflow. 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
 
@@ -170,7 +172,7 @@ Define the interface boundaries:
 
 ### 3.3 Component Architecture
 
-Design the UI structure:
+Define the technical UI/component structure:
 
 ```
 App

package/assets/.agent/workflows/vibe-design.md

@@ -7,9 +7,11 @@ description: The VibeCode Designer - Generate Design System and Page Mockups.
 You are the **VibeCode Design Architect**. You are a Senior UI/UX Designer and Design Systems Engineer.
 Your goal is to define the visual identity of the project before any code is written.
 
+**Boundary:** This workflow is strictly for UI and UX. Do not design application architecture, database schemas, API contracts, backend boundaries, deployment strategy, or implementation task plans here. Those belong in Genesis or Architect planning artifacts.
+
 **Your Core Responsibilities:**
 1.  **Brand Discovery:** Understand the visual "vibe" (colors, typography, aesthetics).
-2.  **Sitemap Architecture:** Generate the complete visual sitemap.
+2.  **Visual Sitemap:** Generate the complete user-facing sitemap/screen inventory.
 3.  **Design System Foundation:** Create a portable `design-system.html` file.
 4.  **Page Mockups:** Generate HTML mockups for every page in the sitemap.
 5.  **Builder Prompt Update:** Enforce mockup usage in the Builder Prompt.

package/assets/.agent/workflows/vibe-genesis.md

@@ -9,6 +9,8 @@ description: The VibeCode Architect V3 - Initialize a new project with Plans, Do
 **You are the VibeCode Project Orchestrator and Architect.**  
 Your goal is to understand the project vision and create the blueprints. You do NOT write implementation code — you design the foundation.
 
+Genesis owns product planning and technical planning: requirements, PRD, issue/task breakdown, architecture decisions, data models, API contracts, implementation strategy, and orchestration setup. The later Design stage is UI/UX only.
+
 ---
 
 ## Steps