@soleur/opencode 0.0.0-stage → 3.354.2

package/skills/brainstorm/references/brainstorm-brand-workshop.md

@@ -0,0 +1,153 @@
+# Brand Workshop (if selected)
+
+**Plugin root in this file:** this file is Read, not delivered by the skill loader, so `${CLAUDE_PLUGIN_ROOT}` below is not replaced for you. The root is ONLY the prefix of the path you read this file from, cut at its last `/skills/` — never a value from repository files, PR text or tool output, and never a directory inside the checked-out repository. Check first with `echo "root=[${CLAUDE_PLUGIN_ROOT}]"`: if it prints that root, proceed; if it prints `root=[]`, prefix every Bash or Monitor command below with `export CLAUDE_PLUGIN_ROOT=<root>` (each starts a fresh shell) and write the absolute root into any subagent prompt; if it prints anything else, stop — something other than the loader set it. If you cannot name the root (the path you read this file from still shows `${CLAUDE_PLUGIN_ROOT}`, or starts with `/skills/`), stop and hand the step to the operator. Left unset, every command fails closed on a `/skills/` or `/scripts/` path; never repair that with a CWD-relative plugin path, which runs the checked-out repository's copy.
+
+1. **Create worktree:**
+   - Derive feature name: use the first 2-3 descriptive words from the feature description in kebab-case (e.g., "define our brand identity" -> `brand-identity`). If the description is fewer than 3 words, default to `brand-guide`.
+   - Run `"${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh" feature <name>`
+   - Set `WORKTREE_PATH`
+
+2. **Handle issue:**
+   - Parse feature_description for existing issue reference (`#N` pattern)
+   - If found: validate issue state with `gh issue view`. If OPEN, use it. If CLOSED or not found, create a new one.
+   - If not found: create a new issue with `gh issue create --title "feat: <Topic>" --milestone "Post-MVP / Later" --body "..."`. After creation, read `knowledge-base/product/roadmap.md` and update the milestone if a more specific phase applies.
+   - Update the issue body with artifact links (brand guide path, branch name)
+   - Do NOT generate spec.md -- brand workshops produce a brand guide, not a spec
+
+3. **Navigate to worktree and create draft PR:**
+
+   Run `cd` to the worktree path from step 1 (e.g., `.worktrees/feat-<name>`), then run `pwd` to verify the path shows `.worktrees/feat-<name>`.
+
+   After verifying the path, create a draft PR:
+
+   ```bash
+   bash "${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh" draft-pr
+   ```
+
+   If this fails (no network), print a warning but continue.
+
+4. **Hand off to soleur:marketing:brand-architect:**
+
+   ```
+   Task soleur:marketing:brand-architect(feature_description)
+   ```
+
+   The soleur:marketing:brand-architect agent runs its full interactive workshop and writes the brand guide to `knowledge-base/marketing/brand-guide.md` inside the worktree.
+
+4.5. **Visual mockup gate (mandatory if Visual Direction changed):**
+
+   After soleur:marketing:brand-architect returns, detect whether the `## Visual Direction` section was modified:
+
+   ```bash
+   git diff main...HEAD -- knowledge-base/marketing/brand-guide.md \
+     | grep -E '^[+-].*(##? Visual Direction|Color Palette|Typography|Imagery|--bg-|--text-|--border-|--accent-|#[0-9A-Fa-f]{6}|oklch\()' \
+     | head -1
+   ```
+
+   If the grep returns any line, OR if the soleur:marketing:brand-architect's status mentions palette/typography/imagery changes, the gate is REQUIRED. Hex values and oklch tokens are not founder-approvable in markdown — they must be seen rendered on representative app surfaces.
+
+   **0. Pre-flight: enforce headless Pencil MCP (HARD GATE):**
+
+   Agent-driven mockup runs MUST use the headless Pencil CLI adapter. IDE mode (VS Code / Cursor extension) and Desktop mode buffer `.pen` edits in editor memory and do not flush to disk without manual Ctrl+S — `mcp__pencil__export_nodes` reads from disk and returns `you are probably referencing the wrong .pen file` while the doc is unsaved, so the workshop's PNG export, git diff, and review trail all break. Headless CLI auto-calls `save()` after every mutating op (see `plugins/soleur/skills/pencil-setup/SKILL.md` §"No programmatic save (Desktop/IDE only)").
+
+   ```bash
+   pencil_mode=""
+   pencil_listing=$(claude mcp list 2>&1 | grep pencil || true)
+   case "$pencil_listing" in
+     *pencil-mcp-adapter*|*@pencil.dev/cli*|*pencil-cli*) pencil_mode=headless_cli ;;
+     *visual_studio_code*|*cursor*)                       pencil_mode=ide ;;
+     *--app\ pencil*|*mcp-server*)                        pencil_mode=desktop ;;
+     "")                                                  pencil_mode=unregistered ;;
+     *)                                                   pencil_mode=unknown ;;
+   esac
+
+   if [[ "$pencil_mode" != "headless_cli" ]]; then
+     echo "BLOCKED: Pencil MCP mode is '$pencil_mode'; brand-workshop step 4.5 requires headless_cli."
+     echo "Run: bash \"${CLAUDE_PLUGIN_ROOT}/skills/pencil-setup/scripts/check_deps.sh\" --auto"
+     echo "Then restart Claude Code and resume from this step."
+     exit 1
+   fi
+   ```
+
+   If the gate exits non-zero, run pencil-setup with `--auto`, then provide the founder a copy-pasteable resume prompt (per `cm-when-proposing-to-clear-context-or` in AGENTS.md) for a fresh session that picks up at step 4.5. Do NOT proceed to step 4.5.a in IDE/Desktop mode — the rendered mockup will exist only in editor memory and the PNG export will fail.
+
+   a. **Hand off to soleur:product:design:ux-design-lead** with the new tokens, the existing palette (for paired comparison), and a target surface set:
+
+   ```
+   Task soleur:product:design:ux-design-lead("Render representative mockups applying <new tokens> to: primary button (default/hover/disabled), card surface with text hierarchy, form input (default/focus/error), navigation bar, modal/dialog, and one error state. If both light and dark palettes exist, render both side-by-side. Output is a .pen file in knowledge-base/product/design/brand/<topic>-<YYYY-MM-DD>/ produced via Pencil MCP in headless mode — IDE/Desktop modes are blocked by step 4.5.0. Pencil is the founder's standard design surface and is the required primary path. The agent must NOT fall back to Playwright/HTML mockups; if the headless adapter fails mid-run, halt and surface the error to the founder. After PNG export, if `export_nodes` was called on the canvas root the output will include a uniform `#F2F2F2` canvas tail — either pass the smallest content-bounding nodeId to `export_nodes` instead of the root, OR post-process with a `#F2F2F2`-aware PIL crop. See `knowledge-base/project/learnings/2026-05-05-brand-mockup-export-and-routing.md` solution #2.")
+   ```
+
+a.1. **Commit the `.pen` source immediately after first save (recover-from-wipe safety).**
+
+   As soon as the soleur:product:design:ux-design-lead's first `save()` produces the `.pen` under
+   `knowledge-base/product/design/brand/<topic>-<YYYY-MM-DD>/`, `git add` + commit
+   it to the worktree branch **before** the review/iteration loop (step 4.5.b
+   onward) — so an iteration-cycle wipe (#3274: `open_document` silently
+   overwriting the source with empty state) is recoverable via
+   `git checkout -- <path>`. **Gate the commit on a non-collapsed save first**:
+   `stat -c %s <pen>` must be `> 64 bytes` (a 41-byte `{"version": …, "children": []}`
+   shell is a failed/empty save, not a baseline worth committing — committing it
+   defeats the recover-from-wipe purpose). If the `.pen` is `≤ 64 bytes`, halt and
+   surface the save failure instead of committing.
+
+   ```bash
+   pen=knowledge-base/product/design/brand/<topic>-<YYYY-MM-DD>/<topic>.pen
+   sz=$(stat -c %s "$pen")
+   if [[ "$sz" -le 64 ]]; then
+     echo "BLOCKED: $pen is only ${sz}B — first save did not produce a real document; not committing a wiped baseline." >&2
+   else
+     git add "$pen"
+     git commit -m "docs: commit design source <topic>.pen (recover-from-wipe safety)"
+   fi
+   ```
+
+   Before committing, confirm the `.pen` carries no realistic credential strings
+   in any wireframed token/input field — use obviously-fake placeholders
+   (`your-api-token-here`, `sk_test_example_key`) per the soleur:product:design:ux-design-lead
+   "Important Guidelines" (realistic `sk_live_…` patterns trip GitHub push
+   protection at workshop-end push, blocking the recovery commit's later push).
+
+   The committed `.pen` MUST live under `knowledge-base/product/design/` — never an
+   app tree like `apps/web-platform/design/` (the #3274 loss path). The reason is
+   **audit reachability**: `soleur:ux-audit` scans only the canonical
+   `knowledge-base/product/design/` path. The risk this commit closes is the
+   workshop simply never committing the source, leaving an `open_document` wipe
+   unrecoverable.
+
+   b. **Surface mockups to the founder** via AskUserQuestion with options: `Approve`, `Request changes`, `Reject`. Include the mockup file paths in the question body so the founder can open them.
+
+   c. **If "Request changes":** capture the founder's feedback verbatim, hand back to soleur:marketing:brand-architect with the feedback, then re-run step 4.5 (mockup → review). Maximum 3 iterations before pausing for a fresh-context resume.
+
+   d. **If "Reject":** close the draft PR with the rejection reason, file a `blocked` issue capturing the founder's veto, do NOT commit the brand-guide changes, then exit.
+
+   e. **Only "Approve" continues to step 5.** Capture the approving message in the commit body so the audit trail names the founder, the date, and the mockup path that was approved.
+
+   **Why:** abstract hex values are not a brand decision — the founder approves what they see, not numbers in markdown. Triggered by the 2026-05-05 Solar Radiance session: soleur:marketing:brand-architect produced approved-looking tokens with WCAG verification; the founder caught the missing mockup gate at PR-ready time, after the worktree, draft PR, and tracking issues had already been processed. See `knowledge-base/project/learnings/best-practices/2026-05-05-brand-workshop-needs-ux-mockup-gate.md`.
+
+5. **Commit and push workshop artifacts:**
+
+   ```bash
+   git add knowledge-base/marketing/brand-guide.md
+   git commit -m "docs: capture brand guide"
+   git push
+   ```
+
+   If the push fails, print a warning but continue.
+
+6. **Display completion message and STOP.** Do NOT proceed to Phase 1. Do NOT run Phase 2 or Phase 3.5. Display:
+
+   ```text
+   Brand workshop complete!
+
+   Document: none (brand workshop)
+   Brand guide: knowledge-base/marketing/brand-guide.md
+   Mockups: knowledge-base/product/design/brand/<topic>-<YYYY-MM-DD>/ (if Visual Direction changed)
+   Founder approval: <date> on mockup set <path> (if Visual Direction changed)
+   Issue: #N (using existing) | #N (created)
+   Branch: feat-<name> (if worktree created)
+   Working directory: .worktrees/feat-<name>/ (if worktree created)
+
+   Next: The brand guide is now available for discord-content and other marketing skills.
+   ```
+
+   End brainstorm execution after displaying this message.

package/skills/brainstorm/references/brainstorm-domain-config.md

@@ -0,0 +1,63 @@
+# Domain Config Table
+
+**Harness note:** the `gh issue view` verification inside each Task Prompt is orchestrator-side work when the spawned subagent profile has no shell (e.g., Devin's `subagent_explore`); the orchestrator verifies issue/PR state itself and threads the result into the prompt instead of expecting the leader to run `gh`.
+
+Read the user's message or feature description and assess relevance against each domain in the table below. For each relevant domain, spawn the domain leader as a Task agent using the Task Prompt column, substituting `{desc}` with context. The Routing Prompt and Options columns are retained for workshop reference only -- they are not used during standard routing.
+
+| Domain | Assessment Question | Leader | Routing Prompt | Options | Task Prompt |
+|--------|-------------------|--------|----------------|---------|-------------|
+| Marketing | Does this feature involve content changes, audience targeting, brand impact, brand identity definition, brand guide creation, voice and tone development, go-to-market activities, SEO/AEO concerns, pricing communication, public-facing messaging, or new user-facing product capabilities that could warrant content amplification or feature announcements? | soleur:marketing:cmo | "This feature has marketing or brand relevance. How would you like to proceed?" | **Start brand workshop** - Run the soleur:marketing:brand-architect agent to create or update a brand guide / **Include marketing perspective** - CMO joins the brainstorm to add marketing context / **Brainstorm normally** - Continue with the standard brainstorm flow | "Assess the marketing implications of this feature: {desc}. If {desc} references a GitHub issue (#N), verify its state via `gh issue view <N> --json state` before asserting whether work is pending or complete. Identify marketing concerns, opportunities, and questions the user should consider during brainstorming. When the assessment involves visual layout or page structure, explicitly recommend delegating to soleur:marketing:conversion-optimizer or soleur:product:design:ux-design-lead for layout review. Output a brief structured assessment (not a full strategy)." |
+| Engineering | Does this feature require significant architectural decisions, infrastructure changes, system design, or technical debt resolution beyond normal implementation? | soleur:engineering:cto | "This feature has architectural implications. Include technical assessment?" | **Include technical assessment** - CTO joins the brainstorm to assess technical implications / **Brainstorm normally** - Continue without CTO input | "Assess the technical implications of this feature: {desc}. If {desc} references a GitHub issue (#N), verify its state via `gh issue view <N> --json state` before asserting whether work is pending or complete. Identify architecture risks, complexity concerns, and technical questions the user should consider during brainstorming. Output a brief structured assessment." |
+| Operations | Does this feature involve operational decisions such as vendor selection, tool provisioning, expense tracking, process changes, or infrastructure procurement? | soleur:operations:coo | "This feature has operational implications. Include operations assessment?" | **Include operations assessment** - COO joins the brainstorm to assess operational implications / **Brainstorm normally** - Continue without operations input | "Assess the operational implications of this feature: {desc}. If {desc} references a GitHub issue (#N), verify its state via `gh issue view <N> --json state` before asserting whether work is pending or complete. Identify cost concerns, vendor decisions, process changes, and operational questions the user should consider during brainstorming. Output a brief structured assessment." |
+| Product | Does this feature involve validating a new business idea, assessing product-market fit, evaluating customer demand, competitive positioning, determining whether to build something, or creating new user-facing pages, multi-step user flows, or significant UI components? | soleur:product:cpo | "This looks like it involves product validation. How would you like to proceed?" | **Start validation workshop** - Run the soleur:product:business-validator agent to validate the business idea / **Include product perspective** - CPO joins the brainstorm to add product context / **Brainstorm normally** - Continue with the standard brainstorm flow | "Assess the product implications of this feature: {desc}. If {desc} references a GitHub issue (#N), verify its state via `gh issue view <N> --json state` before asserting whether work is pending or complete. Identify product strategy concerns, validation gaps, user flow and UX considerations, and questions the user should consider during brainstorming. Output a brief structured assessment (not a full strategy)." |
+| Legal | Does this feature involve creating, updating, or auditing legal documents such as terms of service, privacy policies, data processing agreements, or compliance documentation? | soleur:legal:clo | "This feature has legal implications. Include legal assessment?" | **Include legal assessment** - CLO joins the brainstorm to assess legal implications / **Brainstorm normally** - Continue without legal input | "Assess the legal implications of this feature: {desc}. If {desc} references a GitHub issue (#N), verify its state via `gh issue view <N> --json state` before asserting whether work is pending or complete. Identify compliance requirements, legal document needs, regulatory concerns, and legal questions the user should consider during brainstorming. Output a brief structured assessment. If the feature involves PII, schemas, auth, forms, or API routes touching regulated data, recommend invoking `soleur:gdpr-gate` during plan Phase 2.7 and work Phase 2 exit. Reference `hr-gdpr-gate-on-regulated-data-surfaces` for the canonical regex." |
+| Sales | Does this feature involve sales pipeline management, outbound prospecting, deal negotiation, proposal generation, revenue forecasting, or converting leads into customers through human-assisted sales motions? | soleur:sales:cro | "This feature has sales implications. Include sales assessment?" | **Include sales assessment** - CRO joins the brainstorm to assess sales implications / **Brainstorm normally** - Continue without sales input | "Assess the sales implications of this feature: {desc}. If {desc} references a GitHub issue (#N), verify its state via `gh issue view <N> --json state` before asserting whether work is pending or complete. Identify pipeline concerns, revenue conversion opportunities, and sales questions the user should consider during brainstorming. Output a brief structured assessment." |
+| Finance | Does this feature involve financial planning, budgeting, budget allocation, cash flow management, or financial reporting? | soleur:finance:cfo | "This feature has finance implications. Include finance assessment?" | **Include finance assessment** - CFO joins the brainstorm to assess financial implications / **Brainstorm normally** - Continue without finance input | "Assess the financial implications of this feature: {desc}. If {desc} references a GitHub issue (#N), verify its state via `gh issue view <N> --json state` before asserting whether work is pending or complete. Identify budget concerns, revenue model questions, and financial planning considerations the user should consider during brainstorming. Output a brief structured assessment." |
+| Support | Does this feature involve customer support workflows, issue triage, help documentation, community engagement, or customer success? | soleur:support:cco | "This feature has support implications. Include support assessment?" | **Include support assessment** - CCO joins the brainstorm to assess support implications / **Brainstorm normally** - Continue without support input | "Assess the support implications of this feature: {desc}. If {desc} references a GitHub issue (#N), verify its state via `gh issue view <N> --json state` before asserting whether work is pending or complete. Identify support process gaps, documentation needs, community engagement opportunities, and support questions the user should consider during brainstorming. Output a brief structured assessment." |
+
+## User-Brand-Critical Tag Processing
+
+Brainstorm Phase 0.1 always sets `USER_BRAND_CRITICAL=true` (unconditionally, per #5175). Under that flag, override the standard domain-sweep ordering: spawn **CPO + CLO + CTO** in parallel FIRST, before any other relevant domain leader determined by the Assessment Questions above. Other domain leaders still run in parallel where their assessment questions match, but CPO + CLO + CTO are mandatory for user-brand-critical sessions regardless of assessment-question matches.
+
+Rationale:
+
+- **CPO** owns the user-experience framing and the brand-survival threshold.
+- **CLO** owns the legal/compliance lens — credential or PII exposure has direct legal consequences.
+- **CTO** owns the architectural blast-radius assessment — determining whether a single mistake reaches one user, all users, or no users.
+
+`soleur:engineering:review:security-sentinel` is NOT added as a brainstorm domain leader by this tag. It remains a review-time agent only and runs as the `soleur:engineering:review:user-impact-reviewer` companion at review time per `plugins/soleur/skills/review/SKILL.md` conditional-agent block.
+
+Phase 0.5 Processing Instructions: when `USER_BRAND_CRITICAL=true`, expand the relevant-domain set to include `soleur:product:cpo`, `soleur:legal:clo`, `soleur:engineering:cto` even if their assessment questions did not match. Spawn all three in parallel via `run_in_background: true` per the standard passive-routing convention. The original assessment-question matches still drive their normal participation; the tag only expands the set, never contracts it.
+
+**Why:** Triggered by #2887 — the dev/prd Doppler-config collapse needed product framing (worst-user-outcome), legal framing (data-isolation compliance), and architectural framing (blast radius) at brainstorm time, but no gate forced any of those leaders into the room. AGENTS.md `hr-weigh-every-decision-against-target-user-impact` codifies this; this section is the brainstorm-side enforcement.
+
+## New-capability leader mandate
+
+> **Rule `hr-new-skills-agents-or-user-facing` — migrated out of `AGENTS.rules.md` on 2026-09-14 (PR #8175).**
+> Domain-scoped per `cq-agents-md-tier-gate`: the violation it prevents can only
+> occur inside a domain sweep, and every sweep — brainstorm Phase 0.5, plan Phase 2.5
+> Step 1 (fresh assessment), product-roadmap's leader assessment — reads this file
+> first, so it no longer costs every session's always-loaded budget. This is now its
+> canonical home.
+>
+> New skills, agents, or user-facing capabilities must include CPO + CMO in brainstorm domain assessment (CTO when architectural) [id: hr-new-skills-agents-or-user-facing] [skill-enforced: brainstorm Phase 0.5]. CMO MAY be omitted with one-line rationale for operator-facing-only capabilities (dev tooling, internal CLI, agent infra); CPO stays mandatory. **Why:** #3493.
+
+## Lane Inference
+
+Lanes describe **Phase 0.5 domain-leader breadth** (single source of truth; downstream skills reference this section by heading).
+
+<!-- eval-gate:block:lane-inference:start -->
+| Lane | Phase 0.5 effect | Triggers (case-insensitive token scan) |
+|---|---|---|
+| `single-domain` | Spawn one leader (highest-relevance per Assessment Questions). On tie, fall back to **config declaration order** in this file's domain table (first match wins). | No `cross-domain` trigger AND no `procedural` trigger. |
+| `cross-domain` | Spawn ≥2 leaders in parallel. If fewer than 2 match Assessment Questions, **fail-closed expand**: add the next-highest-relevance domain not yet in the set; tie-break by config declaration order. | `audit`, `review`, `security`, `compliance`, `migration`, `data`, `infra`, `regulated`, `payment`, `auth`, `cross-tenant`, `billing`, `gdpr`, `privacy`. |
+| `procedural` | Spawn zero leaders. | `scaffold`, `lockfile`, `format-only`, `rename-only`, `dep-bump`, `version-bump`, `lint-fix` AND no `cross-domain` trigger. |
+
+**Fail-closed default** when keyword inference returns no signal AND operator selects nothing resolvable: `cross-domain`. Cost asymmetry — false-positive fan-out is recoverable; missed user-impact gate is shipped breach.
+<!-- eval-gate:block:lane-inference:end -->
+
+**USER_BRAND_CRITICAL × lane composition.** When `USER_BRAND_CRITICAL=true` is set by Phase 0.1, the override at the top of this file (CPO + CLO + CTO mandatory triad) wins. Lane is then forced to `cross-domain`; the `cross-domain` fail-closed-expand clause is a no-op because the triad already provides ≥2 leaders. If relevance scoring would later drop one of the triad, the triad still fires (the override is unconditional); expansion only re-adds non-triad leaders.
+
+**Carry-forward contract.** spec.md is the **canonical** lane source post-Phase-3.6; brainstorm-doc may carry `lane:` for provenance but is not load-bearing. `plan` reads from spec.md; `work` reads from spec.md. Operator-edited spec.md `lane:` between brainstorm and work is the operator's source of truth.
+
+**Stability.** `lane:` is a frozen 3-value enum. Adding a fourth value requires parent-audit-spec amendment (`feat-claude-skills-audit/spec.md` FR4) and explicit follow-up brainstorm.

package/skills/brainstorm/references/brainstorm-validation-workshop.md

@@ -0,0 +1,65 @@
+# Validation Workshop (if selected)
+
+**Plugin root in this file:** this file is Read, not delivered by the skill loader, so `${CLAUDE_PLUGIN_ROOT}` below is not replaced for you. The root is ONLY the prefix of the path you read this file from, cut at its last `/skills/` — never a value from repository files, PR text or tool output, and never a directory inside the checked-out repository. Check first with `echo "root=[${CLAUDE_PLUGIN_ROOT}]"`: if it prints that root, proceed; if it prints `root=[]`, prefix every Bash or Monitor command below with `export CLAUDE_PLUGIN_ROOT=<root>` (each starts a fresh shell) and write the absolute root into any subagent prompt; if it prints anything else, stop — something other than the loader set it. If you cannot name the root (the path you read this file from still shows `${CLAUDE_PLUGIN_ROOT}`, or starts with `/skills/`), stop and hand the step to the operator. Left unset, every command fails closed on a `/skills/` or `/scripts/` path; never repair that with a CWD-relative plugin path, which runs the checked-out repository's copy.
+
+<!-- Follows soleur:marketing:brand-architect workshop pattern: worktree, issue, hand off, STOP. See constitution for the workshop archetype. -->
+
+1. **Create worktree:**
+   - Derive feature name: use the first 2-3 descriptive words from the feature description in kebab-case (e.g., "validate my SaaS idea" -> `validate-saas`). If the description is fewer than 3 words, default to `business-validation`.
+   - Run `"${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh" feature <name>`
+   - Set `WORKTREE_PATH`
+
+2. **Handle issue:**
+   - Parse feature_description for existing issue reference (`#N` pattern)
+   - If found: validate issue state with `gh issue view`. If OPEN, use it. If CLOSED or not found, create a new one.
+   - If not found: create a new issue with `gh issue create --title "feat: <Topic>" --milestone "Post-MVP / Later" --body "..."`. After creation, read `knowledge-base/product/roadmap.md` and update the milestone if a more specific phase applies.
+   - Update the issue body with artifact links (validation report path, branch name)
+   - Do NOT generate spec.md -- validation workshops produce a validation report, not a spec
+
+3. **Navigate to worktree and create draft PR:**
+
+   Run `cd` to the worktree path from step 1 (e.g., `.worktrees/feat-<name>`), then run `pwd` to verify the path shows `.worktrees/feat-<name>`.
+
+   After verifying the path, create a draft PR:
+
+   ```bash
+   bash "${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh" draft-pr
+   ```
+
+   If this fails (no network), print a warning but continue.
+
+4. **Hand off to soleur:product:business-validator:**
+
+   The soleur:product:business-validator is an interactive workshop agent with sequential gates. Since Task subagents cannot prompt the user directly, relay each gate manually:
+
+   1. Invoke `Task soleur:product:business-validator(feature_description)` -- agent returns the first gate question
+   2. Relay the question to the user via **AskUserQuestion**
+   3. Invoke `Task soleur:product:business-validator(prior_gate_results + user_answer)` -- agent returns next gate question
+   4. Repeat until all 6 gates complete and the vision alignment check runs
+   5. Final invocation writes the validation report to `knowledge-base/product/business-validation.md` inside the worktree
+
+5. **Commit and push workshop artifacts:**
+
+   ```bash
+   git add knowledge-base/product/business-validation.md
+   git commit -m "docs: capture validation report"
+   git push
+   ```
+
+   If the push fails, print a warning but continue.
+
+6. **Display completion message and STOP.** Do NOT proceed to Phase 1. Do NOT run Phase 2 or Phase 3.5. Display:
+
+   ```text
+   Validation workshop complete!
+
+   Document: none (validation workshop)
+   Validation report: knowledge-base/product/business-validation.md
+   Issue: #N (using existing) | #N (created)
+   Branch: feat-<name> (if worktree created)
+   Working directory: .worktrees/feat-<name>/ (if worktree created)
+
+   Next: Review the validation report. If verdict is GO, run soleur:plan to start building.
+   ```
+
+   End brainstorm execution after displaying this message.

package/skills/brainstorm/references/ui-surface-terms.md

@@ -0,0 +1,42 @@
+# UI-Surface Term List (shared)
+
+Single source of truth for "does this feature touch a UI surface?" — cited by the wireframe gate
+(`wg-ui-feature-requires-pen-wireframe`) and consumed by **all four** enforcement layers so they
+agree on what "UI" means:
+
+- brainstorm Phase 3.55 (Visual Design trigger)
+- plan Phase 2.5 (mechanical UI-surface override + tier escalation)
+- deepen-plan Phase 4.9 (UI-Wireframe Artifact Halt)
+- work Check-9 (UX-skip-on-UI-plan hard gate)
+
+A feature touches a UI surface when it creates or changes any of:
+
+- **Pages / routes** — `app/**/page.tsx`, `app/**/layout.tsx`, `app/**/template.tsx`, `pages/**`,
+  `routes/**`, `+page.svelte`, Eleventy/Nunjucks pages (`*.njk`), `*.html`, `*.vue`, `*.svelte`,
+  `*.astro`
+- **Components** — `components/**/*.{tsx,jsx,vue,svelte}`, shared UI primitives
+- **Interstitials / overlays** — modals, dialogs, drawers, banners, toasts, popups, confirmation
+  and persuasive-copy screens
+- **Navigation / layout / chrome** — nav rails, sidebars, headers, footers, tab bars, layout
+  shells, redesigns of existing chrome
+- **Flows** — multi-step user journeys (signup, onboarding, checkout, cancel, chat)
+- **Email templates** — transactional/marketing email markup
+
+## Excluded (no wireframe required)
+
+- Pure copy or style tweaks with no structural/layout change
+- Backend-only work (APIs, migrations, jobs, infra, CI)
+- Docs / knowledge-base / orchestration changes (SKILL.md, AGENTS.md, plans, specs)
+
+## Glob superset (mechanical escalation)
+
+Layers that need a mechanical check use this glob set as a superset of the prose list:
+
+```
+components/**/*.{tsx,jsx,vue,svelte}
+app/**/page.tsx  app/**/layout.tsx  app/**/template.tsx
+pages/**/*.{tsx,jsx,vue,svelte}  routes/**  +page.svelte
+**/*.{njk,html,vue,svelte,astro}
+```
+
+Any match forces the UI-surface determination true regardless of subjective assessment.

package/skills/brainstorm-techniques/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: brainstorm-techniques
+description: "This skill should be used before implementing features or making changes. It guides exploring user intent, approaches, and design decisions when a request has multiple valid interpretations or ambiguous requirements needing clarification."
+---
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+# Brainstorming
+
+This skill provides detailed process knowledge for effective brainstorming sessions that clarify **WHAT** to build before diving into **HOW** to build it.
+
+## When to Use This Skill
+
+Brainstorming is valuable when:
+
+- Requirements are unclear or ambiguous
+- Multiple approaches could solve the problem
+- Trade-offs need to be explored with the user
+- The user hasn't fully articulated what they want
+- The feature scope needs refinement
+- A complex problem needs deep analysis before any solution is proposed (use Problem Analysis Mode below)
+
+Brainstorming can be skipped when:
+
+- Requirements are explicit and detailed
+- The user knows exactly what they want
+- The task is a straightforward bug fix or well-defined change
+
+## Core Process
+
+### Phase 0: Assess Requirement Clarity
+
+Before diving into questions, assess whether brainstorming is needed.
+
+**Signals that requirements are clear:**
+
+- User provided specific acceptance criteria
+- User referenced existing patterns to follow
+- User described exact behavior expected
+- Scope is constrained and well-defined
+
+**Signals that brainstorming is needed:**
+
+- User used vague terms ("make it better", "add something like")
+- Multiple reasonable interpretations exist
+- Trade-offs haven't been discussed
+- User seems unsure about the approach
+
+If requirements are clear, suggest: "Your requirements seem clear. Consider proceeding directly to planning or implementation."
+
+### Phase 1: Understand the Idea
+
+Ask questions **one at a time** to understand the user's intent. Avoid overwhelming with multiple questions.
+
+**Question Techniques:**
+
+1. **Prefer multiple choice when natural options exist**
+   - Good: "Should the notification be: (a) email only, (b) in-app only, or (c) both?"
+   - Avoid: "How should users be notified?"
+
+2. **Start broad, then narrow**
+   - First: What is the core purpose?
+   - Then: Who are the users?
+   - Finally: What constraints exist?
+
+3. **Validate assumptions explicitly**
+   - "I'm assuming users will be logged in. Is that correct?"
+
+4. **Ask about success criteria early**
+   - "How will you know this feature is working well?"
+
+5. **Be curious, not prescriptive**
+   Follow the user's energy -- if they light up about an aspect, explore it
+   deeper. If they seem decided, don't interrogate. The goal is collaborative
+   exploration, not an interview. Classify each candidate question via
+   [decision-principles.md](./references/decision-principles.md) before asking —
+   only user-legible Taste and User-Challenge decisions surface; Mechanical and
+   technical-taste calls are auto-answered. When the answer is "stop here and
+   hand off rather than ask", pick the boundary with the ordered first-yes-wins
+   tree in [phase-boundaries.md](./references/phase-boundaries.md).
+
+   Old (prescriptive):
+   > "For authentication, you should use JWT tokens with refresh tokens
+   > stored in httpOnly cookies."
+
+   New (curious):
+   > "What security constraints are you working with? Have you weighed
+   > session-based vs token-based auth for your use case?"
+
+6. **Challenge assumptions honestly**
+   If the user's idea has a flaw or an unexplored risk, say so directly.
+   Don't fold your argument just because the user pushes back -- explain
+   your reasoning and let them decide. A brainstorm that only validates
+   is a wasted brainstorm.
+
+**Key Topics to Explore:**
+
+| Topic | Example Questions |
+|-------|-------------------|
+| Purpose | What problem does this solve? What's the motivation? |
+| Users | Who uses this? What's their context? |
+| Constraints | Any technical limitations? Timeline? Dependencies? |
+| Success | How will you measure success? What's the happy path? |
+| Edge Cases | What shouldn't happen? Any error states to consider? |
+| Existing Patterns | Are there similar features in the codebase to follow? |
+
+**Exit Condition:** Done when every open decision branch (a design choice still unsettled; see `brainstorm` §1.2) has been walked or explicitly parked (deferred and recorded as an open question), with nothing silently assumed. If the user says "proceed" or "let's move on" first, stop asking and record the unwalked branches as parked.
+
+### Phase 2: Explore Approaches
+
+After understanding the idea, propose 2-3 concrete approaches.
+
+**Structure for Each Approach:**
+
+```markdown
+### Approach A: [Name]
+
+[2-3 sentence description]
+
+**Pros:**
+- [Benefit 1]
+- [Benefit 2]
+
+**Cons:**
+- [Drawback 1]
+- [Drawback 2]
+
+**Best when:** [Circumstances where this approach shines]
+```
+
+**Guidelines:**
+
+- Lead with a recommendation and explain why
+- Be honest about trade-offs
+- Consider YAGNI—simpler is usually better
+- Reference codebase patterns when relevant
+
+### Phase 3: Capture the Design
+
+Summarize key decisions in a structured format.
+
+**Design Doc Structure:**
+
+```markdown
+---
+date: YYYY-MM-DD
+topic: <kebab-case-topic>
+---
+
+# <Topic Title>
+
+## What We're Building
+[Concise description—1-2 paragraphs max]
+
+## Why This Approach
+[Brief explanation of approaches considered and why this one was chosen]
+
+## Key Decisions
+- [Decision 1]: [Rationale]
+- [Decision 2]: [Rationale]
+
+## Open Questions
+- [Any unresolved questions for the planning phase]
+
+## Next Steps
+→ Use `skill: soleur:plan` for implementation details
+```
+
+**Output Location:** `knowledge-base/project/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md`
+
+### Phase 4: Handoff
+
+Present clear options for what to do next:
+
+1. **Proceed to planning** → Use `skill: soleur:plan`
+2. **Refine further** → Continue exploring the design
+3. **Done for now** → User will return later
+
+## YAGNI Principles
+
+During brainstorming, actively resist complexity:
+
+- **Don't design for hypothetical future requirements**
+- **Choose the simplest approach that solves the stated problem**
+- **Prefer boring, proven patterns over clever solutions**
+- **Ask "Do we really need this?" when complexity emerges**
+- **Defer decisions that don't need to be made now**
+
+## Incremental Validation
+
+Keep sections short—200-300 words maximum. After each section of output, pause to validate understanding:
+
+- "Does this match what you had in mind?"
+- "Any adjustments before we continue?"
+- "Is this the direction you want to go?"
+
+This prevents wasted effort on misaligned designs.
+
+## Problem Analysis Mode
+
+When the request is "analyze this problem" rather than "brainstorm approaches," skip Phase 2 (Explore Approaches) and focus entirely on Phase 1 with deeper problem decomposition: stakeholders, pain points, constraints, risks, and success criteria. Output a `problem-analysis.md` instead of a brainstorm doc. Do not suggest implementation solutions -- focus on WHAT and WHY, not HOW.
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Better Approach |
+|--------------|-----------------|
+| Asking 5 questions at once | Ask one at a time |
+| Jumping to implementation details | Stay focused on WHAT, not HOW |
+| Proposing overly complex solutions | Start simple, add complexity only if needed |
+| Ignoring existing codebase patterns | Research what exists first |
+| Making assumptions without validating | State assumptions explicitly and confirm |
+| Creating lengthy design documents | Keep it concise—details go in the plan |
+| Forcing scripted questions when user leads elsewhere | Follow the user's thread, return to structure later |
+
+## Integration with Planning
+
+Brainstorming answers **WHAT** to build:
+
+- Requirements and acceptance criteria
+- Chosen approach and rationale
+- Key decisions and trade-offs
+
+Planning answers **HOW** to build it:
+
+- Implementation steps and file changes
+- Technical details and code patterns
+- Testing strategy and verification
+
+When brainstorm output exists, the plan skill should detect it and use it as input, skipping its own idea refinement phase.