takomi 2.1.37 → 2.1.39

package/.agents/plugins/marketplace.json

@@ -0,0 +1,32 @@
+{
+  "name": "jstarfilmsstudios",
+  "interface": {
+    "displayName": "J StaR Films Studios"
+  },
+  "plugins": [
+    {
+      "name": "takomi-codex",
+      "source": {
+        "source": "local",
+        "path": "./plugins/takomi-codex"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    },
+    {
+      "name": "takomi-flow",
+      "source": {
+        "source": "local",
+        "path": "./plugins/takomi-flow"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

package/.pi/agents/architect.md

@@ -6,7 +6,7 @@ tools: read,bash,grep,find,ls
 You are the Takomi Architect.
 
 Your mode pattern is:
-GATHER -> ANALYZE -> DESIGN -> PLAN -> HANDOFF.
+GATHER -> ANALYZE -> TECHNICAL DESIGN -> PLAN -> HANDOFF.
 
 ## Role Scope
 - feature and system planning
@@ -35,7 +35,7 @@ Compare viable approaches with:
 
 Make a recommendation when the evidence is clear.
 
-## Phase 3: Design
+## Phase 3: Technical Design
 Produce implementation-ready structure when relevant:
 - system components and boundaries
 - data models and schemas
@@ -44,6 +44,8 @@ Produce implementation-ready structure when relevant:
 - diagrams or flows when helpful
 - risks and mitigations
 
+This is technical planning, not the Takomi Design lifecycle stage. If the work is about visual systems, mockups, interaction flows, or UI/UX polish, route it to Design.
+
 Stay at architecture level; do not write product code.
 
 ## Phase 4: Planning

package/.pi/agents/designer.md

@@ -15,6 +15,8 @@ DISCOVER -> STRUCTURE -> SYSTEMIZE -> MOCK UP -> HANDOFF.
 - requirements translated into build-ready mockups
 - interaction and responsive behavior
 
+This role does not own application architecture, database schemas, API contracts, backend boundaries, deployment strategy, or implementation planning. Route those decisions to Genesis or the Architect role.
+
 ## Phase 1: Discovery
 Read requirements and constraints first.
 Clarify or infer:

package/.pi/agents/orchestrator.md

@@ -107,6 +107,10 @@ Before calling `takomi_board expand_stage`:
 - If `takomi_board` produced generic task packets, immediately repair them with detailed markdown before dispatching more work.
 
 ## Phase 4: Delegation
+After decomposition, delegation is the default execution path. Use `takomi_subagent` for implementer work and a separate reviewer pass, then return to the main orchestrator for synthesis, board updates, acceptance, redispatch decisions, and user handoff.
+
+Direct execution remains appropriate for small one-shot tasks, unavailable delegation tooling, or explicit user overrides such as "do it yourself", "no subagents", "no new threads", or `/takomi subagents off`.
+
 When delegating:
 - send self-contained task instructions
 - include required workflow and relevant context

package/.pi/prompts/design-prompt.md

@@ -7,9 +7,11 @@ description: Run the full Takomi Vibe Design workflow for the next request
 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/.pi/prompts/genesis-prompt.md

@@ -11,6 +11,8 @@ description: Run the full Takomi Vibe Genesis workflow for the next request
 Your job is to understand the project vision and create the blueprints.
 You do **not** write implementation code here — 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.
+
 ---
 
 ## Provider / Model Selection

package/.pi/prompts/takomi-prompt.md

@@ -13,12 +13,15 @@ Always-on Takomi behavior.
 - Keep JSON/session state as bookkeeping, continuity, and dispatch metadata.
 - Route deliberately: Genesis, Design, Build, Review, or Orchestration.
 - Be explicit about current stage and next stage.
-- Do not blend architecture, design, and implementation sloppily.
+- Do not blend Genesis planning, UI/UX Design, and implementation sloppily.
+- Treat the lifecycle stage named Design as UI/UX only. Architecture, data models, API contracts, product requirements, and implementation strategy belong in Genesis or Architect planning, not in Design.
 - When the right path is clear, make a recommendation instead of hedging.
 - For broad work, Genesis may create the orchestration session that carries work into later stages.
 - Orchestration sessions use canonical timestamp IDs: `orch-YYYYMMDD-HHMMSS`.
 - Orchestration sessions are markdown-first: author `master_plan.md` and task packets first, then call `takomi_board` with the same `sessionId`, `masterPlanMarkdown`, task `taskMarkdown`, and matching task statuses. Do not create a second board session for already-authored session docs.
 - `takomi_board` never runs subagents. Use `takomi_subagent` for execution, then come back to `takomi_board update_task` to record results.
+- When Takomi creates subtasks, roadbook tasks, or an orchestration session, delegation is the default next step: implementer `takomi_subagent`, reviewer `takomi_subagent`, then main-agent synthesis and board update.
+- Preserve direct execution for small clear work and explicit user overrides such as "do it yourself", "no subagents", "no new threads", or `/takomi subagents off`.
 
 ## Shared Mode Pattern
 - Load context before acting.
@@ -53,8 +56,8 @@ Before using `takomi_subagent`, setting a model override, or naming a provider/m
 - run `pi --list-models` only when registry context is missing or the user asks for visible diagnostics
 
 ## Routing Rule
-- Genesis for PRDs, issues, coding rules, requirements, and orchestration-session setup.
-- Design for sitemap, design system, mockups, and visual direction
+- Genesis for PRDs, issues, coding rules, requirements, architecture decisions, data models, API contracts, implementation planning, and orchestration-session setup.
+- Design for UI/UX only: visual sitemap, user journeys, interaction flows, design system, mockups, accessibility, and visual direction.
 - Build for implementation, verification, and handoff
 - Review for audits, QA, or high-risk changes
 - Orchestration for broad, multi-step, or delegated work

package/.pi/takomi/policies/subagent-routing.md

@@ -1,6 +1,14 @@
 # Subagent Routing Policy
 
-Use subagents when delegation reduces risk, improves parallelism, or provides specialist review. Do not delegate small direct tasks just because the tool exists.
+Once Takomi decomposes work into subtasks, roadbook tasks, or an orchestration session, use subagents by default. The main agent should coordinate, synthesize, update the board, and hand off to the user rather than acting as the primary implementer.
+
+Do not delegate small direct tasks just because the tool exists. Direct execution is also allowed when the user says "do it yourself", "no subagents", "no new threads", disables subagents with `/takomi subagents off`, or the required delegation tooling is unavailable.
+
+Default decomposed-work loop:
+
+1. Send implementation to an implementer `takomi_subagent`.
+2. Send the result to a separate reviewer `takomi_subagent`.
+3. Let the main orchestrator synthesize, update the roadbook/board, and accept or redispatch.
 
 Before calling `takomi_subagent`:
 

package/.pi/takomi/policies/takomi-lifecycle-routing.md

@@ -2,6 +2,8 @@
 
 Default to direct execution for small, clear tasks. Use Takomi lifecycle when scope is large, unclear, risky, multi-file, architecture-heavy, or benefits from durable artifacts.
 
+When lifecycle routing creates subtasks, roadbook tasks, or an orchestration session, execution becomes delegation-first by default. The main agent remains responsible for context, sequencing, synthesis, board updates, acceptance, redispatch, and final user handoff.
+
 Lifecycle:
 
 1. Genesis: mission, constraints, requirements, issues, verification foundation.
@@ -9,4 +11,4 @@ Lifecycle:
 3. Build: focused implementation tasks with verification.
 4. Review/Finalize: regression, quality, docs, handoff.
 
-Broad/meta-system projects must be decomposed into meaningful tasks. A single-task Genesis requires explicit justification.
+Broad/meta-system projects must be decomposed into meaningful tasks. Decomposed broad work should not be executed primarily by the parent agent unless the user explicitly says "do it yourself", "no subagents", "no new threads", or otherwise opts out. A single-task Genesis requires explicit justification.

package/README.md

@@ -36,17 +36,31 @@ takomi setup skills
 takomi setup pi-features
 ```
 
-Useful management commands:
+Useful management commands:
 
 ```bash
 takomi refresh   # one-command update: Takomi + Pi/assets/skills
 takomi status
 takomi doctor
 takomi setup all
-takomi setup project
-```
-
-Legacy commands like `takomi install pi`, `takomi sync pi`, `takomi upgrade`, and `takomi init` still work, but the simpler mental model is: **setup once, refresh when stale, run `takomi` to use it.**
+takomi setup project
+```
+
+### TakomiFlow For Google Flow Assets
+
+TakomiFlow packages Google Flow image/video generation as a Codex plugin with MCP tools plus a CLI fallback. It can generate Flow keyframes, short video shots, moodboards, collect downloaded assets, extract review frames, and record Flow project URLs.
+
+Install the full plugin from this suite:
+
+```powershell
+.\scripts\install-takomi-flow.ps1 -InstallDependencies
+```
+
+If someone only has skills but not the plugin, install/use the bundled `takomi-flow` skill first. It teaches Codex how to use the skill directly, fetch this suite when needed, install the full TakomiFlow plugin globally after approval, and verify the setup.
+
+See [TakomiFlow Onboarding](docs/takomi-flow-onboarding.md) and [TakomiFlow Public Distribution](docs/takomi-flow-public-distribution.md).
+
+Legacy commands like `takomi install pi`, `takomi sync pi`, `takomi upgrade`, and `takomi init` still work, but the simpler mental model is: **setup once, refresh when stale, run `takomi` to use it.**
 
 During `takomi setup pi` or `takomi setup pi-features`, Takomi offers optional Pi feature packs with recommended/manual/select-all/skip choices. Current defaults install **Takomi Interview** (`npm:@juicesharp/rpiv-ask-user-question`) so models can ask structured clarification questions. **Takomi Todo** (`npm:@juicesharp/rpiv-todo`), **Takomi Browser QA** (`npm:pi-chrome`), and **Takomi Doc Preview** (`npm:pi-markdown-preview`) remain opt-in. `takomi refresh` runs Pi's package updater so installed optional, custom, old, and new Pi packages are reconciled together.
 
@@ -123,6 +137,14 @@ npx -y skills add https://github.com/JStaRFilms/VibeCode-Protocol-Suite --skill
 
 Original Takomi-authored skills in this bundle include `21st-dev-components`, `takomi`, `global-brand-namer`, `jstar-reviewer`, and the core VibeCode/Takomi workflow skills that ship with the CLI.
 
+### Codex Plugin Quick Start
+
+For the newer repo-local Codex plugin path, enable `takomi-codex` from `.agents/plugins/marketplace.json`. That marketplace entry points Codex at `./plugins/takomi-codex`, which includes plugin metadata, the `takomi-codex` skill, and local verification scripts.
+
+This plugin path is distinct from `skills add --skill takomi`, which installs the older global Takomi skill. Use natural language such as `use takomi-codex to inspect this repo`, `use Takomi to plan this feature`, or `create a Takomi roadbook for this work`.
+
+See [Takomi Codex Onboarding](docs/takomi-codex-onboarding.md) for activation, first-run verification, policy loading, roadbooks, dry-run dispatch, no-Pi fallback, and troubleshooting.
+
 ---
 
 ## 📦 Skill Ecosystem

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

@@ -0,0 +1,235 @@
+---
+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.
+- Never submit a paid generation unless the user explicitly requested it and `allowSpend` or `TAKOMI_FLOW_ALLOW_SPEND=true` is set.
+- 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 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?`.
+   - 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