@su-record/vibe 2.6.54 → 2.7.0

package/CLAUDE.md

@@ -3,12 +3,12 @@
 ## Project Nature
 
 > **This project is the source code for the `@su-record/vibe` npm package.**
-> Since users install this via `npm install`, all bug fixes and improvements MUST be made in **this project source** — not in installed locations (e.g., AppData).
+> All bug fixes and improvements MUST be made in **this project source** — not in installed locations.
 > Always modify files in this repository, never the installed copy.
 
 ## Philosophy
 
-> **core = Easy vibe coding + Minimum quality guaranteed**
+> **vibe = Easy vibe coding + Minimum quality guaranteed**
 
 | Principle | Description |
 |-----------|-------------|
@@ -16,36 +16,25 @@
 | **Minimum Quality Guaranteed** | Type safety, code quality, security — automatic baseline enforcement |
 | **Iterative Reasoning (Type 6)** | Don't delegate answers to AI — break down problems, ask questions, reason together |
 
-### How CORE Guarantees Quality
+### Quality Guardrails
 
 | Guardrail | Mechanism |
 |-----------|-----------|
 | Type Safety | Quality Gate — blocks `any` / `Any` / `@ts-ignore` |
-| Code Review | Claude Code native parallel review (13+ agents) |
+| Code Review | 13+ agent parallel review (security, performance, architecture, etc.) |
 | Completion Check | Ralph Loop — iterate until 100% complete (no scope reduction) |
-| Memory RAG | SQLite + FTS5 BM25 persistent memory — gets smarter over time |
-
-### User's Role (Iterative-Reasoning Type)
-
-Research shows that **breaking down problems and reasoning collaboratively (Type 6)** produces far better results than simply delegating to AI (Type 1).
-
-| Avoid | Do Instead |
-|-------|------------|
-| "Build login feature" | "Let's analyze the requirements for login" |
-| Accept AI output as-is | Ask "Is this approach correct?" |
-| Request complete code only | Review step by step |
+| Memory RAG | SQLite + FTS5 BM25 persistent memory |
+| Multi-LLM | GPT + Gemini cross-validation via ReviewRace |
 
 ## Code Quality Standards (Mandatory)
 
-Follow these standards when writing code. See `~/.claude/vibe/rules/` (global) for detailed rules.
-
 ### Core Principles
 
 - **Modify only requested scope** — Don't touch unrelated code
 - **Preserve existing style** — Follow project conventions
 - **Keep working code** — No unnecessary refactoring
-- **Edit existing files, never create new ones** — When fixing errors/bugs, ALWAYS modify the original file. NEVER create new files (wrappers, adapters, V2 copies) as a workaround. Fix the problem at its source.
-- **Respect user interrupts** — If user interrupts (Ctrl+C/Escape) and sends a new message, the previous task is CANCELLED. Do NOT resume or continue interrupted work. Respond ONLY to the new message.
+- **Edit existing files, never create new ones** — Fix the problem at its source
+- **Respect user interrupts** — If user interrupts (Ctrl+C/Escape), the previous task is CANCELLED. Respond ONLY to the new message
 
 ### Code Complexity Limits
 
@@ -63,12 +52,6 @@ Follow these standards when writing code. See `~/.claude/vibe/rules/` (global) f
 - No `@ts-ignore` — fix type issues at root
 - Explicit return types on all functions
 
-### Error Handling Required
-
-- try-catch or error state required
-- Loading state handling
-- User-friendly error messages
-
 ### Forbidden Patterns
 
 - No console.log in commits
@@ -76,18 +59,25 @@ Follow these standards when writing code. See `~/.claude/vibe/rules/` (global) f
 - No commented-out code
 - No incomplete code without TODO
 
-### Superpowers Integration (v0.2.0)
+## Configuration
 
-Four quality mechanisms inspired by the Superpowers project:
+### Global: `~/.vibe/config.json`
 
-| Feature | Description | Location |
-|---------|-------------|----------|
-| **Anti-Rationalization** | Blocks 6 categories of AI excuse patterns (SPEC skip, quality skip, verification skip, scope expansion, architecture avoidance, evidence avoidance) | `rules/principles/anti-rationalization.md` |
-| **Evidence Gate** | 5-step verification protocol (IDENTIFY → RUN → READ → VERIFY → CLAIM). No completion claims without evidence | `rules/quality/evidence-gate.md` + UltraQA |
-| **3-Fix Rule** | Same failure 3 times → switch to architecture question. User discussion required before fix #4 | UltraQA `architecture_question` status |
-| **Rule TDD** | 6 quality checks (example/both-sides/rationalization/edge/quality/comprehensive), 70+ pass threshold | RuleBuildSystem `pressureTestRule()` |
+All credentials, channel config, and model settings in one file (0o600 permissions).
 
-**Core principle:** Violating the letter of a rule is violating the spirit of a rule.
+```json
+{
+  "credentials": { "gpt": {}, "gemini": {} },
+  "channels": { "telegram": {}, "slack": {} },
+  "models": { "gpt": "gpt-5.2", "gemini": "gemini-3-pro-preview" }
+}
+```
+
+CLI commands: `vibe gpt key`, `vibe gemini auth`, `vibe telegram setup`, etc.
+
+### Project: `.claude/vibe/config.json`
+
+Project-specific settings (language, quality, stacks, details, references).
 
 ## Workflow
 
@@ -95,38 +85,26 @@ Four quality mechanisms inspired by the Superpowers project:
 /vibe.spec → /new → /vibe.spec.review → /vibe.run → /vibe.trace → (auto) code review → Done
 ```
 
-1. `/vibe.spec` — Write SPEC (requirements + research + draft)
-2. `/new` — Start new session (clean context)
-3. `/vibe.spec.review` — SPEC quality review
-4. `/vibe.run` — Implementation + parallel agent review
-5. **(auto)** — 13+ agent parallel review + P1/P2 auto-fix
-
-**All commands call `getCurrentTime` at start/end to display elapsed time.**
-
-## Plan Mode vs CORE
-
 | Task Size | Recommended |
 |-----------|-------------|
 | Simple changes (1-2 files) | Plan Mode |
 | Complex features (3+ files) | `/vibe.spec` |
 
-After `/vibe.analyze` or `/vibe.review` with dev request → **Ask user for workflow choice**
-
 ## ULTRAWORK Mode
 
-Include `ultrawork` or `ulw` keyword for maximum performance:
+Add `ultrawork` or `ulw` keyword:
 
 - Parallel sub-agent exploration (3+ concurrent)
 - Background agents + Phase pipelining
 - Boulder Loop (auto-continue until all Phases complete)
 - Auto-retry on error (max 3), Auto-save at 70%+ context
 
-## Commands
+## Commands (Slash)
 
 | Command | Description |
 |---------|-------------|
 | `/vibe.spec "name"` | Write SPEC (PTCF) + parallel research |
-| `/vibe.spec.review "name"` | SPEC quality review |
+| `/vibe.spec.review "name"` | SPEC quality review (GPT + Gemini 3-round) |
 | `/vibe.run "name"` | Execute implementation |
 | `/vibe.run "name" ultrawork` | Maximum performance mode |
 | `/vibe.verify "name"` | Verification against SPEC |
@@ -134,45 +112,38 @@ Include `ultrawork` or `ulw` keyword for maximum performance:
 | `/vibe.trace "name"` | Requirements traceability matrix |
 | `/vibe.reason "problem"` | Systematic reasoning |
 | `/vibe.analyze` | Project analysis |
-| `/vibe.utils --e2e` | E2E testing (Playwright) |
-| `/vibe.utils --diagram` | Generate diagrams |
-| `/vibe.utils --ui "desc"` | UI preview |
-| `/vibe.utils --continue` | Session restore |
-| `/vibe.voice` | Voice-to-coding command (Gemini audio) |
+| `/vibe.utils` | Utilities (--e2e, --diagram, --ui, --continue) |
+| `/vibe.voice` | Voice-to-coding (Gemini audio) |
 
 ## CLI Commands
 
 | Command | Description |
 |---------|-------------|
 | `vibe init [project]` | Project initialization |
-| `vibe setup` | Interactive setup wizard (LLM auth + channels) |
+| `vibe setup` | Interactive setup wizard |
 | `vibe update` | Update project configuration |
 | `vibe upgrade` | Upgrade to latest version |
 | `vibe remove` | Remove from project |
-| `vibe status` | Full status check (LLM, channels) |
+| `vibe status` | Full status check |
 | `vibe version` | Show version |
 | `vibe claude <cmd>` | Claude (key, status, logout) |
 | `vibe gpt <cmd>` | GPT (auth, key, status, logout, remove) |
 | `vibe gemini <cmd>` | Gemini (auth, key, import, status, logout, remove) |
 | `vibe telegram <cmd>` | Telegram (setup, chat, status) |
 | `vibe slack <cmd>` | Slack (setup, channel, status) |
+| `vibe env import [path]` | .env → ~/.vibe/config.json migration |
 
-## External Channels
+## External LLM Integration
 
-| Channel | Interface | Requirements |
-|---------|-----------|-------------|
-| Telegram | TelegramBot (polling) | `TELEGRAM_BOT_TOKEN` |
-| Slack | SlackBot (Socket Mode) | `SLACK_BOT_TOKEN`, `SLACK_APP_TOKEN` |
+- **GPT**: `vibe gpt auth` (OAuth) / `vibe gpt key` (API Key) — Responses API
+- **Gemini**: `vibe gemini auth` (OAuth) / `vibe gemini key` (API Key) — Gemini API
+- Auth priority: OAuth → API Key → Azure (GPT) / gemini-cli → OAuth → API Key (Gemini)
+- All credentials stored in `~/.vibe/config.json`
 
-### Channel Environment Variables
+## External Channels
 
-| Variable | Description |
-|----------|-------------|
-| `VIBE_TELEGRAM_ENABLED` | Enable Telegram channel |
-| `VIBE_SLACK_ENABLED` | Enable Slack channel |
-| `SLACK_BOT_TOKEN` | Slack bot token (xoxb-) |
-| `SLACK_APP_TOKEN` | Slack app-level token (xapp-) |
-| `SLACK_ALLOWED_CHANNELS` | Comma-separated allowed channel IDs |
+- **Telegram**: `vibe telegram setup <token>` — `~/.vibe/config.json` channels.telegram
+- **Slack**: `vibe slack setup <bot-token> <app-token>` — `~/.vibe/config.json` channels.slack
 
 ## Magic Keywords
 
@@ -184,232 +155,50 @@ Include `ultrawork` or `ulw` keyword for maximum performance:
 | `verify` | Strict verification mode |
 | `quick` | Fast mode, minimal verification |
 
-## PTCF Structure
-
-SPEC documents use: `<role>` `<context>` `<task>` `<constraints>` `<output_format>` `<acceptance>`
-
-## Built-in Tools (41+)
-
-### Memory & Session
-
-| Tool | Purpose |
-|------|---------|
-| `core_start_session` | Restore previous session context |
-| `core_auto_save_context` | Save current state |
-| `core_save_memory` | Save important decisions |
-| `core_recall_memory` | Recall saved memories |
-| `core_list_memories` | List all memories |
-| `core_search_memories` | Search memories |
-| `core_search_memories_advanced` | Advanced memory search |
-| `core_link_memories` | Link related memories |
-| `core_get_memory_graph` | Visualize memory graph |
-| `core_create_memory_timeline` | Create memory timeline |
-| `core_restore_session_context` | Restore session context |
-| `core_prioritize_memory` | Prioritize memory items |
-
-### Semantic & Quality
-
-| Tool | Purpose |
-|------|---------|
-| `core_find_symbol` | Find symbol definitions |
-| `core_find_references` | Find references |
-| `core_analyze_dependency_graph` | Analyze dependency graph |
-| `core_analyze_complexity` | Analyze complexity |
-| `core_validate_code_quality` | Validate quality |
-| `core_check_coupling_cohesion` | Check coupling/cohesion |
-| `core_suggest_improvements` | Suggest improvements |
-| `core_apply_quality_rules` | Apply quality rules |
-
-### UI & Utility
-
-| Tool | Purpose |
-|------|---------|
-| `core_preview_ui_ascii` | UI preview in ASCII |
-| `core_get_current_time` | Get current time |
-
-### Channel Tools
-
-| Tool | Purpose |
-|------|---------|
-| `send_slack` | Send message to Slack channel |
-
-### SPEC & Testing
-
-| Tool | Purpose |
-|------|---------|
-| `core_spec_generator` | Generate SPEC documents |
-| `core_prd_parser` | Parse PRD documents |
-| `core_traceability_matrix` | Generate traceability matrix |
-| `core_e2e_test_generator` | Generate E2E tests |
-
-### Session RAG
-
-Structured session context storage/retrieval system. SQLite + FTS5 BM25 hybrid search.
-
-| Tool | Purpose |
-|------|---------|
-| `save_session_item` | Store Decision/Constraint/Goal/Evidence |
-| `retrieve_session_context` | Hybrid search (BM25 + recency + priority) |
-| `manage_goals` | Goal lifecycle management (list/update/complete) |
-
-**4 Entity Types:**
-
-| Entity | Description | Key Fields |
-|--------|-------------|------------|
-| Decision | User-confirmed decisions | title, rationale, alternatives, impact, priority |
-| Constraint | Explicit constraints | title, type (technical/business/resource/quality), severity |
-| Goal | Current goal stack (hierarchical) | title, status, priority, progressPercent, successCriteria |
-| Evidence | Verification/test results | title, type (test/build/lint/coverage), status, metrics |
-
-**Auto-injection:** When `start_session` is called, active Goals, critical Constraints, and recent Decisions are automatically included in session context.
-
-```typescript
-import { saveSessionItem, retrieveSessionContext, manageGoals } from '@su-record/vibe/tools';
-
-// Save decision
-await saveSessionItem({ itemType: 'decision', title: 'Use Vitest', rationale: 'Fast and modern' });
-
-// Save constraint
-await saveSessionItem({ itemType: 'constraint', title: 'No vector DB', type: 'technical', severity: 'high' });
-
-// Save goal
-await saveSessionItem({ itemType: 'goal', title: 'Implement Session RAG', priority: 2 });
-
-// Search context
-await retrieveSessionContext({ query: 'testing' });
-
-// Manage goals
-await manageGoals({ action: 'list' });
-await manageGoals({ action: 'update', goalId: 1, progressPercent: 80 });
-await manageGoals({ action: 'complete', goalId: 1 });
-```
-
-## External LLM Integration (v0.1.0)
-
-GPT and Gemini external LLM support via `llm-orchestrate.js` hook script.
-
-### Core Modules
-
-| Module | Purpose |
-|--------|---------|
-| `SmartRouter` | Task-type-specific LLM selection + fallback chain |
-| `LLMCluster` | Parallel multi-LLM calls (GPT + Gemini) |
-| `AgentRegistry` | SQLite-based agent execution tracking (WAL mode) |
+## Agents (49)
 
-### External LLM Usage
+### Main (19)
 
-| Role | Provider | Method |
-|------|----------|--------|
-| SPEC review (cross-validation) | GPT + Gemini | `llm-orchestrate.js` via Bash |
-| Race code review | GPT + Gemini | `llm-orchestrate.js` via Bash |
-| Research (best practices, security) | GPT + Gemini | `llm-orchestrate.js` via Bash |
-| User questions | GPT / Gemini | Hook auto-handles |
+Explorer (high/medium/low), Implementer (high/medium/low), Architect (high/medium/low), Searcher, Tester, Simplifier, Refactor Cleaner, Build Error Resolver, Compounder, Diagrammer, E2E Tester, UI Previewer, Junior Mentor
 
-### GPT Integration
+### Review (12)
 
-- Auth: `vibe gpt auth` (OAuth) or `vibe gpt key <key>` (API Key)
-- OAuth endpoint: `https://chatgpt.com/backend-api/codex/responses`
-- API Key endpoint: `https://api.openai.com/v1/responses`
+security, performance, architecture, complexity, simplicity, data-integrity, test-coverage, git-history, typescript, python, rails, react
 
-### Gemini Integration
+### Research (4)
 
-- Auth: `vibe gemini auth` (OAuth) or `vibe gemini key <key>` (API Key)
-- Used for: research, review, image analysis, STT
+best-practices, framework-docs, codebase-patterns, security-advisory
 
-## Agents
+### UI/UX (8)
 
-### Main Agents (18)
+ui-industry-analyzer, ui-design-system-gen, ui-layout-architect, ui-stack-implementer, ui-dataviz-advisor, ux-compliance-reviewer, ui-a11y-auditor, ui-antipattern-detector
 
-- **Explorer** (high/medium/low) — Codebase exploration
-- **Implementer** (high/medium/low) — Code implementation
-- **Architect** (high/medium/low) — Architecture design
-- **Searcher** — Code search
-- **Tester** — Test generation
-- **Simplifier** — Code simplification
-- **Refactor Cleaner** — Refactoring cleanup
-- **Build Error Resolver** — Build error fixing
-- **Compounder** — Multi-step compound tasks
-- **Diagrammer** — Diagram generation
-- **E2E Tester** — E2E test execution
-- **UI Previewer** — UI preview
+### Planning (2), QA (2), Docs (2)
 
-### Review Agents (12)
+requirements-analyst, ux-advisor, edge-case-finder, acceptance-tester, api-documenter, changelog-writer
 
-security, performance, architecture, complexity, simplicity, data-integrity, test-coverage, git-history, typescript, python, rails, react → `agents/review/`
+### Agent Teams (9)
 
-### Research Agents (4)
+Lite, Dev (ULTRAWORK), Research, Review Debate, SPEC Debate, Debug, Security, Migration, Fullstack
 
-best-practices, framework-docs, codebase-patterns, security-advisory → `agents/research/`
-
-### UI/UX Agents (8)
-
-CSV data-driven design intelligence. BM25 search engine auto-generates industry-specific design strategies from 24 CSV files.
-
-| Phase | Agent | Model | Role |
-|-------|-------|-------|------|
-| SPEC | 1. ui-industry-analyzer | Haiku | Industry analysis + design strategy |
-| SPEC | 2. ui-design-system-gen | Sonnet | MASTER.md design system generation |
-| SPEC | 3. ui-layout-architect | Haiku | Page structure/sections/CTA design |
-| RUN | 4. ui-stack-implementer | Haiku | Framework-specific component guide |
-| RUN | 5. ui-dataviz-advisor | Haiku | Chart/visualization library recommendations |
-| REVIEW | 6. ux-compliance-reviewer | Haiku | UX guideline compliance verification |
-| REVIEW | 7. ui-a11y-auditor | Haiku | WCAG 2.1 AA accessibility audit |
-| REVIEW | 8. ui-antipattern-detector | Haiku | UI anti-pattern detection |
-
-**Execution flow**: 1→2,3 (SPEC, supervisor-worker) → 4,5 (RUN, before Phase start) → 6,7,8 (REVIEW, on UI file changes)
-
-**Disable**: Set `"uiUxAnalysis": false` in `.claude/vibe/config.json`
-
-**MCP tools**: `core_ui_search`, `core_ui_stack_search`, `core_ui_generate_design_system`, `core_ui_persist_design_system`
-
-**Data**: `~/.claude/vibe/ui-ux-data/` (11 domain CSVs + 13 stack CSVs)
-
-→ `agents/ui/`
-
-### Planning Agents (2)
-
-requirements-analyst, ux-advisor → `agents/planning/`
-
-### QA Agents (2)
-
-edge-case-finder, acceptance-tester → `agents/qa/`
-
-### Docs Agents (2)
-
-api-documenter, changelog-writer → `agents/docs/`
-
-### Mentor Agent (1)
-
-junior-mentor — Junior developer mentor with EXPLANATION.md generation
-
-### Agent Teams (9 teams)
-
-> Agents form teams to collaborate via shared task lists with mutual feedback.
-> Setting: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` (`.claude/settings.local.json` env, postinstall auto-configured)
+## Built-in Tools (41+)
 
-| Team | Workflow | Members | Activation |
-|------|----------|---------|------------|
-| Lite Team | `/vibe.run` normal | architect, implementer, tester | 3+ scenarios, normal mode |
-| Dev Team | `/vibe.run` ULTRAWORK | architect, implementer, tester, security-reviewer | ULTRAWORK or complexity 20+ |
-| Research Team | `/vibe.spec` Step 3 | best-practices, security-advisory, codebase-patterns, framework-docs | Always in /vibe.spec |
-| Review Debate Team | `/vibe.review` Phase 4.5 | security, architecture, performance, simplicity | P1/P2 issues 2+ |
-| SPEC Debate Team | `/vibe.spec.review` Step 3.5 | security, architecture, performance, simplicity | P1/P2 issues 2+ |
-| Debug Team | `/vibe.run` failure | architect, implementer, tester | Build/test failure 3x+ |
-| Security Team | `/vibe.run` security | security, data-integrity, security-advisory, tester | auth/payment file changes |
-| Migration Team | `/vibe.run` migration | architect, implementer, tester, build-error-resolver | Major dependency version change |
-| Fullstack Team | `/vibe.run` fullstack | architect, implementer-backend, implementer-frontend, tester | SPEC has frontend + backend |
+- **Memory & Session** (21): save/recall/search/link memories, session RAG (save_session_item, retrieve_session_context, manage_goals)
+- **Code Quality** (8): find_symbol, find_references, analyze_complexity, validate_code_quality, etc.
+- **SPEC & Testing** (9): spec_generator, traceability_matrix, e2e_test_generator, etc.
+- **UI & Utility** (3+): preview_ui_ascii, get_current_time, send_slack
 
 ## Hooks System
 
 | Event | Hooks |
 |-------|-------|
 | SessionStart | `session-start.js` |
-| PreToolUse (Bash/Edit/Write) | `pre-tool-guard.js` |
-| PostToolUse (Write/Edit) | `post-edit.js`, `code-check.js`, `post-tool-verify.js` |
+| PreToolUse | `pre-tool-guard.js` |
+| PostToolUse | `post-edit.js`, `code-check.js`, `post-tool-verify.js` |
 | UserPromptSubmit | `prompt-dispatcher.js`, `skill-injector.js`, `keyword-detector.js`, `hud-status.js` |
-| Notification (context 80/90/95%) | `context-save.js` |
+| Notification | `context-save.js` (80/90/95%) |
 
-**Additional hooks:** `code-review.js`, `llm-orchestrate.js`, `recall.js`, `complexity.js`, `compound.js`, `skill-requirements.js`, `autonomy-controller.js`, `evolution-engine.js`, `hud-multiline.js`, `sentinel-guard.js`, `stop-notify.js`
+Additional: `code-review.js`, `llm-orchestrate.js`, `recall.js`, `complexity.js`, `compound.js`, `stop-notify.js`
 
 ## Language Support (25 frameworks)
 
@@ -422,22 +211,8 @@ junior-mentor — Junior developer mentor with EXPLANATION.md generation
 
 ## Context Management
 
-### Model Selection
-
-- **Exploration/Search**: Haiku
-- **Implementation**: Sonnet
-- **Architecture**: Opus
-
-### At 70%+ Context
-
-- Do NOT use `/compact` (information loss risk)
-- Use `save_memory` → `/new` for new session
-- Restore with `/vibe.utils --continue`
-
-## Documentation Guidelines
-
-- Avoid ASCII boxes → Use Mermaid diagrams, Markdown tables, or indented lists
-- Flowcharts → Mermaid | Structure → Indented lists | Comparisons → Tables
+- **Exploration/Search**: Haiku | **Implementation**: Sonnet | **Architecture**: Opus
+- At 70%+ context: Use `save_memory` → `/new` → `/vibe.utils --continue`
 
 ## Git Commit Rules