@su-record/vibe 2.5.21 → 2.6.1

package/CLAUDE.md

@@ -40,7 +40,9 @@ Follow these standards when writing code. See `~/.claude/vibe/rules/` (global) f
 ## Workflow
 
 ```
-/vibe.spec → /new → /vibe.spec.review → /vibe.run → (auto) code review → ✅ Done
+/vibe.spec → /new → /vibe.spec.review → /vibe.run → /vibe.trace → (auto) code review → ✅ Done
+                                                         ↑
+                                                Coverage check (v2.6)
 ```
 
 **Flow:**
@@ -117,7 +119,157 @@ Include `ultrawork` or `ulw` keyword to activate maximum performance mode:
 | `/vibe.utils --ui "description"` | UI preview |
 | `/vibe.utils --continue` | **Session restore** (load previous context) |
 
-## New Features (v2.5.15)
+## New Features (v2.6.x)
+
+### Structured User Questions (v2.6.1)
+
+Use `askUser` tool for critical requirements that must not be missed:
+
+```typescript
+import { askUser, askUserQuick } from '@su-record/vibe/tools';
+
+// Quick helper for login features
+const result = await askUserQuick.login('my-login');
+
+// Custom categories
+const result = await askUser({
+  featureName: 'dashboard',
+  categories: ['authentication', 'security', 'session'],
+});
+```
+
+**Available categories:**
+| Category | Questions |
+|----------|-----------|
+| `authentication` | Auth method, MFA |
+| `security` | Password policy, rate limit |
+| `session` | Duration, concurrent login |
+| `data_model` | Profile fields |
+| `performance` | Response time targets |
+| `integration` | External services |
+
+**When to use:**
+- ✅ Critical: auth, security, session → `askUser`
+- ❌ Exploratory: scope, style → Natural conversation
+- ⚠️ ultrawork mode: skipped (uses defaults)
+
+### Fire-and-Forget Background Manager
+
+Launch background agents without blocking, with automatic concurrency control:
+
+```typescript
+import { launch, poll, cancel, getStats } from '@su-record/vibe/orchestrator';
+
+// Fire-and-forget - returns immediately (<100ms)
+const { taskId } = launch({
+  prompt: 'Analyze codebase',
+  agentName: 'analyzer',
+  model: 'claude-sonnet-4-5',
+});
+
+// Poll for result later
+const result = await poll(taskId);
+
+// Check queue stats
+const stats = getStats();
+```
+
+**Concurrency limits:**
+
+| Model | Limit |
+|-------|-------|
+| claude-opus-4 | 3 |
+| claude-sonnet-4-5 | 5 |
+| claude-haiku-* | 8 |
+
+**Error types:**
+- `QueueOverflowError`: Queue at capacity (100 tasks max)
+- `TaskTimeoutError`: Task exceeded 3 minutes
+- `PipelineTimeoutError`: Pipeline exceeded 10 minutes
+- `AgentExecutionError`: Agent execution failed
+
+### Phase Pipelining
+
+Remove wait time between phases with background preparation:
+
+```typescript
+import { PhasePipeline, createStage, createUltraworkPipeline } from '@su-record/vibe/orchestrator';
+
+const pipeline = createUltraworkPipeline('my-feature', [
+  createStage('Setup', async (ctx) => { /* ... */ }),
+  createStage('Core', async (ctx) => { /* ... */ }),
+  createStage('Test', async (ctx) => { /* ... */ }),
+]);
+
+const result = await pipeline.execute();
+// Next phase preparation happens during current phase execution!
+```
+
+### PRD-to-SPEC Automation
+
+Generate SPEC documents from PRD (Product Requirements Document):
+
+```typescript
+import { parsePRD, generateSpecFromPRD } from '@su-record/vibe/tools';
+
+// Parse PRD document
+const prd = parsePRD(prdContent, 'login');
+
+// Generate SPEC
+const spec = generateSpecFromPRD(prd, {
+  techStack: { frontend: 'React', backend: 'Node.js' },
+});
+```
+
+**Supported PRD formats:**
+- Markdown with `## Requirements` sections
+- YAML frontmatter with `requirements:` array
+- Mixed format
+
+### Requirements Traceability Matrix (/vibe.trace)
+
+Track requirements coverage across SPEC → Feature → Test:
+
+```bash
+/vibe.trace "login"           # Generate RTM
+/vibe.trace "login" --html    # HTML output
+/vibe.trace "login" --save    # Save to file
+```
+
+```typescript
+import { generateTraceabilityMatrix, formatMatrixAsMarkdown } from '@su-record/vibe/tools';
+
+const matrix = generateTraceabilityMatrix('login');
+const markdown = formatMatrixAsMarkdown(matrix);
+```
+
+**Coverage levels:**
+| Level | Meaning |
+|-------|---------|
+| Full (✅) | SPEC + Feature + Test all mapped |
+| Partial (⚠️) | Missing one or more mappings |
+| None (❌) | Only in SPEC |
+
+### SPEC Versioning
+
+Git-integrated version control for SPEC documents:
+
+```typescript
+import { bumpSpecVersion, createGitTag, generateChangelog } from '@su-record/vibe/tools';
+
+// Bump version (major/minor/patch)
+const newVersion = bumpSpecVersion(specPath, 'minor', [
+  { type: 'added', description: 'New login feature' },
+]);
+
+// Create git tag
+createGitTag('login', newVersion.version);
+
+// Generate changelog
+const changelog = generateChangelog(versionHistory);
+```
+
+## Previous Features (v2.5.15)
 
 ### Rule Build System
 

package/README.md

@@ -39,6 +39,7 @@ vibe init
 | `/vibe.run "feature"` | Execute implementation |
 | `/vibe.run "feature" ultrawork` | Maximum performance mode |
 | `/vibe.verify "feature"` | BDD verification |
+| `/vibe.trace "feature"` | Requirements traceability matrix (v2.6) |
 | `/vibe.review` | 13+ agent parallel review |
 | `/vibe.analyze` | Code analysis |
 | `/vibe.reason "problem"` | Systematic reasoning |
@@ -47,13 +48,19 @@ vibe init
 ## Workflow
 
 ```
-/vibe.spec → /vibe.run → /vibe.verify → /vibe.review
+/vibe.spec → /vibe.run → /vibe.trace → /vibe.verify → /vibe.review
+                              ↑
+                     Coverage check (v2.6)
 ```
 
 ## Key Features
 
 | Feature | Description |
 |---------|-------------|
+| **Fire-and-Forget Agents (v2.6)** | Non-blocking background execution with instant handle return |
+| **Phase Pipelining (v2.6)** | Prepare next phase during current execution |
+| **PRD-to-SPEC Automation (v2.6)** | Auto-generate SPEC from PRD documents |
+| **Traceability Matrix (v2.6)** | REQ → SPEC → Feature → Test coverage tracking |
 | **Multi-LLM Research (v2.5)** | Claude + GPT + Gemini 3-way validation during SPEC research |
 | **Multi-model orchestration** | Claude + GPT-5.2 + Gemini 3 Pro |
 | **13+ parallel review agents** | Security, performance, architecture |
@@ -61,7 +68,7 @@ vibe init
 | **Large SPEC auto-split** | 5+ phases auto-split into phase files |
 | **BDD auto verification** | Given/When/Then scenario verification |
 | **ULTRAWORK mode** | One keyword enables all optimizations |
-| **25 built-in tools** | Code analysis, memory management, quality validation |
+| **30+ built-in tools** | Code analysis, memory management, quality validation |
 | **Auto context management** | 80%+ auto-save, session restore |
 | **23 language presets** | TypeScript, Python, Go, Rust, Swift, Kotlin, C#, Ruby, Dart, GDScript |
 
@@ -76,11 +83,134 @@ Enable maximum performance with `ultrawork` or `ulw`:
 
 **Enabled features:**
 - Parallel subagent exploration (3+ concurrent)
+- **Background agents** (v2.6) - Prepare next phase during implementation
+- **Phase pipelining** (v2.6) - Zero wait time between phases
 - Boulder Loop (auto-progress until all scenarios complete)
 - Auto-retry on errors (max 3)
 - Continuous execution without phase confirmation
 - Auto-save at 80%+ context
 
+## Fire-and-Forget Background Manager (v2.6)
+
+Non-blocking task execution with instant response:
+
+```typescript
+import { launch, poll, getStats } from '@su-record/vibe/orchestrator';
+
+// Fire-and-forget: returns immediately (<100ms)
+const { taskId } = launch({
+  prompt: 'Analyze codebase security',
+  agentName: 'security-agent',
+  model: 'claude-sonnet-4-5'
+});
+
+// Poll for result later
+const result = await poll(taskId);
+
+// Check queue stats
+const stats = getStats();
+```
+
+**Concurrency limits:**
+
+| Model  | Concurrent Limit |
+|--------|------------------|
+| Opus   | 3                |
+| Sonnet | 5                |
+| Haiku  | 8                |
+
+**Queue features:**
+
+- Bounded queue (max 100 tasks)
+- Per-model rate limiting
+- Task timeout: 180s individual, 10min pipeline
+- Automatic cleanup (24h TTL)
+
+## Phase Pipelining (v2.6)
+
+Prepare next phase while current phase executes:
+
+```
+Phase N execution     │ Background: Phase N+1 preparation
+──────────────────────┼──────────────────────────────────
+[Implementing...]     │ [Analyzing files for next phase]
+[Testing...]          │ [Pre-generating test cases]
+[Complete]            │ [Ready to start immediately!]
+                      ↓
+Phase N+1 starts with ZERO wait time
+```
+
+**Speed comparison:**
+
+| Mode                      | 5 Phases Total |
+|---------------------------|----------------|
+| Sequential                | ~10min         |
+| Parallel Exploration      | ~7.5min        |
+| **ULTRAWORK + Pipeline**  | **~5min**      |
+
+## PRD-to-SPEC Automation (v2.6)
+
+Auto-generate SPEC from PRD documents:
+
+```typescript
+import { parsePRD } from '@su-record/vibe/tools';
+
+// Parse PRD (supports Markdown, YAML frontmatter)
+const prd = parsePRD(prdContent, 'login-feature');
+
+// Extracted requirements with auto-generated IDs
+// REQ-login-001, REQ-login-002, ...
+```
+
+**Requirement ID System:**
+
+- Format: `REQ-{feature}-{number}`
+- Auto-deduplication
+- Priority inference from keywords (must, should, nice-to-have)
+
+## Requirements Traceability Matrix (v2.6)
+
+Track coverage from requirements to tests:
+
+```bash
+/vibe.trace "feature-name"  # Generate RTM
+```
+
+**RTM tracks:**
+
+```
+REQ-login-001 → SPEC Phase 1 → Feature Scenario 1 → login.test.ts
+REQ-login-002 → SPEC Phase 2 → Feature Scenario 3 → auth.test.ts
+```
+
+**Coverage report:**
+
+- Requirements coverage %
+- Missing implementations
+- Untested features
+- Export: Markdown, HTML
+
+## SPEC Versioning (v2.6)
+
+Automatic version management for SPEC documents:
+
+```typescript
+import { bumpVersion, generateChangelog } from '@su-record/vibe/tools';
+
+// Auto-bump version on SPEC changes
+await bumpVersion('feature-name', 'minor');
+
+// Generate changelog
+await generateChangelog('feature-name');
+```
+
+**Features:**
+
+- Semantic versioning (major.minor.patch)
+- Git tag integration
+- Automatic changelog generation
+- Baseline tagging for releases
+
 ## Multi-model Orchestration
 
 **Hook-based automatic routing** - Keywords in your prompt trigger the right LLM automatically:

package/commands/vibe.run.md

@@ -162,7 +162,7 @@ Like Sisyphus rolling the boulder, ULTRAWORK **keeps going until done**:
 
 **Problem**: AI often claims "complete" when implementation is partial.
 
-**Solution**: Self-referential completion verification with iteration tracking.
+**Solution**: RTM-based automated coverage verification with iteration tracking.
 
 ```
 ┌─────────────────────────────────────────────────────────────────┐
@@ -171,50 +171,69 @@ Like Sisyphus rolling the boulder, ULTRAWORK **keeps going until done**:
 │   After ALL phases complete:                                     │
 │                                                                  │
 │   ┌──────────────────────────────────────────────────────────┐  │
-│   │  COMPLETION VERIFICATION [Iteration {{ITER}}/{{MAX}}]     │  │
+│   │  RTM COVERAGE VERIFICATION [Iteration {{ITER}}/{{MAX}}]   │  │
 │   │                                                           │  │
-│   │  Compare ORIGINAL REQUEST vs IMPLEMENTATION:              │  │
+│   │  Generate RTM via vibe tools:                             │  │
+│   │  → generateTraceabilityMatrix("{feature-name}")           │  │
 │   │                                                           │  │
-│   │  □ All SPEC requirements implemented?                     │  │
-│   │  □ All acceptance criteria passing?                       │  │
-│   │  □ All scenarios in Feature file complete?                │  │
+│   │  Coverage Metrics (automated):                            │  │
+│   │  □ Requirements coverage: {coveragePercent}%              │  │
+│   │  □ SPEC → Feature mapping: {featureCovered}/{total}       │  │
+│   │  □ Feature → Test mapping: {testCovered}/{total}          │  │
 │   │  □ Build successful?                                      │  │
 │   │  □ Tests passing?                                         │  │
-│   │  □ No TODO/FIXME left unaddressed?                        │  │
-│   │  □ No partial implementations?                            │  │
 │   │                                                           │  │
-│   │  MISSING: [List any gaps]                                 │  │
+│   │  UNCOVERED: {uncoveredRequirements[]}                     │  │
 │   └──────────────────────────────────────────────────────────┘  │
 │                              │                                   │
 │                   ┌──────────┴──────────┐                       │
-│                   │   100% Complete?    │                       │
+│                   │  Coverage ≥ 95%?    │                       │
 │                   └──────────┬──────────┘                       │
 │                       │              │                          │
 │                      NO            YES                          │
 │                       │              │                          │
 │                       ↓              ↓                          │
 │              ┌────────────────┐  ┌────────────────┐             │
-│              │ IDENTIFY GAPS  │  │ ✅ TRULY DONE  │             │
-│              │ + FIX THEM     │  │                │             │
-│              │ (no scope      │  │ Report final   │             │
-│              │  reduction!)   │  │ completion     │             │
+│              │ IMPLEMENT      │  │ ✅ TRULY DONE  │             │
+│              │ UNCOVERED      │  │                │             │
+│              │ REQUIREMENTS   │  │ Report final   │             │
+│              │ (auto-extract) │  │ RTM coverage   │             │
 │              └───────┬────────┘  └────────────────┘             │
 │                      │                                          │
-│                      └──────────→ [Back to Phase]               │
+│                      └──────────→ [Re-generate RTM]             │
 │                                                                  │
 │   MAX_ITERATIONS: 5 (prevent infinite loops)                    │
+│   COVERAGE_THRESHOLD: 95% (quality gate)                        │
 │   ZERO TOLERANCE for scope reduction                            │
 └─────────────────────────────────────────────────────────────────┘
 ```
 
+**Ralph Loop with RTM:**
+
+```bash
+# Generate RTM for coverage verification
+node -e "import('@su-record/vibe/tools').then(t => t.generateTraceabilityMatrix('{feature-name}', {projectPath: process.cwd()}).then(r => console.log(JSON.stringify(r, null, 2))))"
+```
+
+**RTM provides automated metrics:**
+
+| Metric | Description |
+|--------|-------------|
+| `totalRequirements` | Total REQ-* items in SPEC |
+| `specCovered` | Requirements with SPEC mapping |
+| `featureCovered` | Requirements with Feature scenarios |
+| `testCovered` | Requirements with test files |
+| `coveragePercent` | Overall coverage percentage |
+| `uncoveredRequirements` | List of missing REQ-* IDs |
+
 **Ralph Loop Rules:**
 
 | Rule | Description |
 |------|-------------|
 | **No Scope Reduction** | Never say "simplified" or "basic version" - implement FULL request |
 | **Iteration Tracking** | Display `[{{ITER}}/{{MAX}}]` to show progress |
-| **Explicit Gap List** | List EVERY missing item before fixing |
-| **Self-Referential** | Compare against ORIGINAL request, not current state |
+| **RTM-Based Gap List** | Use `uncoveredRequirements` array - no manual comparison |
+| **Coverage Threshold** | Must reach 95% coverage to complete |
 | **Max Iterations** | Stop at 5 iterations (report remaining gaps) |
 
 **Ralph Loop Output Format:**
@@ -224,49 +243,55 @@ Like Sisyphus rolling the boulder, ULTRAWORK **keeps going until done**:
 🔄 RALPH VERIFICATION [Iteration 1/5]
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-Original Request: "Full login page with form, validation, API integration"
+📊 RTM Coverage Report: login
+
+Requirements Traceability:
+  Total Requirements: 9
+  SPEC Covered: 9/9 (100%)
+  Feature Covered: 5/9 (55%)
+  Test Covered: 4/9 (44%)
 
-Checking against SPEC requirements:
-  ✅ Login form UI - implemented
-  ✅ Email validation - implemented
-  ✅ Password validation - implemented
-  ❌ Remember me checkbox - NOT FOUND
-  ❌ Forgot password link - NOT FOUND
-  ✅ API integration - implemented
-  ❌ Loading state - NOT FOUND
-  ❌ Error toast notifications - NOT FOUND
+  ✅ REQ-login-001: Login form UI → Scenario 1 → login.test.ts
+  ✅ REQ-login-002: Email validation → Scenario 2 → validation.test.ts
+  ✅ REQ-login-003: Password validation → Scenario 2 → validation.test.ts
+  ❌ REQ-login-004: Remember me checkbox → NOT IMPLEMENTED
+  ❌ REQ-login-005: Forgot password link → NOT IMPLEMENTED
+  ✅ REQ-login-006: API integration → Scenario 3 → api.test.ts
+  ❌ REQ-login-007: Loading state → NOT IMPLEMENTED
+  ❌ REQ-login-008: Error toast → NOT IMPLEMENTED
+  ✅ REQ-login-009: Session storage → Scenario 4 → (no test)
 
-Completion: 5/9 (55%)
+Overall Coverage: 55% ⚠️ BELOW 95% THRESHOLD
 
-GAPS IDENTIFIED:
-  1. Remember me checkbox (SPEC line 24)
-  2. Forgot password link (SPEC line 28)
-  3. Loading state during API call (SPEC line 35)
-  4. Error toast notifications (SPEC line 42)
+UNCOVERED REQUIREMENTS (auto-extracted from RTM):
+  1. REQ-login-004: Remember me checkbox
+  2. REQ-login-005: Forgot password link
+  3. REQ-login-007: Loading state
+  4. REQ-login-008: Error toast notifications
 
-⚠️ NOT COMPLETE - Continuing implementation...
+⚠️ NOT COMPLETE - Implementing uncovered requirements...
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 🔄 RALPH VERIFICATION [Iteration 2/5]
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-Checking against SPEC requirements:
-  ✅ Login form UI - implemented
-  ✅ Email validation - implemented
-  ✅ Password validation - implemented
-  ✅ Remember me checkbox - implemented
-  ✅ Forgot password link - implemented
-  ✅ API integration - implemented
-  ✅ Loading state - implemented
-  ✅ Error toast notifications - implemented
+📊 RTM Coverage Report: login
 
-Completion: 9/9 (100%)
+Requirements Traceability:
+  Total Requirements: 9
+  SPEC Covered: 9/9 (100%)
+  Feature Covered: 9/9 (100%)
+  Test Covered: 9/9 (100%)
+
+Overall Coverage: 100% ✅ ABOVE 95% THRESHOLD
 
 Build: ✅ Passed
 Tests: ✅ 12/12 Passed
 Type Check: ✅ No errors
 
 ✅ RALPH VERIFIED COMPLETE!
+
+📄 RTM saved: .claude/vibe/rtm/login-rtm.md
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 

package/commands/vibe.spec.md

@@ -218,6 +218,89 @@ $ git checkout -b feature/login-page
 - 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`: 인증 방식, MFA
+- `security`: 비밀번호 정책, 속도 제한
+- `session`: 세션 만료, 동시 로그인
+- `data_model`: 사용자 프로필 필드
+- `performance`: 응답 시간 목표
+- `integration`: 외부 서비스 연동
+
+**Example output:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📋 요구사항 확인
+Feature: login
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## 🔐 인증
+
+### 🔐 Q-AUTHENTICATION-001
+
+**어떤 인증 방식을 지원할까요?**
+(복수 선택 가능)
+
+1. **이메일/비밀번호** ✓
+2. **Google 소셜 로그인**
+3. **Apple 소셜 로그인**
+...
+
+**필수**
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+총 6개 질문 (필수: 4개)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Response parsing:**
+
+```typescript
+import { parseUserResponse } from '@su-record/vibe/tools';
+
+// User responds: "1, 2, 4" (선택한 옵션 번호)
+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**