@su-record/vibe 2.9.25 → 2.9.32

package/skills/vibe-spec/SKILL.md

@@ -1,1195 +1,1195 @@
----
-name: vibe-spec
-tier: core
-description: "Create an AI-executable PTCF-structured SPEC document through conversational requirements gathering, parallel research (GPT/Gemini/Claude agents), PTCF writing, ambiguity scan, and 100-point quality gate (loops until perfect or stuck). Produces .claude/vibe/specs/{feature}.md + matching .claude/vibe/features/{feature}.feature (BDD). Must use this skill when the user says 'write spec', 'create spec', '/vibe.spec', or when a plan document exists and is ready for code specification."
-triggers: [spec, SPEC, 명세, "코드 명세", "구현 명세", "write spec", "create spec", PTCF]
-priority: 85
-chain-next: [vibe-spec-review]
----
-
-# vibe.spec — Specification Agent
-
-Create a SPEC document (Specification Agent).
-
-## Usage
-
-```
-/vibe.spec "feature-name"                    # Conversation mode (requirements gathering)
-/vibe.spec "feature-name" ultrawork          # Auto: SPEC → Review → Implementation
-/vibe.spec "docs/login-prd.md"               # File path input (auto-detected)
-/vibe.spec + 📎 file attachment              # Use attached file
-```
-
-### ultrawork Mode
-
-When `ultrawork` (or `ulw`) is included, automatically chains:
-
-```
-/vibe.spec "feature" ultrawork
-    ↓
-[1] SPEC Creation (this command)
-    ↓
-[2] Auto: Load skill `vibe-spec-review` (chain-next from this skill)
-    ↓
-[3] Auto: /vibe.run "{feature}" ultrawork
-```
-
-**No manual intervention between steps.**
-
-> **⏱️ Timer**: Call `getCurrentTime` tool at the START. Record the result as `{start_time}`.
-
-## Input Mode Detection (Auto-detect)
-
-**Input priority:**
-
-```
-1. Attachment exists? → Use attached file
-2. Argument is file path? (existence check) → Read file
-3. Otherwise → Conversation mode (start with feature name)
-```
-
-| Input | Result |
-|-------|--------|
-| 📎 Attached file | → Analyze attached file |
-| File path (exists) | → Read file (Read tool) |
-| Feature name | → Start conversation mode |
-
-**All supported files:**
-- Text: `.md`, `.txt`, `.rst`, `.html`, `.json`, `.yaml`, etc.
-- Documents: `.pdf` (page-by-page analysis)
-- Images: `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.svg`, etc.
-- Notebooks: `.ipynb` (Jupyter)
-- **All formats Claude can read**
-
-**File input mode flow:**
-
-```
-/vibe.spec "docs/login-prd.md"
-
-📄 File loaded: docs/login-prd.md (2.3KB)
-
-📋 Parsed requirements:
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Feature: Login
-  - Email/password login
-  - Social login (Google, Apple)
-  - Password recovery
-  - Auto login persistence
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-❓ Additional confirmation needed:
-  1. Session expiration time? (default: 24 hours)
-  2. Allow concurrent login?
-  3. Confirm tech stack? (current: React + Supabase)
-
-User: 1 hour, disallow, confirm
-
-✅ Requirements confirmed → Run research → Generate SPEC → Review
-```
-
-**Supported file formats:**
-
-| Format | Extension | Purpose |
-|--------|-----------|---------|
-| Markdown | `.md` | PRD, planning docs, README |
-| Text | `.txt` | Requirements list |
-| PDF | `.pdf` | Planning docs, design documents |
-| Image | `.png`, `.jpg`, `.jpeg`, `.webp` | Wireframes, UI design, screenshots |
-
-**Image input analysis:**
-
-When image files (`.png`, `.jpg`, `.jpeg`, `.webp`) are provided as input, analyze them using the best available method:
-
-- **Gemini Enabled**: `llm-orchestrate.js gemini analyze-image` (Gemini Flash - best image recognition)
-- **Gemini Disabled**: Claude Opus Read tool (built-in multimodal, existing behavior)
-
-**Gemini enabled - analyze via llm-orchestrate.js:**
-
-```bash
-# [LLM_SCRIPT] = {{VIBE_PATH}}/hooks/scripts/llm-orchestrate.js
-node "[LLM_SCRIPT]" gemini analyze-image "./designs/login-wireframe.png" "Analyze this UI design image. Identify all UI elements, layout structure, colors, typography, and component hierarchy. Output a structured breakdown."
-```
-
-Parse the JSON result: `{ success: true, analysis: "..." }` → use `analysis` field content.
-
-If `success: false`, fall back to Claude Read tool.
-
-**Gemini disabled - analyze via Claude Read tool:**
-
-Use the Read tool directly on the image file. Claude can read images natively.
-
-**Image input example:**
-```
-/vibe.spec "designs/login-wireframe.png"
-
-🖼️ Image analysis: designs/login-wireframe.png
-   (via Gemini Flash / Claude Opus)
-
-📋 Detected UI elements:
-  - Email input field
-  - Password input field
-  - "Login" button
-  - "Forgot password" link
-  - Social login buttons (Google, Apple)
-
-❓ Confirmation needed:
-  1. Feature name? (e.g., "login")
-  2. Additional requirements?
-
-→ Generate SPEC
-```
-
-## Rules Reference
-
-**Must follow `~/.claude/vibe/rules/` (global):**
-- `core/development-philosophy.md` - Surgical precision, simplicity
-- `core/quick-start.md` - Korean first, DRY, SRP
-- `core/communication-guide.md` - Communication principles
-
-## Description
-
-Collect requirements through conversation with the user and create an **AI-executable PTCF structured SPEC document**.
-
-> **PTCF**: Persona, Task, Context, Format - Google Gemini prompt optimization framework
-
-## External LLM Integration (GPT/Gemini)
-
-When GPT/Gemini are enabled, they are automatically utilized during SPEC creation:
-
-```
-/vibe.spec "feature"
-      ↓
-[Claude] Draft SPEC
-      ↓
-[Parallel Research] GPT + Gemini + Claude agents (8 parallel)
-      ↓
-[SPEC Review] GPT + Gemini parallel review
-      ↓
-[Claude] Finalize SPEC
-```
-
-**Setup:**
-```bash
-vibe gpt key <key>      # Enable GPT
-vibe gemini key <key>   # Enable Gemini
-vibe status         # Check current settings
-```
-
-## Process
-
-### 0. Git Branch Setup (MANDATORY - Execute First!)
-
-> ⚠️ **CRITICAL: You MUST execute this step FIRST before anything else!**
-> This is NOT optional documentation - you must RUN these git commands.
-
-**Step 0 is BLOCKING - do not proceed to Step 1 until branch is ready.**
-
-**Execute these commands using Bash tool:**
-
-```bash
-# 1. Check current branch
-git branch --show-current
-```
-
-**Then based on result:**
-
-| Current Branch | Action |
-|----------------|--------|
-| `main` or `master` | **MUST** create feature branch: `git checkout -b feature/{feature-name}` |
-| `feature/*` | Ask user: "Continue on this branch or create new?" |
-| Other | Ask user to confirm |
-
-**Example execution:**
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🌿 GIT BRANCH SETUP
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Current branch: main
-
-Creating feature branch...
-$ git checkout -b feature/login-page
-
-✅ Switched to new branch: feature/login-page
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-**Branch naming rules:**
-- Convert to lowercase: `Login Page` → `login-page`
-- Replace spaces with hyphens
-- Prefix with `feature/`
-- Example: `feature/passkey-auth`, `feature/dark-mode`
-
-**`.last-feature` pointer update** (immediately after Git branch setup):
-
-```
-Write ".claude/vibe/.last-feature" ← feature-name (single line)
-Execute at the point when the feature name is finalized.
-No-op if the value is already the same.
-```
-
-### 1. Project Analysis
-
-**Existing project** (`vibe init`):
-- Reference `CLAUDE.md` file (tech stack)
-- **Delegate codebase analysis to explorer agent** — do NOT read project files in main session:
-
-```text
-Task(subagent_type="explorer-low",
-  prompt="Analyze project structure: package.json, pyproject.toml, pubspec.yaml, go.mod.
-  Find existing implementations related to [FEATURE]. Return: tech stack, relevant files, patterns used.
-  Keep summary under 200 tokens.")
-```
-
-**New project** (`vibe init <project-name>`):
-- Suggest tech stack (2-3 options)
-
-### 2. Collect Requirements via Conversation
-
-**Principles:**
-- Ask **one question at a time**
-- Present options **with numbers** + "Feel free to describe in your own words"
-- **Natural conversation** without fixed order
-
-**Required confirmations:**
-- Purpose (Why): Why is it needed?
-- User (Who): Who will use it?
-- Feature scope (What): What features are needed?
-- Tech stack: Confirm existing stack or suggest new
-- Design reference: UI/UX to reference
-
-### 2.1 Critical Requirements Confirmation (askUser) - v2.6.1
-
-**🚨 IMPORTANT: Use `askUser` tool for CRITICAL requirements that must not be missed**
-
-After initial conversation, use the structured `askUser` tool for:
-- 🔐 Authentication: method, MFA, password policy
-- 🛡️ Security: rate limiting, session management
-- ⏱️ Session: duration, concurrent login policy
-- 📊 Data Model: required fields, relationships
-
-**When to use askUser vs conversation:**
-
-| Scenario | Method |
-|----------|--------|
-| Exploratory (feature scope, style) | Natural conversation |
-| **Critical** (auth, security, session) | `askUser` tool |
-| Optional (performance, integration) | Natural conversation |
-
-**Usage:**
-
-```typescript
-import { askUser, askUserQuick } from '@su-record/vibe/tools';
-
-// Quick helper for common scenarios
-const result = await askUserQuick.login('my-login-feature');
-console.log(result.content[0].text);
-
-// Custom categories
-const result = await askUser({
-  featureName: 'user-dashboard',
-  categories: ['authentication', 'security', 'session', 'data_model'],
-  context: 'Building a user dashboard with role-based access',
-});
-```
-
-**Available categories:**
-- `authentication`: Auth methods, MFA
-- `security`: Password policy, rate limiting
-- `session`: Session expiry, concurrent login
-- `data_model`: User profile fields
-- `performance`: Response time targets
-- `integration`: External service integration
-
-**Example output:**
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-📋 Requirements Confirmation
-Feature: login
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-## 🔐 Authentication
-
-### 🔐 Q-AUTHENTICATION-001
-
-**Which authentication methods should be supported?**
-(Multiple selection allowed)
-
-1. **Email/Password** ✓
-2. **Google Social Login**
-3. **Apple Social Login**
-...
-
-**Required**
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Total 6 questions (Required: 4)
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-**Response parsing:**
-
-```typescript
-import { parseUserResponse } from '@su-record/vibe/tools';
-
-// User responds: "1, 2, 4" (selected option numbers)
-const response = parseUserResponse(question, "1, 2, 4");
-// { questionId: "Q-AUTH-001", value: ["email_password", "social_google", "passkey"], timestamp: "..." }
-```
-
-**ultrawork mode:**
-- askUser is **skipped** in ultrawork mode
-- Uses default values from templates automatically
-
-### 2.5. Reference Documents via config.json (MANDATORY after tech stack confirmed)
-
-**🚨 CRITICAL: Read config.json references IMMEDIATELY after tech stack is confirmed**
-
-Reference documents are automatically generated in `config.json` based on the stack detected during `vibe init`:
-
-```json
-// .claude/vibe/config.json
-{
-  "language": "ko",
-  "stacks": [
-    { "type": "typescript-react", "path": "package.json" }
-  ],
-  "references": {
-    "rules": [
-      "~/.claude/vibe/rules/code-quality.md",
-      "~/.claude/vibe/rules/error-handling.md",
-      "~/.claude/vibe/rules/security.md"
-    ],
-    "languages": [
-      "~/.claude/vibe/languages/typescript-react.md"
-    ],
-    "templates": [
-      "~/.claude/vibe/templates/spec-template.md",
-      "~/.claude/vibe/templates/feature-template.md",
-      "~/.claude/vibe/templates/constitution-template.md"
-    ]
-  }
-}
-```
-
-**Workflow:**
-
-1. Read `.claude/vibe/config.json`
-2. Extract `references.languages[]` paths
-3. Read each language document for stack-specific guidelines
-
-**Example:**
-```bash
-# 1. Check references in config.json
-Read .claude/vibe/config.json
-
-# 2. Reference documents specified in references.languages
-Read ~/.claude/vibe/languages/typescript-react.md
-```
-
-**Important:**
-
-- No manual mapping needed - config.json contains all reference paths
-- `config.json.references` is automatically referenced when running `/vibe.run`
-- Not copied to project (referenced from global package)
-
-### 2.9 Research Cache Check (BEFORE step 3)
-
-Before spawning any research agents, check for a prior persisted dataset:
-
-```bash
-# Slug = kebab-case of the feature/topic, max 50 chars
-ls .claude/vibe/research/<slug>/paper.md 2>/dev/null
-```
-
-**If `paper.md` exists:**
-1. Read `.claude/vibe/research/<slug>/paper.md`
-2. Read `.claude/vibe/research/<slug>/awesome-list.md` (if present)
-3. Inject the **Findings**, **Recommendation**, and **Security considerations** sections verbatim into SPEC Context, prefixed with `> Source: .claude/vibe/research/<slug>/paper.md (cached {{FILE_MTIME}})`
-4. **Skip step 3** (parallel research) entirely — do not re-run GPT/Gemini/Claude agents
-5. Print: `✅ Research cache hit: <slug> (saved ~30s of LLM calls)`
-
-**Cache invalidation:**
-- User passes `--refresh-research` → delete dir, rerun step 3 from scratch
-- `paper.md` mtime older than 30 days → warn the user, ask to refresh or reuse
-- `stack` in `paper.md` frontmatter differs from current stack → auto-refresh
-
-**If `paper.md` does NOT exist:**
-Proceed to step 3. After step 3 completes, the synthesizer **must** write the 3 artifacts (see `parallel-research/orchestrator.md` Phase 5) so the next `/vibe.spec` run on this topic hits the cache.
-
-### 3. Parallel Research (v2.5.0) - MANDATORY AFTER requirements confirmed
-
-**🚨🚨🚨 ABSOLUTE RULES FOR RESEARCH PHASE 🚨🚨🚨**
-
-**STOP! Before doing ANY research, read this carefully:**
-
-1. **DO NOT** use Task tool to spawn research agents
-2. **DO NOT** use context7 MCP directly for research
-3. **DO NOT** use WebSearch tool directly for research
-4. **YOU MUST** use Bash tool to call llm-orchestrate.js directly
-
-**🚨🚨🚨 CRITICAL: NO FILE CREATION DURING RESEARCH 🚨🚨🚨**
-
-5. **DO NOT** create any files in project root during research
-6. **DO NOT** create SECURITY_*.md, RESEARCH_*.md, SUMMARY_*.md files
-7. **DO NOT** use Write tool during research phase
-8. **ALL research results** must be returned as text output only
-9. **Files are ONLY created** in Step 4 (SPEC) and Step 5 (Feature) in `.claude/vibe/` directory
-
-**When to trigger:**
-1. ✅ Feature type decided (e.g., "passkey authentication")
-2. ✅ Tech stack confirmed (e.g., "React + Supabase")
-3. ✅ Language guide copied (step 2.5)
-4. ✅ Core requirements collected
-
-**→ IMMEDIATELY run these 6 Bash commands IN PARALLEL (all at once):**
-
-**Step 0: Script path:**
-- `[LLM_SCRIPT]` = `{{VIBE_PATH}}/hooks/scripts/llm-orchestrate.js`
-
-**Run all 4 in PARALLEL (each as separate Bash tool call):**
-```bash
-# 1. GPT: Best practices (codex — code review & analysis)
-node "[LLM_SCRIPT]" gpt-codex orchestrate-json "Best practices for [FEATURE] with [STACK]. Focus: architecture patterns, code conventions. Return JSON: {patterns: [], antiPatterns: [], libraries: []}"
-
-# 2. GPT: Security (codex — code review & analysis)
-node "[LLM_SCRIPT]" gpt-codex orchestrate-json "Security vulnerabilities for [FEATURE] with [STACK]. Focus: CVE database, known exploits. Return JSON: {vulnerabilities: [], mitigations: [], checklist: []}"
-
-# 3. Gemini: Best practices
-node "[LLM_SCRIPT]" gemini orchestrate-json "Best practices for [FEATURE] with [STACK]. Focus: latest trends, framework updates. Return JSON: {patterns: [], antiPatterns: [], libraries: []}"
-
-# 4. Gemini: Security
-node "[LLM_SCRIPT]" gemini orchestrate-json "Security advisories for [FEATURE] with [STACK]. Focus: latest patches, recent incidents. Return JSON: {advisories: [], patches: [], incidents: []}"
-```
-
-**Concrete example - run all 4 in parallel:**
-```bash
-# GPT best practices (codex — code review & analysis)
-node "[LLM_SCRIPT]" gpt-codex orchestrate-json "Best practices for passkey authentication with React, Supabase. Focus: architecture patterns, code conventions. Return JSON: {patterns: [], antiPatterns: [], libraries: []}"
-
-# GPT security (codex — code review & analysis)
-node "[LLM_SCRIPT]" gpt-codex orchestrate-json "Security vulnerabilities for passkey authentication with React, Supabase. Focus: CVE database, known exploits. Return JSON: {vulnerabilities: [], mitigations: [], checklist: []}"
-
-# Gemini best practices
-node "[LLM_SCRIPT]" gemini orchestrate-json "Best practices for passkey authentication with React, Supabase. Focus: latest trends, framework updates. Return JSON: {patterns: [], antiPatterns: [], libraries: []}"
-
-# Gemini security
-node "[LLM_SCRIPT]" gemini orchestrate-json "Security advisories for passkey authentication with React, Supabase. Focus: latest patches, recent incidents. Return JSON: {advisories: [], patches: [], incidents: []}"
-```
-
-**ALSO run Claude research agents in parallel using Task tool:**
-
-| Claude Agent | Role | Source |
-|--------------|------|--------|
-| `best-practices-agent` | Best practices for [feature] + [stack] | WebSearch |
-| `framework-docs-agent` | Latest docs via context7 | context7 MCP |
-| `codebase-patterns-agent` | Similar patterns in existing codebase | Glob, Grep |
-| `security-advisory-agent` | Security advisories for [feature] | WebSearch |
-
-**Total: 4 GPT/Gemini calls (Bash) + 4 Claude agents (Task) = 8 parallel research tasks**
-
-**🚨 GPT/Gemini MUST be called via Bash with llm-orchestrate.js! 🚨**
-
-#### 3.0.1 Agent Teams — Research Collaboration
-
-> **Team definition**: See `agents/teams/research-team.md`
-> Settings: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` + `teammateMode: in-process` (`~/.claude/settings.json` global — auto-configured by postinstall)
-
-**Discussion results are reflected in the SPEC's Context section.**
-
-#### 3.1 Result Merge Rules
-
-| Area | Merge Strategy |
-|------|----------------|
-| Best Practices | Deduplicate, keep most detailed |
-| Security | ALL included (no dedup for safety) |
-| Libraries | Consensus recommendations |
-
-**IMPORTANT:**
-- ❌ DO NOT skip research step
-- ❌ DO NOT ask user "should I run research?"
-- ✅ ALWAYS run after requirements confirmed
-- ✅ Show "Running parallel research (Claude + GPT + Gemini)..." message
-- ✅ Include all agent + LLM results in SPEC Context
-- ✅ Run all 4 Bash LLM calls in parallel + 4 Task agents in parallel
-
-**Research results are reflected in SPEC's Context section.**
-
-### 3.2 UI/UX Design Intelligence (Auto-triggered)
-
-> **Condition**: Auto-executes when UI/UX keywords are present in the SPEC context (website, landing, dashboard, app, e-commerce, portfolio, SaaS, mobile app, web app, UI, UX, frontend, design)
-> **Disable**: Set `"uiUxAnalysis": false` in `.claude/vibe/config.json`
-
-**When UI/UX keywords are detected, run 3 agents sequentially in parallel with research:**
-
-```
-[Parallel Research] GPT + Gemini + Claude agents
-        ↓ (concurrent execution)
-[UI/UX Intelligence]
-  ① ui-industry-analyzer (Haiku) → industry analysis + design strategy
-        ↓
-  ②③ parallel execution:
-    ② ui-design-system-gen (Sonnet) → generate MASTER.md
-    ③ ui-layout-architect (Haiku) → layout design
-```
-
-**How to execute:**
-
-1. **① ui-industry-analyzer** — Run as Task(haiku) agent:
-```text
-Task(subagent_type="ui-industry-analyzer",
-  prompt="Analyze product: [USER_DESCRIPTION]. Use core_ui_search to detect category, style priority, color mood, typography mood. Save result to .claude/vibe/design-system/{project}/analysis-result.json")
-```
-
-2. **②③ parallel execution** — Using ①'s result as input:
-```text
-# ② Generate design system (Sonnet)
-Task(subagent_type="ui-design-system-gen",
-  prompt="Generate design system from analysis-result.json for project '{project}'. Use core_ui_search for style/color/typography, then core_ui_generate_design_system and core_ui_persist_design_system.")
-
-# ③ Layout design (Haiku) — parallel execution
-Task(subagent_type="ui-layout-architect",
-  prompt="Design layout from analysis-result.json for project '{project}'. Use core_ui_search for landing patterns and dashboard layout.")
-```
-
-3. **Inject results into SPEC Context:**
-```markdown
-### Design System (Auto-generated)
-- Category: {① category}
-- Style: {① style_priority}
-- MASTER.md: .claude/vibe/design-system/{project}/MASTER.md
-- Layout: {③ pattern + sections}
-```
-
-### 3.9 Persist Research Cache (AFTER research completes, BEFORE SPEC write)
-
-> The "no Write during research" rule from step 3 does **not** apply here — research is done; artifacts are safe to persist.
-
-After parallel research + UI/UX intelligence complete, before writing the SPEC, save the merged research to `.claude/vibe/research/<slug>/`:
-
-1. Compute slug: kebab-case of feature name, max 50 chars
-2. Write **three files** using templates from `parallel-research/templates/`:
-   - `.claude/vibe/research/<slug>/synthesis.md` — raw merged findings (all agent outputs)
-   - `.claude/vibe/research/<slug>/awesome-list.md` — curated links/repos/patterns (every entry needs a one-line "why"; drop entries without one)
-   - `.claude/vibe/research/<slug>/paper.md` — structured survey (Abstract → Background → Method → Findings → Recommendation → Security → References)
-3. Include a frontmatter header in `paper.md` with a `stack:` field so step 2.9 can detect stack drift
-4. If the directory already exists (user passed `--refresh-research`), overwrite
-
-This makes the next `/vibe.spec` (or future `/vibe.research`) invocation on the same topic hit the cache at step 2.9.
-
-### 4. Write SPEC Document (PTCF Structure)
-
-#### 4.0 Large Scope Detection & Auto-Split (MANDATORY)
-
-**🚨 CRITICAL: Automatically split SPEC when scope is large**
-
-**❌ DO NOT ask user for confirmation - auto-split silently**
-
-**Detection criteria (ANY triggers split):**
-
-| Criteria | Threshold |
-|----------|-----------|
-| Phases | 5+ phases |
-| Files to create | 15+ files |
-| Platforms | 2+ platforms |
-| Major features | 4+ distinct features |
-
-**Auto-split output (SPEC + Feature files must match):**
-
-```
-.claude/vibe/specs/{feature-name}/
-├── _index.md           # Master SPEC
-├── phase-1-setup.md
-├── phase-2-core.md
-└── ...
-
-.claude/vibe/features/{feature-name}/
-├── _index.feature      # Master Feature
-├── phase-1-setup.feature
-├── phase-2-core.feature
-└── ...
-```
-
-**🚨 CRITICAL: Each SPEC phase file MUST have a matching Feature file**
-
-**Master SPEC (`_index.md`):**
-
-```markdown
-# SPEC: {feature-name} (Master)
-
-## Overview
-- Total phases: N
-- Dependencies: [list]
-
-## Sub-SPECs
-
-| Order | SPEC File | Feature File | Status |
-|-------|-----------|--------------|--------|
-| 1 | phase-1-setup.md | phase-1-setup.feature | ⬜ |
-| 2 | phase-2-core.md | phase-2-core.feature | ⬜ |
-
-## Shared Context
-- Tech Stack: [all phases]
-- Constraints: [all phases]
-```
-
-**Master Feature (`_index.feature`):**
-
-```markdown
-# Feature: {feature-name} (Master)
-
-**Master SPEC**: `.claude/vibe/specs/{feature-name}/_index.md`
-
-## Sub-Features
-
-| Order | Feature File | SPEC File | Status |
-|-------|--------------|-----------|--------|
-| 1 | phase-1-setup.feature | phase-1-setup.md | ⬜ |
-| 2 | phase-2-core.feature | phase-2-core.md | ⬜ |
-
-## Overall User Story
-**As a** {user}
-**I want** {complete feature}
-**So that** {value}
-```
-
-**Small scope (default):**
-
-Create `.claude/vibe/specs/{feature-name}.md`:
-
-```markdown
----
-status: pending
-currentPhase: 0
-totalPhases: 3
-createdAt: {ISO-timestamp}
-lastUpdated: {ISO-timestamp}
----
-
-# SPEC: {feature-name}
-
-## Persona
-<role>
-Define AI role and expertise for implementation
-- Senior developer on the project
-- Follow existing code patterns
-- Write testable code
-</role>
-
-## Context
-<context>
-### Background
-- Why this feature is needed
-- Who will use it
-
-### Tech Stack
-- Backend: {technology}
-- Frontend: {technology}
-- Database: {technology}
-
-### Related Code
-- `src/xxx/`: Existing implementation to reference
-- `src/yyy/`: Files to modify
-
-### Design Reference
-- {Reference app/service}
-</context>
-
-## Task
-<task>
-### Phase 1: {phase-name}
-1. [ ] {specific task}
-   - File: `path/to/file`
-   - Verify: `command`
-2. [ ] {specific task}
-
-### Phase 2: {phase-name}
-1. [ ] {specific task}
-2. [ ] {specific task}
-
-### Phase 3: Testing and Verification
-1. [ ] Unit Tests
-2. [ ] Integration Tests
-</task>
-
-## Constraints
-<constraints>
-- Follow existing code patterns
-- Localize error messages
-- Separate configuration via environment variables
-- {other constraints}
-</constraints>
-
-## Output Format
-<output_format>
-### Files to Create
-- `path/to/new/file.ts`
-- `path/to/new/file.test.ts`
-
-### Files to Modify
-- `path/to/existing/file.ts`
-
-### Verification Commands
-- `npm test`
-- `npm run build`
-</output_format>
-
-## Acceptance Criteria
-<acceptance>
-- [ ] {verifiable criterion 1}
-- [ ] {verifiable criterion 2}
-- [ ] All tests pass
-- [ ] Build succeeds
-</acceptance>
-```
-
-### 5. Create Feature File (BDD) - Required
-
-**🚨 CRITICAL: Feature files MUST match SPEC file structure**
-
-| SPEC Structure | Feature Structure |
-|----------------|-------------------|
-| Single file (`{feature}.md`) | Single file (`{feature}.feature`) |
-| Split (`{feature}/_index.md` + phases) | Split (`{feature}/_index.feature` + phases) |
-
-#### 5.1 Single File (Small Scope)
-
-Create `.claude/vibe/features/{feature-name}.feature`:
-
-**Creation rules:**
-1. Convert each SPEC Acceptance Criteria → one Scenario
-2. Include Happy Path (normal case) + Edge Case (exception case)
-3. Follow Given-When-Then format
-
-```markdown
-# Feature: {feature-name}
-
-**SPEC**: `.claude/vibe/specs/{feature-name}.md`
-
-## User Story
-**As a** {user}
-**I want** {feature}
-**So that** {value}
-
-## Scenarios
-
-### Scenario 1: {Happy Path}
-\`\`\`gherkin
-Scenario: {title}
-  Given {precondition}
-  When {action}
-  Then {result}
-\`\`\`
-**Verification**: SPEC AC #1
-
-### Scenario 2: {Edge Case}
-...
-
-## Coverage
-| Scenario | SPEC AC | Status |
-|----------|---------|--------|
-| 1 | AC-1 | ⬜ |
-```
-
-#### 5.2 Split Files (Large Scope)
-
-When SPEC is split into phases, Feature files MUST also be split:
-
-```
-.claude/vibe/features/{feature-name}/
-├── _index.feature        # Master: links to all phase features
-├── phase-1-setup.feature # Scenarios for phase-1-setup.md
-├── phase-2-core.feature  # Scenarios for phase-2-core.md
-└── ...
-```
-
-**Phase Feature file structure:**
-
-```markdown
-# Feature: {feature-name} - Phase {N}: {phase-name}
-
-**SPEC**: `.claude/vibe/specs/{feature-name}/phase-{N}-{name}.md`
-**Master Feature**: `.claude/vibe/features/{feature-name}/_index.feature`
-
-## User Story (Phase Scope)
-**As a** {user}
-**I want** {phase-specific feature}
-**So that** {phase-specific value}
-
-## Scenarios
-
-### Scenario 1: {Phase Happy Path}
-...
-
-## Coverage
-| Scenario | SPEC AC | Status |
-|----------|---------|--------|
-| 1 | Phase {N} AC-1 | ⬜ |
-```
-
-### 6. Ambiguity Scan - Required
-
-After creating SPEC draft, **must perform systematic ambiguity check**.
-
-#### 6.1 Mandatory Check Categories
-
-| Category | Check Items | Red Flags |
-|----------|-------------|-----------|
-| **Functional Scope** | Missing features, unclear behavior | "etc.", "other", "if needed" |
-| **Data Model** | Undefined entities, relationships | Undefined types, missing fields |
-| **Non-Functional** | Performance, security requirements | Performance requirements without numbers |
-| **Edge Cases** | Boundary conditions, errors | 0 failure scenarios |
-| **Integration Points** | External APIs, contracts | API version/endpoint undefined |
-| **User Input** | Validation rules, limits | Input limits not specified |
-| **State Management** | State transitions, persistence | Missing state diagram |
-
-#### 6.2 Forbidden Ambiguous Terms
-
-If the following terms exist in SPEC, **clarification is mandatory**:
-
-| Forbidden Term | Replacement Method |
-|----------------|-------------------|
-| "appropriately", "properly" | Provide specific criteria (e.g., "within 3 seconds") |
-| "quickly", "rapidly" | Specify with numbers (e.g., "under 100ms") |
-| "various", "multiple" | List specific items |
-| "etc.", "other" | Specify complete list or limit scope |
-| "if needed", "depending on situation" | Specify conditions (e.g., "when credits < 10") |
-| "later", "in the future" | Explicitly exclude from current scope |
-
-#### 6.3 Check Process
-
-```
-1. Write SPEC draft
-      ↓
-2. Auto-scan for forbidden terms
-      ↓
-3. Review checklist by category
-      ↓
-4. List discovered ambiguities
-      ↓
-5. Auto-fixable items → Fix immediately
-   Needs user confirmation → Ask question
-      ↓
-6. Re-verify (max 2 rounds — remaining ambiguities → user confirmation or TODO)
-```
-
-#### 6.4 Auto-Fix for Common Ambiguities
-
-| Ambiguity Type | Auto-Fix Method |
-|----------------|-----------------|
-| Timeout undefined | Apply default 30 seconds |
-| Retry count undefined | Apply default 3 retries |
-| Pagination undefined | Apply default 20 items/page |
-| Input length undefined | Text 500 chars, password 8-64 chars |
-| File size undefined | Image 5MB, video 100MB |
-
-#### 6.5 Ambiguity Output Format
-
-```markdown
-## 🔍 Ambiguity Scan Results
-
-### Found Issues: 3
-
-#### 1. Functional Scope
-- ⚠️ "Login failure behavior" not defined
-  → **Auto-fix**: Apply 5-minute lockout after 3 failures
-- ⚠️ "Session expiration handling" unclear
-  → **Question**: Session expiration time? (30min/1hour/24hours)
-
-#### 2. Edge Cases
-- ⚠️ Concurrent login permission undefined
-  → **Question**: Allow concurrent login? (Y/N)
-
-### Auto-fixed: 1
-### Needs clarification: 2
-```
-
-### 7. Quality Validation (Self-Check)
-
-**Must perform self-quality check after SPEC completion**
-
-#### 7.1 Quality Checklist (Required Items)
-
-| Category | Check Item | Weight |
-|----------|------------|--------|
-| **Completeness** | All user flows included in Task | 15% |
-| **Completeness** | All ACs converted to Feature scenarios | 10% |
-| **Clarity** | No ambiguous terms (e.g., "appropriately", "quickly") | 10% |
-| **Clarity** | All numbers/limits specified (e.g., "max 500 chars") | 10% |
-| **Testability** | All ACs are auto-testable | 10% |
-| **Security** | Authentication/authorization requirements defined | 10% |
-| **Security** | Sensitive data handling method specified | 5% |
-| **Error Handling** | Major failure scenarios defined | 10% |
-| **Error Handling** | User error messages specified | 5% |
-| **Performance** | Response time/throughput targets specified | 5% |
-| **Edge Cases** | Boundary condition handling defined | 5% |
-| **Dependencies** | External systems/APIs specified | 5% |
-
-#### 7.2 Quality Score Calculation
-
-```
-Score = Σ(Check item met × Weight) / 100
-
-Grades:
-- 95-100: ✅ EXCELLENT - Ready to start implementation
-- 90-94:  ⚠️ GOOD - Minor improvements required before implementation
-- 80-89:  ⚠️ FAIR - Significant improvements required
-- 0-79:   ❌ POOR - Rewrite required
-```
-
-#### 7.3 Quality Gate (Auto-verification)
-
-**100 points required to complete SPEC draft. Loop until perfect — ask user if auto-fixer hits a wall.**
-
-```
-SPEC writing complete
-      ↓
-[Calculate Quality Score]
-      ↓
-Score < 100? → Show missing items → Auto-fix → Re-evaluate
-      ↓
-Stuck? (score == prev_score)
-  ├─ Interactive: ask user → fill values OR "proceed" OR "abort"
-  └─ ultrawork: record gaps as TODO → proceed
-      ↓
-Score == 100 (or user-approved) → SPEC Draft Complete → Handoff to vibe-spec-review skill
-```
-
-#### 7.4 Auto-Fix for Low Score
-
-If score is below 100, attempt automatic fixes:
-
-| Missing Item | Auto-Fix Method |
-|--------------|-----------------|
-| Missing AC | Auto-generate AC based on Task |
-| Numbers not specified | Apply project defaults (e.g., timeout 30s) |
-| Missing error handling | Add common error scenarios |
-| Missing performance targets | Apply industry standard criteria |
-
-### 8. SPEC Draft Complete - Handoff to Review
-
-**🚨 IMPORTANT: GPT/Gemini review is now a SEPARATE command**
-
-After SPEC draft is complete (score ≥ 95):
-
-**If `ultrawork` mode:**
-- ❌ DO NOT show handoff message
-- ❌ DO NOT ask for confirmation
-- ✅ Immediately load skill `vibe-spec-review` with feature `{feature-name}` (chain-next)
-- ✅ After review passes, immediately proceed to `/vibe.run "{feature-name}" ultrawork`
-
-**If normal mode:**
-Output the handoff message:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-✅ SPEC DRAFT COMPLETE: {feature-name}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-📋 SPEC: .claude/vibe/specs/{feature-name}.md
-📋 Feature: .claude/vibe/features/{feature-name}.feature
-📊 Quality Score: {score}/100
-⏱️ Started: {start_time}
-⏱️ Completed: {getCurrentTime result}
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-⚠️ NEXT STEP: Run SPEC review (vibe-spec-review skill)
-
-Option 1 (same session):
-  Load skill `vibe-spec-review` with feature `{feature-name}`
-  (or natural language: "spec review")
-
-Option 2 (recommended for large context):
-  /new → /vibe.spec "{feature-name}"
-  (Smart Resume will start from Phase 4)
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-**Tip:** New session recommended when context > 50% to ensure review accuracy
-
-## Output (MANDATORY File Creation)
-
-**🚨 CRITICAL: Files MUST be created in these EXACT paths. NO exceptions.**
-
-### Small Scope (Single File)
-
-| File | Path | When |
-|------|------|------|
-| SPEC | `.claude/vibe/specs/{feature-name}.md` | After quality validation (Step 7) |
-| Feature | `.claude/vibe/features/{feature-name}.feature` | Immediately after SPEC |
-
-### Large Scope (Split Files)
-
-| File | Path | When |
-|------|------|------|
-| Master SPEC | `.claude/vibe/specs/{feature-name}/_index.md` | After quality validation |
-| Phase SPEC | `.claude/vibe/specs/{feature-name}/phase-{N}-{name}.md` | Per phase |
-| Master Feature | `.claude/vibe/features/{feature-name}/_index.feature` | After Master SPEC |
-| Phase Feature | `.claude/vibe/features/{feature-name}/phase-{N}-{name}.feature` | Per phase SPEC |
-
-**❌ FORBIDDEN:**
-
-- Creating files in project root (e.g., `feature-name.md`)
-- Creating files outside `.claude/vibe/` directory
-- Skipping file creation
-- Using different file names than feature-name
-- Creating split SPEC without matching split Feature files
-
-**✅ REQUIRED:**
-
-- Use Write tool to create files
-- Verify directories exist (create if needed)
-- Confirm file creation in response
-- **Each SPEC file must have a matching Feature file**
-
-### File Creation Template
-
-**Single file:**
-```
-1. Write .claude/vibe/specs/{feature-name}.md
-2. Write .claude/vibe/features/{feature-name}.feature
-3. Confirm: "✅ Created: specs/{feature-name}.md + features/{feature-name}.feature"
-```
-
-**Split files:**
-```
-1. Write .claude/vibe/specs/{feature-name}/_index.md
-2. Write .claude/vibe/specs/{feature-name}/phase-1-setup.md
-3. Write .claude/vibe/specs/{feature-name}/phase-2-core.md
-4. Write .claude/vibe/features/{feature-name}/_index.feature
-5. Write .claude/vibe/features/{feature-name}/phase-1-setup.feature
-6. Write .claude/vibe/features/{feature-name}/phase-2-core.feature
-7. Confirm: "✅ Created: {N} SPEC files + {N} Feature files"
-```
-
-## Example
-
-```
-User: /vibe.spec "brick-game"
-
-Claude:
-You're making a brick game! What style are you thinking of?
-
-1. Classic Breakout style
-2. Arkanoid (with power-up items)
-3. Custom style with special gameplay
-
-Feel free to describe in your own words.
-
-User: 1
-
-Claude: What platform will it run on?
-
-1. Web (browser)
-2. Mobile (iOS/Android)
-3. Desktop
-
-User: 1
-
-Claude:
-Here are tech stack suggestions for web game development:
-
-1. **Phaser.js** (Recommended) - Game framework with built-in physics engine
-2. **Canvas + JavaScript** - Lightweight with fine control
-3. **PixiJS + Matter.js** - High-performance rendering
-
-User: 1
-
-Claude: What design style?
-
-1. Retro pixel (Atari Breakout)
-2. Neon graphics (Arkanoid)
-3. Modern 3D effects
-
-User: 2
-
-[Conversation continues...]
-
-Claude: SPEC draft created. Running ambiguity scan.
-
-## 🔍 Ambiguity Scan Results
-
-### Functional Scope
-- ⚠️ Game over condition not defined (ball drop vs lives system)
-- ⚠️ Stage clear condition unclear
-
-### Edge Cases
-- ⚠️ Ball reflection angle when hitting paddle edge
-- ⚠️ Multiple brick collision handling
-
-Please clarify the above items.
-
-User: 3 lives, clear when all bricks destroyed, edge reflects at 45 degrees
-
-Claude: Thank you. SPEC has been refined.
-
-🔍 Re-check result: 0 ambiguities
-📊 Quality score: 92/100 (A)
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🔍 SPEC REVIEW (Gemini)
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-📤 Sending SPEC...
-📝 Gemini feedback:
-  1. [Edge] Ball speed increase logic undefined
-  2. [Security] Need score manipulation prevention
-
-✅ 2 improvements auto-applied
-🔍 Re-verifying... ✅ Passed
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-✅ SPEC Complete!
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-📄 .claude/vibe/specs/brick-game.md (PTCF structure)
-📄 .claude/vibe/features/brick-game.feature
-📊 Quality score: 100/100 ← Loop converged (no remaining gaps)
-```
-
-## Core Tools (Semantic Analysis & Memory)
-
-### Tool Invocation
-All tools are called via:
-```bash
-node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index.js').then(t => t.TOOL_NAME({...args}).then(r => console.log(r.content[0].text)))"
-```
-
-### Recommended Tools for SPEC Creation
-
-| Tool | Purpose | When to Use |
-|------|---------|-------------|
-| `findSymbol` | Find symbol definitions | Locate existing implementations to reference |
-| `findReferences` | Find all references | Understand how existing code is used |
-| `analyzeComplexity` | Code complexity analysis | Evaluate complexity of code to modify |
-| `saveMemory` | Save important decisions | Store confirmed requirements, design decisions |
-| `recallMemory` | Recall saved memory | Retrieve previous project decisions |
-
-### Example Tool Usage in SPEC Creation
-
-**1. Find existing auth implementation:**
-```bash
-node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index.js').then(t => t.findSymbol({symbolName: 'login', searchPath: 'src/'}).then(r => console.log(r.content[0].text)))"
-```
-
-**2. Save confirmed requirements:**
-```bash
-node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index.js').then(t => t.saveMemory({key: 'brick-game-requirements', value: 'Platform: Web, Stack: Phaser.js, Style: Neon', category: 'spec', projectPath: process.cwd()}).then(r => console.log(r.content[0].text)))"
-```
-
-**3. Recall previous decisions:**
-```bash
-node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index.js').then(t => t.recallMemory({key: 'brick-game-requirements', projectPath: process.cwd()}).then(r => console.log(r.content[0].text)))"
-```
-
-## Next Step
-
-```
-/vibe.run "brick-game"
-```
-
----
-
-ARGUMENTS: $ARGUMENTS
+---
+name: vibe-spec
+tier: core
+description: "Create an AI-executable PTCF-structured SPEC document through conversational requirements gathering, parallel research (GPT/Gemini/Claude agents), PTCF writing, ambiguity scan, and 100-point quality gate (loops until perfect or stuck). Produces .claude/vibe/specs/{feature}.md + matching .claude/vibe/features/{feature}.feature (BDD). Must use this skill when the user says 'write spec', 'create spec', '/vibe.spec', or when a plan document exists and is ready for code specification."
+triggers: [spec, SPEC, 명세, "코드 명세", "구현 명세", "write spec", "create spec", PTCF]
+priority: 85
+chain-next: [vibe-spec-review]
+---
+
+# vibe.spec — Specification Agent
+
+Create a SPEC document (Specification Agent).
+
+## Usage
+
+```
+/vibe.spec "feature-name"                    # Conversation mode (requirements gathering)
+/vibe.spec "feature-name" ultrawork          # Auto: SPEC → Review → Implementation
+/vibe.spec "docs/login-prd.md"               # File path input (auto-detected)
+/vibe.spec + 📎 file attachment              # Use attached file
+```
+
+### ultrawork Mode
+
+When `ultrawork` (or `ulw`) is included, automatically chains:
+
+```
+/vibe.spec "feature" ultrawork
+    ↓
+[1] SPEC Creation (this command)
+    ↓
+[2] Auto: Load skill `vibe-spec-review` (chain-next from this skill)
+    ↓
+[3] Auto: /vibe.run "{feature}" ultrawork
+```
+
+**No manual intervention between steps.**
+
+> **⏱️ Timer**: Call `getCurrentTime` tool at the START. Record the result as `{start_time}`.
+
+## Input Mode Detection (Auto-detect)
+
+**Input priority:**
+
+```
+1. Attachment exists? → Use attached file
+2. Argument is file path? (existence check) → Read file
+3. Otherwise → Conversation mode (start with feature name)
+```
+
+| Input | Result |
+|-------|--------|
+| 📎 Attached file | → Analyze attached file |
+| File path (exists) | → Read file (Read tool) |
+| Feature name | → Start conversation mode |
+
+**All supported files:**
+- Text: `.md`, `.txt`, `.rst`, `.html`, `.json`, `.yaml`, etc.
+- Documents: `.pdf` (page-by-page analysis)
+- Images: `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.svg`, etc.
+- Notebooks: `.ipynb` (Jupyter)
+- **All formats Claude can read**
+
+**File input mode flow:**
+
+```
+/vibe.spec "docs/login-prd.md"
+
+📄 File loaded: docs/login-prd.md (2.3KB)
+
+📋 Parsed requirements:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Feature: Login
+  - Email/password login
+  - Social login (Google, Apple)
+  - Password recovery
+  - Auto login persistence
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+❓ Additional confirmation needed:
+  1. Session expiration time? (default: 24 hours)
+  2. Allow concurrent login?
+  3. Confirm tech stack? (current: React + Supabase)
+
+User: 1 hour, disallow, confirm
+
+✅ Requirements confirmed → Run research → Generate SPEC → Review
+```
+
+**Supported file formats:**
+
+| Format | Extension | Purpose |
+|--------|-----------|---------|
+| Markdown | `.md` | PRD, planning docs, README |
+| Text | `.txt` | Requirements list |
+| PDF | `.pdf` | Planning docs, design documents |
+| Image | `.png`, `.jpg`, `.jpeg`, `.webp` | Wireframes, UI design, screenshots |
+
+**Image input analysis:**
+
+When image files (`.png`, `.jpg`, `.jpeg`, `.webp`) are provided as input, analyze them using the best available method:
+
+- **Gemini Enabled**: `llm-orchestrate.js gemini analyze-image` (Gemini Flash - best image recognition)
+- **Gemini Disabled**: Claude Opus Read tool (built-in multimodal, existing behavior)
+
+**Gemini enabled - analyze via llm-orchestrate.js:**
+
+```bash
+# [LLM_SCRIPT] = {{VIBE_PATH}}/hooks/scripts/llm-orchestrate.js
+node "[LLM_SCRIPT]" gemini analyze-image "./designs/login-wireframe.png" "Analyze this UI design image. Identify all UI elements, layout structure, colors, typography, and component hierarchy. Output a structured breakdown."
+```
+
+Parse the JSON result: `{ success: true, analysis: "..." }` → use `analysis` field content.
+
+If `success: false`, fall back to Claude Read tool.
+
+**Gemini disabled - analyze via Claude Read tool:**
+
+Use the Read tool directly on the image file. Claude can read images natively.
+
+**Image input example:**
+```
+/vibe.spec "designs/login-wireframe.png"
+
+🖼️ Image analysis: designs/login-wireframe.png
+   (via Gemini Flash / Claude Opus)
+
+📋 Detected UI elements:
+  - Email input field
+  - Password input field
+  - "Login" button
+  - "Forgot password" link
+  - Social login buttons (Google, Apple)
+
+❓ Confirmation needed:
+  1. Feature name? (e.g., "login")
+  2. Additional requirements?
+
+→ Generate SPEC
+```
+
+## Rules Reference
+
+**Must follow `~/.claude/vibe/rules/` (global):**
+- `core/development-philosophy.md` - Surgical precision, simplicity
+- `core/quick-start.md` - Korean first, DRY, SRP
+- `core/communication-guide.md` - Communication principles
+
+## Description
+
+Collect requirements through conversation with the user and create an **AI-executable PTCF structured SPEC document**.
+
+> **PTCF**: Persona, Task, Context, Format - Google Gemini prompt optimization framework
+
+## External LLM Integration (GPT/Gemini)
+
+When GPT/Gemini are enabled, they are automatically utilized during SPEC creation:
+
+```
+/vibe.spec "feature"
+      ↓
+[Claude] Draft SPEC
+      ↓
+[Parallel Research] GPT + Gemini + Claude agents (8 parallel)
+      ↓
+[SPEC Review] GPT + Gemini parallel review
+      ↓
+[Claude] Finalize SPEC
+```
+
+**Setup:**
+```bash
+vibe gpt key <key>      # Enable GPT
+vibe gemini key <key>   # Enable Gemini
+vibe status         # Check current settings
+```
+
+## Process
+
+### 0. Git Branch Setup (MANDATORY - Execute First!)
+
+> ⚠️ **CRITICAL: You MUST execute this step FIRST before anything else!**
+> This is NOT optional documentation - you must RUN these git commands.
+
+**Step 0 is BLOCKING - do not proceed to Step 1 until branch is ready.**
+
+**Execute these commands using Bash tool:**
+
+```bash
+# 1. Check current branch
+git branch --show-current
+```
+
+**Then based on result:**
+
+| Current Branch | Action |
+|----------------|--------|
+| `main` or `master` | **MUST** create feature branch: `git checkout -b feature/{feature-name}` |
+| `feature/*` | Ask user: "Continue on this branch or create new?" |
+| Other | Ask user to confirm |
+
+**Example execution:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🌿 GIT BRANCH SETUP
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Current branch: main
+
+Creating feature branch...
+$ git checkout -b feature/login-page
+
+✅ Switched to new branch: feature/login-page
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Branch naming rules:**
+- Convert to lowercase: `Login Page` → `login-page`
+- Replace spaces with hyphens
+- Prefix with `feature/`
+- Example: `feature/passkey-auth`, `feature/dark-mode`
+
+**`.last-feature` pointer update** (immediately after Git branch setup):
+
+```
+Write ".claude/vibe/.last-feature" ← feature-name (single line)
+Execute at the point when the feature name is finalized.
+No-op if the value is already the same.
+```
+
+### 1. Project Analysis
+
+**Existing project** (`vibe init`):
+- Reference `CLAUDE.md` file (tech stack)
+- **Delegate codebase analysis to explorer agent** — do NOT read project files in main session:
+
+```text
+Task(subagent_type="explorer-low",
+  prompt="Analyze project structure: package.json, pyproject.toml, pubspec.yaml, go.mod.
+  Find existing implementations related to [FEATURE]. Return: tech stack, relevant files, patterns used.
+  Keep summary under 200 tokens.")
+```
+
+**New project** (`vibe init <project-name>`):
+- Suggest tech stack (2-3 options)
+
+### 2. Collect Requirements via Conversation
+
+**Principles:**
+- Ask **one question at a time**
+- Present options **with numbers** + "Feel free to describe in your own words"
+- **Natural conversation** without fixed order
+
+**Required confirmations:**
+- Purpose (Why): Why is it needed?
+- User (Who): Who will use it?
+- Feature scope (What): What features are needed?
+- Tech stack: Confirm existing stack or suggest new
+- Design reference: UI/UX to reference
+
+### 2.1 Critical Requirements Confirmation (askUser) - v2.6.1
+
+**🚨 IMPORTANT: Use `askUser` tool for CRITICAL requirements that must not be missed**
+
+After initial conversation, use the structured `askUser` tool for:
+- 🔐 Authentication: method, MFA, password policy
+- 🛡️ Security: rate limiting, session management
+- ⏱️ Session: duration, concurrent login policy
+- 📊 Data Model: required fields, relationships
+
+**When to use askUser vs conversation:**
+
+| Scenario | Method |
+|----------|--------|
+| Exploratory (feature scope, style) | Natural conversation |
+| **Critical** (auth, security, session) | `askUser` tool |
+| Optional (performance, integration) | Natural conversation |
+
+**Usage:**
+
+```typescript
+import { askUser, askUserQuick } from '@su-record/vibe/tools';
+
+// Quick helper for common scenarios
+const result = await askUserQuick.login('my-login-feature');
+console.log(result.content[0].text);
+
+// Custom categories
+const result = await askUser({
+  featureName: 'user-dashboard',
+  categories: ['authentication', 'security', 'session', 'data_model'],
+  context: 'Building a user dashboard with role-based access',
+});
+```
+
+**Available categories:**
+- `authentication`: Auth methods, MFA
+- `security`: Password policy, rate limiting
+- `session`: Session expiry, concurrent login
+- `data_model`: User profile fields
+- `performance`: Response time targets
+- `integration`: External service integration
+
+**Example output:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📋 Requirements Confirmation
+Feature: login
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## 🔐 Authentication
+
+### 🔐 Q-AUTHENTICATION-001
+
+**Which authentication methods should be supported?**
+(Multiple selection allowed)
+
+1. **Email/Password** ✓
+2. **Google Social Login**
+3. **Apple Social Login**
+...
+
+**Required**
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Total 6 questions (Required: 4)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Response parsing:**
+
+```typescript
+import { parseUserResponse } from '@su-record/vibe/tools';
+
+// User responds: "1, 2, 4" (selected option numbers)
+const response = parseUserResponse(question, "1, 2, 4");
+// { questionId: "Q-AUTH-001", value: ["email_password", "social_google", "passkey"], timestamp: "..." }
+```
+
+**ultrawork mode:**
+- askUser is **skipped** in ultrawork mode
+- Uses default values from templates automatically
+
+### 2.5. Reference Documents via config.json (MANDATORY after tech stack confirmed)
+
+**🚨 CRITICAL: Read config.json references IMMEDIATELY after tech stack is confirmed**
+
+Reference documents are automatically generated in `config.json` based on the stack detected during `vibe init`:
+
+```json
+// .claude/vibe/config.json
+{
+  "language": "ko",
+  "stacks": [
+    { "type": "typescript-react", "path": "package.json" }
+  ],
+  "references": {
+    "rules": [
+      "~/.claude/vibe/rules/code-quality.md",
+      "~/.claude/vibe/rules/error-handling.md",
+      "~/.claude/vibe/rules/security.md"
+    ],
+    "languages": [
+      "~/.claude/vibe/languages/typescript-react.md"
+    ],
+    "templates": [
+      "~/.claude/vibe/templates/spec-template.md",
+      "~/.claude/vibe/templates/feature-template.md",
+      "~/.claude/vibe/templates/constitution-template.md"
+    ]
+  }
+}
+```
+
+**Workflow:**
+
+1. Read `.claude/vibe/config.json`
+2. Extract `references.languages[]` paths
+3. Read each language document for stack-specific guidelines
+
+**Example:**
+```bash
+# 1. Check references in config.json
+Read .claude/vibe/config.json
+
+# 2. Reference documents specified in references.languages
+Read ~/.claude/vibe/languages/typescript-react.md
+```
+
+**Important:**
+
+- No manual mapping needed - config.json contains all reference paths
+- `config.json.references` is automatically referenced when running `/vibe.run`
+- Not copied to project (referenced from global package)
+
+### 2.9 Research Cache Check (BEFORE step 3)
+
+Before spawning any research agents, check for a prior persisted dataset:
+
+```bash
+# Slug = kebab-case of the feature/topic, max 50 chars
+ls .claude/vibe/research/<slug>/paper.md 2>/dev/null
+```
+
+**If `paper.md` exists:**
+1. Read `.claude/vibe/research/<slug>/paper.md`
+2. Read `.claude/vibe/research/<slug>/awesome-list.md` (if present)
+3. Inject the **Findings**, **Recommendation**, and **Security considerations** sections verbatim into SPEC Context, prefixed with `> Source: .claude/vibe/research/<slug>/paper.md (cached {{FILE_MTIME}})`
+4. **Skip step 3** (parallel research) entirely — do not re-run GPT/Gemini/Claude agents
+5. Print: `✅ Research cache hit: <slug> (saved ~30s of LLM calls)`
+
+**Cache invalidation:**
+- User passes `--refresh-research` → delete dir, rerun step 3 from scratch
+- `paper.md` mtime older than 30 days → warn the user, ask to refresh or reuse
+- `stack` in `paper.md` frontmatter differs from current stack → auto-refresh
+
+**If `paper.md` does NOT exist:**
+Proceed to step 3. After step 3 completes, the synthesizer **must** write the 3 artifacts (see `parallel-research/orchestrator.md` Phase 5) so the next `/vibe.spec` run on this topic hits the cache.
+
+### 3. Parallel Research (v2.5.0) - MANDATORY AFTER requirements confirmed
+
+**🚨🚨🚨 ABSOLUTE RULES FOR RESEARCH PHASE 🚨🚨🚨**
+
+**STOP! Before doing ANY research, read this carefully:**
+
+1. **DO NOT** use Task tool to spawn research agents
+2. **DO NOT** use context7 MCP directly for research
+3. **DO NOT** use WebSearch tool directly for research
+4. **YOU MUST** use Bash tool to call llm-orchestrate.js directly
+
+**🚨🚨🚨 CRITICAL: NO FILE CREATION DURING RESEARCH 🚨🚨🚨**
+
+5. **DO NOT** create any files in project root during research
+6. **DO NOT** create SECURITY_*.md, RESEARCH_*.md, SUMMARY_*.md files
+7. **DO NOT** use Write tool during research phase
+8. **ALL research results** must be returned as text output only
+9. **Files are ONLY created** in Step 4 (SPEC) and Step 5 (Feature) in `.claude/vibe/` directory
+
+**When to trigger:**
+1. ✅ Feature type decided (e.g., "passkey authentication")
+2. ✅ Tech stack confirmed (e.g., "React + Supabase")
+3. ✅ Language guide copied (step 2.5)
+4. ✅ Core requirements collected
+
+**→ IMMEDIATELY run these 6 Bash commands IN PARALLEL (all at once):**
+
+**Step 0: Script path:**
+- `[LLM_SCRIPT]` = `{{VIBE_PATH}}/hooks/scripts/llm-orchestrate.js`
+
+**Run all 4 in PARALLEL (each as separate Bash tool call):**
+```bash
+# 1. GPT: Best practices (codex — code review & analysis)
+node "[LLM_SCRIPT]" gpt-codex orchestrate-json "Best practices for [FEATURE] with [STACK]. Focus: architecture patterns, code conventions. Return JSON: {patterns: [], antiPatterns: [], libraries: []}"
+
+# 2. GPT: Security (codex — code review & analysis)
+node "[LLM_SCRIPT]" gpt-codex orchestrate-json "Security vulnerabilities for [FEATURE] with [STACK]. Focus: CVE database, known exploits. Return JSON: {vulnerabilities: [], mitigations: [], checklist: []}"
+
+# 3. Gemini: Best practices
+node "[LLM_SCRIPT]" gemini orchestrate-json "Best practices for [FEATURE] with [STACK]. Focus: latest trends, framework updates. Return JSON: {patterns: [], antiPatterns: [], libraries: []}"
+
+# 4. Gemini: Security
+node "[LLM_SCRIPT]" gemini orchestrate-json "Security advisories for [FEATURE] with [STACK]. Focus: latest patches, recent incidents. Return JSON: {advisories: [], patches: [], incidents: []}"
+```
+
+**Concrete example - run all 4 in parallel:**
+```bash
+# GPT best practices (codex — code review & analysis)
+node "[LLM_SCRIPT]" gpt-codex orchestrate-json "Best practices for passkey authentication with React, Supabase. Focus: architecture patterns, code conventions. Return JSON: {patterns: [], antiPatterns: [], libraries: []}"
+
+# GPT security (codex — code review & analysis)
+node "[LLM_SCRIPT]" gpt-codex orchestrate-json "Security vulnerabilities for passkey authentication with React, Supabase. Focus: CVE database, known exploits. Return JSON: {vulnerabilities: [], mitigations: [], checklist: []}"
+
+# Gemini best practices
+node "[LLM_SCRIPT]" gemini orchestrate-json "Best practices for passkey authentication with React, Supabase. Focus: latest trends, framework updates. Return JSON: {patterns: [], antiPatterns: [], libraries: []}"
+
+# Gemini security
+node "[LLM_SCRIPT]" gemini orchestrate-json "Security advisories for passkey authentication with React, Supabase. Focus: latest patches, recent incidents. Return JSON: {advisories: [], patches: [], incidents: []}"
+```
+
+**ALSO run Claude research agents in parallel using Task tool:**
+
+| Claude Agent | Role | Source |
+|--------------|------|--------|
+| `best-practices-agent` | Best practices for [feature] + [stack] | WebSearch |
+| `framework-docs-agent` | Latest docs via context7 | context7 MCP |
+| `codebase-patterns-agent` | Similar patterns in existing codebase | Glob, Grep |
+| `security-advisory-agent` | Security advisories for [feature] | WebSearch |
+
+**Total: 4 GPT/Gemini calls (Bash) + 4 Claude agents (Task) = 8 parallel research tasks**
+
+**🚨 GPT/Gemini MUST be called via Bash with llm-orchestrate.js! 🚨**
+
+#### 3.0.1 Agent Teams — Research Collaboration
+
+> **Team definition**: See `agents/teams/research-team.md`
+> Settings: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` + `teammateMode: in-process` (`~/.claude/settings.json` global — auto-configured by postinstall)
+
+**Discussion results are reflected in the SPEC's Context section.**
+
+#### 3.1 Result Merge Rules
+
+| Area | Merge Strategy |
+|------|----------------|
+| Best Practices | Deduplicate, keep most detailed |
+| Security | ALL included (no dedup for safety) |
+| Libraries | Consensus recommendations |
+
+**IMPORTANT:**
+- ❌ DO NOT skip research step
+- ❌ DO NOT ask user "should I run research?"
+- ✅ ALWAYS run after requirements confirmed
+- ✅ Show "Running parallel research (Claude + GPT + Gemini)..." message
+- ✅ Include all agent + LLM results in SPEC Context
+- ✅ Run all 4 Bash LLM calls in parallel + 4 Task agents in parallel
+
+**Research results are reflected in SPEC's Context section.**
+
+### 3.2 UI/UX Design Intelligence (Auto-triggered)
+
+> **Condition**: Auto-executes when UI/UX keywords are present in the SPEC context (website, landing, dashboard, app, e-commerce, portfolio, SaaS, mobile app, web app, UI, UX, frontend, design)
+> **Disable**: Set `"uiUxAnalysis": false` in `.claude/vibe/config.json`
+
+**When UI/UX keywords are detected, run 3 agents sequentially in parallel with research:**
+
+```
+[Parallel Research] GPT + Gemini + Claude agents
+        ↓ (concurrent execution)
+[UI/UX Intelligence]
+  ① ui-industry-analyzer (Haiku) → industry analysis + design strategy
+        ↓
+  ②③ parallel execution:
+    ② ui-design-system-gen (Sonnet) → generate MASTER.md
+    ③ ui-layout-architect (Haiku) → layout design
+```
+
+**How to execute:**
+
+1. **① ui-industry-analyzer** — Run as Task(haiku) agent:
+```text
+Task(subagent_type="ui-industry-analyzer",
+  prompt="Analyze product: [USER_DESCRIPTION]. Use core_ui_search to detect category, style priority, color mood, typography mood. Save result to .claude/vibe/design-system/{project}/analysis-result.json")
+```
+
+2. **②③ parallel execution** — Using ①'s result as input:
+```text
+# ② Generate design system (Sonnet)
+Task(subagent_type="ui-design-system-gen",
+  prompt="Generate design system from analysis-result.json for project '{project}'. Use core_ui_search for style/color/typography, then core_ui_generate_design_system and core_ui_persist_design_system.")
+
+# ③ Layout design (Haiku) — parallel execution
+Task(subagent_type="ui-layout-architect",
+  prompt="Design layout from analysis-result.json for project '{project}'. Use core_ui_search for landing patterns and dashboard layout.")
+```
+
+3. **Inject results into SPEC Context:**
+```markdown
+### Design System (Auto-generated)
+- Category: {① category}
+- Style: {① style_priority}
+- MASTER.md: .claude/vibe/design-system/{project}/MASTER.md
+- Layout: {③ pattern + sections}
+```
+
+### 3.9 Persist Research Cache (AFTER research completes, BEFORE SPEC write)
+
+> The "no Write during research" rule from step 3 does **not** apply here — research is done; artifacts are safe to persist.
+
+After parallel research + UI/UX intelligence complete, before writing the SPEC, save the merged research to `.claude/vibe/research/<slug>/`:
+
+1. Compute slug: kebab-case of feature name, max 50 chars
+2. Write **three files** using templates from `parallel-research/templates/`:
+   - `.claude/vibe/research/<slug>/synthesis.md` — raw merged findings (all agent outputs)
+   - `.claude/vibe/research/<slug>/awesome-list.md` — curated links/repos/patterns (every entry needs a one-line "why"; drop entries without one)
+   - `.claude/vibe/research/<slug>/paper.md` — structured survey (Abstract → Background → Method → Findings → Recommendation → Security → References)
+3. Include a frontmatter header in `paper.md` with a `stack:` field so step 2.9 can detect stack drift
+4. If the directory already exists (user passed `--refresh-research`), overwrite
+
+This makes the next `/vibe.spec` (or future `/vibe.research`) invocation on the same topic hit the cache at step 2.9.
+
+### 4. Write SPEC Document (PTCF Structure)
+
+#### 4.0 Large Scope Detection & Auto-Split (MANDATORY)
+
+**🚨 CRITICAL: Automatically split SPEC when scope is large**
+
+**❌ DO NOT ask user for confirmation - auto-split silently**
+
+**Detection criteria (ANY triggers split):**
+
+| Criteria | Threshold |
+|----------|-----------|
+| Phases | 5+ phases |
+| Files to create | 15+ files |
+| Platforms | 2+ platforms |
+| Major features | 4+ distinct features |
+
+**Auto-split output (SPEC + Feature files must match):**
+
+```
+.claude/vibe/specs/{feature-name}/
+├── _index.md           # Master SPEC
+├── phase-1-setup.md
+├── phase-2-core.md
+└── ...
+
+.claude/vibe/features/{feature-name}/
+├── _index.feature      # Master Feature
+├── phase-1-setup.feature
+├── phase-2-core.feature
+└── ...
+```
+
+**🚨 CRITICAL: Each SPEC phase file MUST have a matching Feature file**
+
+**Master SPEC (`_index.md`):**
+
+```markdown
+# SPEC: {feature-name} (Master)
+
+## Overview
+- Total phases: N
+- Dependencies: [list]
+
+## Sub-SPECs
+
+| Order | SPEC File | Feature File | Status |
+|-------|-----------|--------------|--------|
+| 1 | phase-1-setup.md | phase-1-setup.feature | ⬜ |
+| 2 | phase-2-core.md | phase-2-core.feature | ⬜ |
+
+## Shared Context
+- Tech Stack: [all phases]
+- Constraints: [all phases]
+```
+
+**Master Feature (`_index.feature`):**
+
+```markdown
+# Feature: {feature-name} (Master)
+
+**Master SPEC**: `.claude/vibe/specs/{feature-name}/_index.md`
+
+## Sub-Features
+
+| Order | Feature File | SPEC File | Status |
+|-------|--------------|-----------|--------|
+| 1 | phase-1-setup.feature | phase-1-setup.md | ⬜ |
+| 2 | phase-2-core.feature | phase-2-core.md | ⬜ |
+
+## Overall User Story
+**As a** {user}
+**I want** {complete feature}
+**So that** {value}
+```
+
+**Small scope (default):**
+
+Create `.claude/vibe/specs/{feature-name}.md`:
+
+```markdown
+---
+status: pending
+currentPhase: 0
+totalPhases: 3
+createdAt: {ISO-timestamp}
+lastUpdated: {ISO-timestamp}
+---
+
+# SPEC: {feature-name}
+
+## Persona
+<role>
+Define AI role and expertise for implementation
+- Senior developer on the project
+- Follow existing code patterns
+- Write testable code
+</role>
+
+## Context
+<context>
+### Background
+- Why this feature is needed
+- Who will use it
+
+### Tech Stack
+- Backend: {technology}
+- Frontend: {technology}
+- Database: {technology}
+
+### Related Code
+- `src/xxx/`: Existing implementation to reference
+- `src/yyy/`: Files to modify
+
+### Design Reference
+- {Reference app/service}
+</context>
+
+## Task
+<task>
+### Phase 1: {phase-name}
+1. [ ] {specific task}
+   - File: `path/to/file`
+   - Verify: `command`
+2. [ ] {specific task}
+
+### Phase 2: {phase-name}
+1. [ ] {specific task}
+2. [ ] {specific task}
+
+### Phase 3: Testing and Verification
+1. [ ] Unit Tests
+2. [ ] Integration Tests
+</task>
+
+## Constraints
+<constraints>
+- Follow existing code patterns
+- Localize error messages
+- Separate configuration via environment variables
+- {other constraints}
+</constraints>
+
+## Output Format
+<output_format>
+### Files to Create
+- `path/to/new/file.ts`
+- `path/to/new/file.test.ts`
+
+### Files to Modify
+- `path/to/existing/file.ts`
+
+### Verification Commands
+- `npm test`
+- `npm run build`
+</output_format>
+
+## Acceptance Criteria
+<acceptance>
+- [ ] {verifiable criterion 1}
+- [ ] {verifiable criterion 2}
+- [ ] All tests pass
+- [ ] Build succeeds
+</acceptance>
+```
+
+### 5. Create Feature File (BDD) - Required
+
+**🚨 CRITICAL: Feature files MUST match SPEC file structure**
+
+| SPEC Structure | Feature Structure |
+|----------------|-------------------|
+| Single file (`{feature}.md`) | Single file (`{feature}.feature`) |
+| Split (`{feature}/_index.md` + phases) | Split (`{feature}/_index.feature` + phases) |
+
+#### 5.1 Single File (Small Scope)
+
+Create `.claude/vibe/features/{feature-name}.feature`:
+
+**Creation rules:**
+1. Convert each SPEC Acceptance Criteria → one Scenario
+2. Include Happy Path (normal case) + Edge Case (exception case)
+3. Follow Given-When-Then format
+
+```markdown
+# Feature: {feature-name}
+
+**SPEC**: `.claude/vibe/specs/{feature-name}.md`
+
+## User Story
+**As a** {user}
+**I want** {feature}
+**So that** {value}
+
+## Scenarios
+
+### Scenario 1: {Happy Path}
+\`\`\`gherkin
+Scenario: {title}
+  Given {precondition}
+  When {action}
+  Then {result}
+\`\`\`
+**Verification**: SPEC AC #1
+
+### Scenario 2: {Edge Case}
+...
+
+## Coverage
+| Scenario | SPEC AC | Status |
+|----------|---------|--------|
+| 1 | AC-1 | ⬜ |
+```
+
+#### 5.2 Split Files (Large Scope)
+
+When SPEC is split into phases, Feature files MUST also be split:
+
+```
+.claude/vibe/features/{feature-name}/
+├── _index.feature        # Master: links to all phase features
+├── phase-1-setup.feature # Scenarios for phase-1-setup.md
+├── phase-2-core.feature  # Scenarios for phase-2-core.md
+└── ...
+```
+
+**Phase Feature file structure:**
+
+```markdown
+# Feature: {feature-name} - Phase {N}: {phase-name}
+
+**SPEC**: `.claude/vibe/specs/{feature-name}/phase-{N}-{name}.md`
+**Master Feature**: `.claude/vibe/features/{feature-name}/_index.feature`
+
+## User Story (Phase Scope)
+**As a** {user}
+**I want** {phase-specific feature}
+**So that** {phase-specific value}
+
+## Scenarios
+
+### Scenario 1: {Phase Happy Path}
+...
+
+## Coverage
+| Scenario | SPEC AC | Status |
+|----------|---------|--------|
+| 1 | Phase {N} AC-1 | ⬜ |
+```
+
+### 6. Ambiguity Scan - Required
+
+After creating SPEC draft, **must perform systematic ambiguity check**.
+
+#### 6.1 Mandatory Check Categories
+
+| Category | Check Items | Red Flags |
+|----------|-------------|-----------|
+| **Functional Scope** | Missing features, unclear behavior | "etc.", "other", "if needed" |
+| **Data Model** | Undefined entities, relationships | Undefined types, missing fields |
+| **Non-Functional** | Performance, security requirements | Performance requirements without numbers |
+| **Edge Cases** | Boundary conditions, errors | 0 failure scenarios |
+| **Integration Points** | External APIs, contracts | API version/endpoint undefined |
+| **User Input** | Validation rules, limits | Input limits not specified |
+| **State Management** | State transitions, persistence | Missing state diagram |
+
+#### 6.2 Forbidden Ambiguous Terms
+
+If the following terms exist in SPEC, **clarification is mandatory**:
+
+| Forbidden Term | Replacement Method |
+|----------------|-------------------|
+| "appropriately", "properly" | Provide specific criteria (e.g., "within 3 seconds") |
+| "quickly", "rapidly" | Specify with numbers (e.g., "under 100ms") |
+| "various", "multiple" | List specific items |
+| "etc.", "other" | Specify complete list or limit scope |
+| "if needed", "depending on situation" | Specify conditions (e.g., "when credits < 10") |
+| "later", "in the future" | Explicitly exclude from current scope |
+
+#### 6.3 Check Process
+
+```
+1. Write SPEC draft
+      ↓
+2. Auto-scan for forbidden terms
+      ↓
+3. Review checklist by category
+      ↓
+4. List discovered ambiguities
+      ↓
+5. Auto-fixable items → Fix immediately
+   Needs user confirmation → Ask question
+      ↓
+6. Re-verify (max 2 rounds — remaining ambiguities → user confirmation or TODO)
+```
+
+#### 6.4 Auto-Fix for Common Ambiguities
+
+| Ambiguity Type | Auto-Fix Method |
+|----------------|-----------------|
+| Timeout undefined | Apply default 30 seconds |
+| Retry count undefined | Apply default 3 retries |
+| Pagination undefined | Apply default 20 items/page |
+| Input length undefined | Text 500 chars, password 8-64 chars |
+| File size undefined | Image 5MB, video 100MB |
+
+#### 6.5 Ambiguity Output Format
+
+```markdown
+## 🔍 Ambiguity Scan Results
+
+### Found Issues: 3
+
+#### 1. Functional Scope
+- ⚠️ "Login failure behavior" not defined
+  → **Auto-fix**: Apply 5-minute lockout after 3 failures
+- ⚠️ "Session expiration handling" unclear
+  → **Question**: Session expiration time? (30min/1hour/24hours)
+
+#### 2. Edge Cases
+- ⚠️ Concurrent login permission undefined
+  → **Question**: Allow concurrent login? (Y/N)
+
+### Auto-fixed: 1
+### Needs clarification: 2
+```
+
+### 7. Quality Validation (Self-Check)
+
+**Must perform self-quality check after SPEC completion**
+
+#### 7.1 Quality Checklist (Required Items)
+
+| Category | Check Item | Weight |
+|----------|------------|--------|
+| **Completeness** | All user flows included in Task | 15% |
+| **Completeness** | All ACs converted to Feature scenarios | 10% |
+| **Clarity** | No ambiguous terms (e.g., "appropriately", "quickly") | 10% |
+| **Clarity** | All numbers/limits specified (e.g., "max 500 chars") | 10% |
+| **Testability** | All ACs are auto-testable | 10% |
+| **Security** | Authentication/authorization requirements defined | 10% |
+| **Security** | Sensitive data handling method specified | 5% |
+| **Error Handling** | Major failure scenarios defined | 10% |
+| **Error Handling** | User error messages specified | 5% |
+| **Performance** | Response time/throughput targets specified | 5% |
+| **Edge Cases** | Boundary condition handling defined | 5% |
+| **Dependencies** | External systems/APIs specified | 5% |
+
+#### 7.2 Quality Score Calculation
+
+```
+Score = Σ(Check item met × Weight) / 100
+
+Grades:
+- 95-100: ✅ EXCELLENT - Ready to start implementation
+- 90-94:  ⚠️ GOOD - Minor improvements required before implementation
+- 80-89:  ⚠️ FAIR - Significant improvements required
+- 0-79:   ❌ POOR - Rewrite required
+```
+
+#### 7.3 Quality Gate (Auto-verification)
+
+**100 points required to complete SPEC draft. Loop until perfect — ask user if auto-fixer hits a wall.**
+
+```
+SPEC writing complete
+      ↓
+[Calculate Quality Score]
+      ↓
+Score < 100? → Show missing items → Auto-fix → Re-evaluate
+      ↓
+Stuck? (score == prev_score)
+  ├─ Interactive: ask user → fill values OR "proceed" OR "abort"
+  └─ ultrawork: record gaps as TODO → proceed
+      ↓
+Score == 100 (or user-approved) → SPEC Draft Complete → Handoff to vibe-spec-review skill
+```
+
+#### 7.4 Auto-Fix for Low Score
+
+If score is below 100, attempt automatic fixes:
+
+| Missing Item | Auto-Fix Method |
+|--------------|-----------------|
+| Missing AC | Auto-generate AC based on Task |
+| Numbers not specified | Apply project defaults (e.g., timeout 30s) |
+| Missing error handling | Add common error scenarios |
+| Missing performance targets | Apply industry standard criteria |
+
+### 8. SPEC Draft Complete - Handoff to Review
+
+**🚨 IMPORTANT: GPT/Gemini review is now a SEPARATE command**
+
+After SPEC draft is complete (score ≥ 95):
+
+**If `ultrawork` mode:**
+- ❌ DO NOT show handoff message
+- ❌ DO NOT ask for confirmation
+- ✅ Immediately load skill `vibe-spec-review` with feature `{feature-name}` (chain-next)
+- ✅ After review passes, immediately proceed to `/vibe.run "{feature-name}" ultrawork`
+
+**If normal mode:**
+Output the handoff message:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ SPEC DRAFT COMPLETE: {feature-name}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 SPEC: .claude/vibe/specs/{feature-name}.md
+📋 Feature: .claude/vibe/features/{feature-name}.feature
+📊 Quality Score: {score}/100
+⏱️ Started: {start_time}
+⏱️ Completed: {getCurrentTime result}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚠️ NEXT STEP: Run SPEC review (vibe-spec-review skill)
+
+Option 1 (same session):
+  Load skill `vibe-spec-review` with feature `{feature-name}`
+  (or natural language: "spec review")
+
+Option 2 (recommended for large context):
+  /new → /vibe.spec "{feature-name}"
+  (Smart Resume will start from Phase 4)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Tip:** New session recommended when context > 50% to ensure review accuracy
+
+## Output (MANDATORY File Creation)
+
+**🚨 CRITICAL: Files MUST be created in these EXACT paths. NO exceptions.**
+
+### Small Scope (Single File)
+
+| File | Path | When |
+|------|------|------|
+| SPEC | `.claude/vibe/specs/{feature-name}.md` | After quality validation (Step 7) |
+| Feature | `.claude/vibe/features/{feature-name}.feature` | Immediately after SPEC |
+
+### Large Scope (Split Files)
+
+| File | Path | When |
+|------|------|------|
+| Master SPEC | `.claude/vibe/specs/{feature-name}/_index.md` | After quality validation |
+| Phase SPEC | `.claude/vibe/specs/{feature-name}/phase-{N}-{name}.md` | Per phase |
+| Master Feature | `.claude/vibe/features/{feature-name}/_index.feature` | After Master SPEC |
+| Phase Feature | `.claude/vibe/features/{feature-name}/phase-{N}-{name}.feature` | Per phase SPEC |
+
+**❌ FORBIDDEN:**
+
+- Creating files in project root (e.g., `feature-name.md`)
+- Creating files outside `.claude/vibe/` directory
+- Skipping file creation
+- Using different file names than feature-name
+- Creating split SPEC without matching split Feature files
+
+**✅ REQUIRED:**
+
+- Use Write tool to create files
+- Verify directories exist (create if needed)
+- Confirm file creation in response
+- **Each SPEC file must have a matching Feature file**
+
+### File Creation Template
+
+**Single file:**
+```
+1. Write .claude/vibe/specs/{feature-name}.md
+2. Write .claude/vibe/features/{feature-name}.feature
+3. Confirm: "✅ Created: specs/{feature-name}.md + features/{feature-name}.feature"
+```
+
+**Split files:**
+```
+1. Write .claude/vibe/specs/{feature-name}/_index.md
+2. Write .claude/vibe/specs/{feature-name}/phase-1-setup.md
+3. Write .claude/vibe/specs/{feature-name}/phase-2-core.md
+4. Write .claude/vibe/features/{feature-name}/_index.feature
+5. Write .claude/vibe/features/{feature-name}/phase-1-setup.feature
+6. Write .claude/vibe/features/{feature-name}/phase-2-core.feature
+7. Confirm: "✅ Created: {N} SPEC files + {N} Feature files"
+```
+
+## Example
+
+```
+User: /vibe.spec "brick-game"
+
+Claude:
+You're making a brick game! What style are you thinking of?
+
+1. Classic Breakout style
+2. Arkanoid (with power-up items)
+3. Custom style with special gameplay
+
+Feel free to describe in your own words.
+
+User: 1
+
+Claude: What platform will it run on?
+
+1. Web (browser)
+2. Mobile (iOS/Android)
+3. Desktop
+
+User: 1
+
+Claude:
+Here are tech stack suggestions for web game development:
+
+1. **Phaser.js** (Recommended) - Game framework with built-in physics engine
+2. **Canvas + JavaScript** - Lightweight with fine control
+3. **PixiJS + Matter.js** - High-performance rendering
+
+User: 1
+
+Claude: What design style?
+
+1. Retro pixel (Atari Breakout)
+2. Neon graphics (Arkanoid)
+3. Modern 3D effects
+
+User: 2
+
+[Conversation continues...]
+
+Claude: SPEC draft created. Running ambiguity scan.
+
+## 🔍 Ambiguity Scan Results
+
+### Functional Scope
+- ⚠️ Game over condition not defined (ball drop vs lives system)
+- ⚠️ Stage clear condition unclear
+
+### Edge Cases
+- ⚠️ Ball reflection angle when hitting paddle edge
+- ⚠️ Multiple brick collision handling
+
+Please clarify the above items.
+
+User: 3 lives, clear when all bricks destroyed, edge reflects at 45 degrees
+
+Claude: Thank you. SPEC has been refined.
+
+🔍 Re-check result: 0 ambiguities
+📊 Quality score: 92/100 (A)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🔍 SPEC REVIEW (Gemini)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📤 Sending SPEC...
+📝 Gemini feedback:
+  1. [Edge] Ball speed increase logic undefined
+  2. [Security] Need score manipulation prevention
+
+✅ 2 improvements auto-applied
+🔍 Re-verifying... ✅ Passed
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ SPEC Complete!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📄 .claude/vibe/specs/brick-game.md (PTCF structure)
+📄 .claude/vibe/features/brick-game.feature
+📊 Quality score: 100/100 ← Loop converged (no remaining gaps)
+```
+
+## Core Tools (Semantic Analysis & Memory)
+
+### Tool Invocation
+All tools are called via:
+```bash
+node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index.js').then(t => t.TOOL_NAME({...args}).then(r => console.log(r.content[0].text)))"
+```
+
+### Recommended Tools for SPEC Creation
+
+| Tool | Purpose | When to Use |
+|------|---------|-------------|
+| `findSymbol` | Find symbol definitions | Locate existing implementations to reference |
+| `findReferences` | Find all references | Understand how existing code is used |
+| `analyzeComplexity` | Code complexity analysis | Evaluate complexity of code to modify |
+| `saveMemory` | Save important decisions | Store confirmed requirements, design decisions |
+| `recallMemory` | Recall saved memory | Retrieve previous project decisions |
+
+### Example Tool Usage in SPEC Creation
+
+**1. Find existing auth implementation:**
+```bash
+node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index.js').then(t => t.findSymbol({symbolName: 'login', searchPath: 'src/'}).then(r => console.log(r.content[0].text)))"
+```
+
+**2. Save confirmed requirements:**
+```bash
+node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index.js').then(t => t.saveMemory({key: 'brick-game-requirements', value: 'Platform: Web, Stack: Phaser.js, Style: Neon', category: 'spec', projectPath: process.cwd()}).then(r => console.log(r.content[0].text)))"
+```
+
+**3. Recall previous decisions:**
+```bash
+node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index.js').then(t => t.recallMemory({key: 'brick-game-requirements', projectPath: process.cwd()}).then(r => console.log(r.content[0].text)))"
+```
+
+## Next Step
+
+```
+/vibe.run "brick-game"
+```
+
+---
+
+ARGUMENTS: $ARGUMENTS