@su-record/vibe 3.2.6 → 3.2.8

package/skills/vibe.design-review/SKILL.md

@@ -10,6 +10,13 @@ priority: 50
 
 # Design Review — Technical Audit + UX Critique
 
+## Done Criteria
+
+- [ ] review report가 지정 출력 경로에 존재한다.
+- [ ] 모든 finding에 severity와 파일·행 또는 화면 근거가 있다.
+- [ ] accessibility, responsive, performance, theming 검사가 판정되어 있다.
+- [ ] 발견된 P1 개수와 최종 판정이 보고서에 기록되어 있다.
+
 Read-only design quality review. Two modes selected by the first argument. No code modifications — report only.
 
 ## Usage

package/skills/vibe.design-teach/SKILL.md

@@ -1,184 +1,11 @@
 ---
 name: vibe.design-teach
+description: Compatibility alias for gathering project design context. Use for design-teach, design-setup, or design-context requests.
 user-invocable: false
 invocation: [auto]
 tier: standard
-description: "Gather and store project design context — target audience, brand personality, aesthetic direction, constraints. Used by other design-* skills. Use when design-teach, design-setup, design-context."
 triggers: [design-teach, design-setup, design-context]
 priority: 50
 ---
 
-# Design Teach — Project Design Context Gathering
-
-Collect project-specific design context so all design-* skills produce tailored, brand-aware results. Saves to `.vibe/design-context.json`.
-
-## Usage
-
-```
-/design-teach                  # Interactive context gathering
-/design-teach --update         # Update existing context
-```
-
-## Process
-
-### Step 1: Auto-Explore Codebase
-
-Before asking questions, automatically gather existing signals:
-
-| Signal | Where to Look |
-|--------|---------------|
-| CSS variables / tokens | `*.css`, `tailwind.config.*`, `theme.*` |
-| Color palette | Existing color definitions, brand assets |
-| Typography | Font imports, font-family declarations |
-| Component library | `package.json` dependencies (MUI, Chakra, shadcn, etc.) |
-| Design system | `.vibe/design-system/*/MASTER.md` |
-| Existing context | `.vibe/design-context.json` (if updating) |
-
-### Step 2: Ask Clarifying Questions
-
-Present findings from Step 1, then ask what's missing:
-
-**1. Target Audience**
-- Who are the primary users? (developers, consumers, enterprise, internal)
-- Technical sophistication? (tech-savvy, general public, mixed)
-- Usage context? (desktop office, mobile on-the-go, both)
-
-**2. Brand Personality**
-- How should the product feel? (professional, playful, minimal, bold, warm)
-- Reference products with similar feel? (e.g., "Linear-like", "Notion-like")
-- Any brand guidelines or style guide URL?
-
-**3. Aesthetic Direction**
-- Visual density preference? (spacious, balanced, dense)
-- Color mood? (warm, cool, neutral, vibrant)
-- Typography mood? (modern sans, classic serif, monospace-technical)
-
-**4. Constraints**
-- Accessibility requirements? (WCAG AA, AAA, specific needs)
-- Supported devices? (desktop-only, mobile-first, responsive)
-- Dark mode required?
-- Performance budget? (target LCP, bundle size limits)
-
-### Step 3: Save Context
-
-Write gathered context to `.vibe/design-context.json` using the Write tool.
-
-**Schema (v1):**
-
-```json
-{
-  "$schema": "design-context-v1",
-  "createdAt": "ISO-8601",
-  "updatedAt": "ISO-8601",
-  "audience": {
-    "primary": "Description of target users",
-    "context": "Usage environment (desktop/mobile/mixed)",
-    "expertise": "Technical level (beginner/intermediate/expert)"
-  },
-  "brand": {
-    "personality": ["3-5 adjectives"],
-    "tone": "formal | casual | playful | professional (guideline, free text allowed)",
-    "existingAssets": "Path to existing brand guidelines (optional)"
-  },
-  "aesthetic": {
-    "style": "minimal | bold | elegant | playful | corporate (guideline, free text allowed)",
-    "colorMood": "warm | cool | neutral | vibrant | muted (guideline, free text allowed)",
-    "typographyMood": "modern | classic | geometric | humanist (guideline, free text allowed)",
-    "references": ["Reference site/app URLs"]
-  },
-  "constraints": {
-    "accessibility": "AA | AAA",
-    "performance": "core-web-vitals | balanced | unlimited",
-    "browsers": ["chrome", "safari", "firefox", "edge"],
-    "devices": ["mobile", "tablet", "desktop"]
-  },
-  "detectedStack": {
-    "framework": "Detected framework",
-    "componentLibrary": "Detected component library",
-    "styling": "Detected styling approach",
-    "fonts": ["Detected fonts"]
-  }
-}
-```
-
-> **Note**: `tone`, `style`, `colorMood`, `typographyMood` values are suggestions, not closed enums. Users can enter free text.
-
-> **Size limit**: design-context.json should not exceed 10KB. The `references` array is capped at 5 items.
-
-### Step 4: Rerun Semantics
-
-When `/design-teach` is run again and `design-context.json` already exists:
-
-1. Read the existing file with the Read tool
-2. **Show existing values as defaults** for each question ("Current: professional, clean — do you want to change this?")
-3. User replies "keep" or leaves blank → that field is preserved
-4. New value entered → only that field is replaced (**field-level replacement, not merge**)
-5. `createdAt` is always preserved; only `updatedAt` is updated to the current time
-
-### Step 5: Other Skills Reference This Context
-
-Each design-* skill does the following when it runs:
-
-```
-1. Read `.vibe/design-context.json`
-2. File not found → print "Run /design-teach first for better results" → continue with defaults
-3. Parse failure (invalid JSON) → warn "design-context.json parse failed" + continue with defaults → recommend re-running /design-teach
-4. Success → apply context to analysis criteria
-```
-
-## Design Workflow Integration
-
-Design skills are integrated into 3 phases of the vibe workflow:
-
-```
-SPEC Phase:
-  ① Check design-context.json (recommend /design-teach if missing)
-  ② design-system-gen (industry analysis → design system → layout)
-
-REVIEW Phase:
-  ③ /design-review audit (technical quality check)
-  ④ /design-review critique (UX review)
-  ⑤ design-reviewer (AI slop + anti-pattern detection)
-
-PRE-SHIP Phase:
-  ⑥ /design-refine normalize (design system alignment)
-  ⑦ /design-refine polish (final pass)
-```
-
-## How Other Skills Use This
-
-| Skill | Context Usage |
-|-------|---------------|
-| `/design-review audit` | Weight findings by audience constraints (a11y level, devices) |
-| `/design-review critique` | Adjust persona priorities by target audience |
-| `/design-refine polish` | Apply brand-appropriate micro-interactions |
-| `/design-refine normalize` | Use detected token system for replacement mapping |
-| `/design-refine distill` | Preserve brand-expressive elements based on personality |
-
-## Output Format
-
-```markdown
-## Design Context: {project}
-
-### Auto-Detected
-- Framework: Next.js 15
-- Styling: Tailwind CSS + shadcn/ui
-- Fonts: Inter (heading), Inter (body)
-- Tokens: 24 CSS variables found
-
-### User Provided
-- Audience: B2B SaaS, mixed technical level
-- Brand: Professional, clean (like Linear)
-- Density: Balanced
-- A11y: WCAG AA
-- Dark mode: Required
-
-### Saved
-✅ .vibe/design-context.json updated
-```
-
-## Important
-
-- **Non-destructive**: Only creates/updates the context file. No code changes.
-- **Incremental**: Running `--update` preserves existing answers, only asks about gaps.
-- **Foundation**: Run this first before other design-* skills for best results.
+Load `vibe.design` with `init --from=interview`, preserving update intent and all supplied context.

package/skills/vibe.devlog/SKILL.md

@@ -2,12 +2,19 @@
 name: vibe.devlog
 invocation: [auto]
 tier: standard
-description: "Auto-generate devlog posts from git commit history. Triggers every N commits, writes markdown to configured target repo."
+description: "Use when accumulated git commits must be turned into a devlog post or the configured N-commit publication threshold is reached."
 triggers: [devlog, 개발일지, dev log, devlog 작성, 개발일지 작성]
 priority: 60
 ---
 # Devlog Auto-Generator
 
+## Done Criteria
+
+- [ ] 처리한 commit 범위가 산출물에 기록되어 있다.
+- [ ] devlog Markdown이 설정된 대상 경로에 존재한다.
+- [ ] 이미 처리한 commit이 중복 포함되지 않았다.
+- [ ] 설정된 frontmatter 필드가 모두 채워져 있다.
+
 Analyzes git commit history to automatically generate development logs and saves them as posts to the configured blog repository.
 
 ## Config
@@ -46,9 +53,12 @@ Analyzes git commit history to automatically generate development logs and saves
 
 ## Trigger Modes
 
-### 1. Auto (post-commit hook)
+### 1. Auto (lifecycle acceleration)
 
-The `devlog-gen.js` hook checks the counter on every commit, and when it reaches `interval`, generates a devlog via `llm-orchestrate.js`.
+When lifecycle hooks are available, `devlog-gen.js` may check the counter after
+each commit and invoke `llm-orchestrate.js`. Hooks are acceleration only: before
+declaring the devlog workflow complete, explicitly count commits since the last
+devlog and run the same generation step when the count reaches `interval`.
 
 ### 2. Manual
 
@@ -126,14 +136,7 @@ The number is automatically determined as the last existing file number + 1.
 
 ### Step 5: (Optional) Auto Push
 
-If `autoPush: true`:
-
-```bash
-cd {targetRepo}
-git add {targetDir}/{prefix}-{NNNN}.md
-git commit -m "post: Add {prefix} #{NNNN}"
-git push
-```
+If `autoPush: true`, read `references/auto-push.md` and require normal external-state confirmation. Calls with `autoPush: false` do not load it.
 
 ## Rules
 

package/skills/vibe.devlog/references/auto-push.md

@@ -0,0 +1,10 @@
+# Optional Devlog Auto-Push
+
+Load only when `devlog.autoPush` is `true`. External push still requires confirmation.
+
+```bash
+cd {targetRepo}
+git add {targetDir}/{prefix}-{NNNN}.md
+git commit -m "post: Add {prefix} #{NNNN}"
+git push
+```

package/skills/vibe.docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vibe.docs
-description: Generate project documentation — README, architecture docs, user guide, release notes, agent instructions, diagrams, codemaps
+description: Use when README, guides, architecture, release notes, agent instructions, diagrams, or codemaps must be generated or synchronized with the actual codebase.
 argument-hint: "readme, guide, arch, release, agent, diagram, or codemaps"
 user-invocable: true
 ---
@@ -45,207 +45,21 @@ Generate or update project documentation by analyzing the actual codebase.
 
 ## Subcommands
 
-### `/vibe.docs readme` — README Generation
+## Subcommands (선택된 하나만 로드)
 
-Analyze the codebase and generate a complete README.md:
+한 번의 호출은 서브커맨드 **하나만** 실행한다. 해당 reference 하나만 읽고 나머지 6개는 읽지 않는다.
 
-1. **Detect project nature**: Read package.json, CLAUDE.md, existing README
-2. **Extract key info**: Tech stack, installation, usage, API surface
-3. **Generate sections**:
-
-```markdown
-# Project Name
-> One-line description from package.json
-
-## What is this?
-[2-3 sentences explaining the problem and solution]
-
-## Quick Start
-[Installation + minimal usage example]
-
-## Features
-[Auto-detected from codebase — exported functions, CLI commands, API endpoints]
-
-## Architecture
-[High-level module diagram if 5+ source directories]
-
-## Configuration
-[Detected config files and their purposes]
-
-## Development
-[Build, test, lint commands from package.json scripts]
-
-## License
-```
-
-**Analysis approach:**
-```
-Read: package.json → name, description, scripts, dependencies
-Glob: src/**/*.ts → module structure
-Grep: pattern="export (function|class|const)" → public API surface
-Grep: pattern="(app|router)\.(get|post|put|delete)" → API endpoints
-Read: CLAUDE.md → project conventions
-```
-
-### `/vibe.docs guide` — User Guide
-
-Generate a step-by-step user guide:
-
-1. **Installation**: Detect package manager, prerequisites
-2. **Configuration**: Find all config files, document each option
-3. **Usage**: Extract CLI commands or API usage patterns
-4. **FAQ**: Common issues from error handling patterns
-5. **Troubleshooting**: Known edge cases from test files
-
-Output: `docs/GUIDE.md`
-
-**Analysis approach:**
-```
-Read: package.json → bin, scripts, peerDependencies
-Glob: src/cli/commands/*.ts → CLI command list
-Grep: pattern="throw new|Error\(" → common error scenarios
-Grep: pattern="(process\.env|config)\.\w+" → configuration options
-```
-
-### `/vibe.docs arch` — Architecture Documentation
-
-Generate architecture overview with diagrams:
-
-1. **Module map**: Directory structure → responsibility mapping
-2. **Dependency graph**: Import analysis → Mermaid diagram
-3. **Data flow**: Entry points → processing → output
-4. **Key decisions**: Extract from CLAUDE.md and code comments
-
-Output: `docs/ARCHITECTURE.md`
-
-**Mermaid diagram generation:**
-```
-Glob: src/**/ → module list
-Grep: pattern="^import .+ from" → dependency edges
-Read: CLAUDE.md → architecture notes
-
-Generate:
-graph TD
-    CLI[CLI Commands] --> Core[Core Logic]
-    Core --> Infra[Infrastructure]
-    Infra --> DB[(Database)]
-    Infra --> API[External APIs]
-```
-
-### `/vibe.docs agent` — Agent Instruction Files (CLAUDE.md / AGENTS.md)
-
-**CLI ↔ file mapping:**
-
-| CLI | File | Support |
+| 서브커맨드 | 산출물 | 본문 |
 |---|---|---|
-| Claude Code | `CLAUDE.md` | 100% (Primary) |
-| Codex | `AGENTS.md` | 100% (Primary) |
-| Antigravity CLI | `GEMINI.md` | 100% |
-
-Cursor is not supported — do not generate or check Cursor-specific context files.
-
-**Source of truth:**
-- **`CLAUDE.md` is the content SSOT.** Always edit it first; `AGENTS.md` is a regenerated derivative.
-- Behavioral block: `skills/vibe.docs/templates/behavioral-principles.md` (4 Karpathy principles, wrapped in `<!-- VIBE-BEHAVIORAL:START/END -->` markers).
-
-**Procedure (applies to both creation and modification):**
-
-1. **Detect state** — check which of `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` exist in project root. **`CLAUDE.md` is always the SSOT**; if missing, create it first (never derive from AGENTS.md).
-2. **For `AGENTS.md`**:
-   - **If missing** → create by cloning `CLAUDE.md` + applying CLI substitution (below).
-   - **If exists** → regenerate from current `CLAUDE.md` + substitution, preserving user-specific additions outside the VIBE block.
-3. **For `GEMINI.md`**:
-   - **If missing** → create by cloning `CLAUDE.md` + applying Antigravity substitution.
-   - **If exists** → regenerate from current `CLAUDE.md` + substitution, preserving user-specific additions outside the VIBE block.
-4. **CLI substitution for `AGENTS.md`** (Codex): `Claude Code` → `Codex` · `~/.claude/` → `~/.codex/` · `.claude/` → `.codex/` · `CLAUDE.md` → `AGENTS.md`. `CLAUDE.md` itself gets no substitution.
-5. **CLI substitution for `GEMINI.md`** (Antigravity): `Claude Code` → `Antigravity CLI` · `~/.claude/` → `~/.gemini/` · `.claude/` → `.gemini/` · `CLAUDE.md` → `GEMINI.md`.
-6. **Validate every touched file (whether newly created or modified)** via the `agents-md` skill — see validation block below. **Never write or save without running this step.**
-7. Report per file: created / updated / skipped / validation warnings.
+| `readme` | README.md | `references/readme.md` |
+| `guide` | 사용자 가이드 | `references/guide.md` |
+| `arch` | 아키텍처 문서 | `references/arch.md` |
+| `agent` | CLAUDE.md / AGENTS.md | `references/agent.md` |
+| `release` | 릴리스 노트 / CHANGELOG | `references/release.md` |
+| `diagram` | 다이어그램 | `references/diagram.md` |
+| `codemaps` | 코드맵 | `references/codemaps.md` |
 
-**Idempotent:** Re-running re-syncs the behavioral block and re-applies substitutions without duplication.
-
-**Mandatory validation (every create & every update) — Load skill `vibe.agents-md`:**
-
-- Size target 60–150 lines (Optimal). Warn at 200+, force split/trim at 300+.
-- 4-question check per line (outside `VIBE-BEHAVIORAL` block):
-  - Would the agent make a mistake without this? (No → delete)
-  - Needed every session? (No → move to SPEC/plan)
-  - Can a linter/hook replace it? (Yes → move)
-  - Discoverable from code? (Yes → delete)
-- Lost-in-the-Middle: critical rules at top, frequently-violated rules at bottom.
-- Addy Osmani test: "Can the agent discover this by reading the code?" → Yes = delete.
-- Strip tech-stack name-drops already stated in `package.json`.
-
-Report line ranges to trim per file. Do not auto-delete; surface findings for user approval before finalizing.
-
-**When to run:**
-- After `vibe init` / `vibe update` if `CLAUDE.md` or `AGENTS.md` is missing or out of sync.
-- After upgrading `@su-record/vibe` when the behavioral template changes.
-- Whenever the SSOT file is edited — re-sync `AGENTS.md`.
-- User explicitly asks to refresh agent instructions.
-
-### `/vibe.docs release` — Release Notes
-
-Generate release notes from git history:
-
-1. **Collect**: `git log` since last tag
-2. **Classify**: feat/fix/refactor/docs/chore from commit messages
-3. **Group**: By category with breaking changes highlighted
-4. **Format**: Semantic versioning suggestion
-
-Output: `RELEASE_NOTES.md` or append to `CHANGELOG.md`
-
-**Output format:**
-```markdown
-## [x.y.z] - YYYY-MM-DD
-
-### Breaking Changes
-- ...
-
-### Features
-- feat: description (#PR)
-
-### Bug Fixes
-- fix: description (#PR)
-
-### Other
-- refactor/docs/chore items
-```
-
-### `/vibe.docs diagram` — Diagram Generation
-
-Generate Mermaid diagrams for architecture, ERD, flowchart, or sequence
-visualization directly (native capability — no dedicated agent). Ground the
-diagram in sources first: folder structure and imports for architecture;
-`models/`, `migrations/`, `schema.*`, ORM definitions for ERDs; the real
-branch/return structure of the code for flowcharts.
-
-**Options:**
-- `/vibe.docs diagram` (default): Architecture overview
-- `/vibe.docs diagram --er`: Entity-Relationship Diagram
-- `/vibe.docs diagram --flow`: Flowchart
-- `/vibe.docs diagram --seq`: Sequence Diagram
-
-> Read `references/diagram-spec.md` for the full output conventions (Mermaid syntax per diagram type, save location, accuracy constraints).
-
-**Example:**
-```
-/vibe.docs diagram --er
-```
-
-### `/vibe.docs codemaps` — Codemaps Generation
-
-Generate auto-documentation from codebase structure directly (native
-capability — no dedicated agent).
-
-**Output Location:** `docs/CODEMAPS/`
-
-> Read `references/codemaps-output.md` for the full generated-files tree, per-file contents, and tools used.
-
-**Example:**
-```
-/vibe.docs codemaps
-```
+서브커맨드 없이 호출되면 무엇을 생성할지 사용자에게 묻는다 — 전부 생성하지 않는다.
 
 ## Pipeline Integration
 
@@ -290,3 +104,18 @@ Before finalizing any document:
 - [ ] Links and paths are valid
 - [ ] No placeholder text remaining
 - [ ] Consistent with project language (Korean/English)
+
+## Done Criteria
+
+- [ ] The requested document exists at its specified path.
+- [ ] Example commands, paths, and identifiers match the repository.
+- [ ] No placeholder or unverified feature claim remains.
+- [ ] Internal links and file paths resolve to real targets.
+- [ ] The document preserves the project's existing language.
+
+## 체인 의존 (reference 안에서 호출되는 스킬)
+
+reference 로 내려간 절차가 다른 스킬을 체인 호출한다. **설치 무결성 검사가 추적할 수 있도록 여기에 선언한다** —
+선언이 없으면 그 스킬이 미설치여도 아무도 잡지 못한다.
+
+- Load skill `vibe.agents-md` — `references/agent.md` 단계에서 호출

package/skills/vibe.docs/references/agent.md

@@ -0,0 +1,55 @@
+# /vibe.docs agent — Agent Instruction Files (CLAUDE.md / AGENTS.md)
+
+> vibe.docs SKILL.md 의 서브커맨드 표에서 **`agent` 가 선택됐을 때만** 로드한다.
+
+### `/vibe.docs agent` — Agent Instruction Files (CLAUDE.md / AGENTS.md)
+
+**CLI ↔ file mapping:**
+
+| CLI | File | Support |
+|---|---|---|
+| Claude Code | `CLAUDE.md` | 100% (Primary) |
+| Codex | `AGENTS.md` | 100% (Primary) |
+| Antigravity CLI | `GEMINI.md` | 100% |
+
+Cursor is not supported — do not generate or check Cursor-specific context files.
+
+**Source of truth:**
+- **`CLAUDE.md` is the content SSOT.** Always edit it first; `AGENTS.md` is a regenerated derivative.
+- Behavioral block: `skills/vibe.docs/templates/behavioral-principles.md` (4 Karpathy principles, wrapped in `<!-- VIBE-BEHAVIORAL:START/END -->` markers).
+
+**Procedure (applies to both creation and modification):**
+
+1. **Detect state** — check which of `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` exist in project root. **`CLAUDE.md` is always the SSOT**; if missing, create it first (never derive from AGENTS.md).
+2. **For `AGENTS.md`**:
+   - **If missing** → create by cloning `CLAUDE.md` + applying CLI substitution (below).
+   - **If exists** → regenerate from current `CLAUDE.md` + substitution, preserving user-specific additions outside the VIBE block.
+3. **For `GEMINI.md`**:
+   - **If missing** → create by cloning `CLAUDE.md` + applying Antigravity substitution.
+   - **If exists** → regenerate from current `CLAUDE.md` + substitution, preserving user-specific additions outside the VIBE block.
+4. **CLI substitution for `AGENTS.md`** (Codex): `Claude Code` → `Codex` · `~/.claude/` → `~/.codex/` · `.claude/` → `.codex/` · `CLAUDE.md` → `AGENTS.md`. `CLAUDE.md` itself gets no substitution.
+5. **CLI substitution for `GEMINI.md`** (Antigravity): `Claude Code` → `Antigravity CLI` · `~/.claude/` → `~/.gemini/` · `.claude/` → `.gemini/` · `CLAUDE.md` → `GEMINI.md`.
+6. **Validate every touched file (whether newly created or modified)** via the `agents-md` skill — see validation block below. **Never write or save without running this step.**
+7. Report per file: created / updated / skipped / validation warnings.
+
+**Idempotent:** Re-running re-syncs the behavioral block and re-applies substitutions without duplication.
+
+**Mandatory validation (every create & every update) — Load skill `vibe.agents-md`:**
+
+- Size target 60–150 lines (Optimal). Warn at 200+, force split/trim at 300+.
+- 4-question check per line (outside `VIBE-BEHAVIORAL` block):
+  - Would the agent make a mistake without this? (No → delete)
+  - Needed every session? (No → move to SPEC/plan)
+  - Can a linter/hook replace it? (Yes → move)
+  - Discoverable from code? (Yes → delete)
+- Lost-in-the-Middle: critical rules at top, frequently-violated rules at bottom.
+- Addy Osmani test: "Can the agent discover this by reading the code?" → Yes = delete.
+- Strip tech-stack name-drops already stated in `package.json`.
+
+Report line ranges to trim per file. Do not auto-delete; surface findings for user approval before finalizing.
+
+**When to run:**
+- After `vibe init` / `vibe update` if `CLAUDE.md` or `AGENTS.md` is missing or out of sync.
+- After upgrading `@su-record/vibe` when the behavioral template changes.
+- Whenever the SSOT file is edited — re-sync `AGENTS.md`.
+- User explicitly asks to refresh agent instructions.

package/skills/vibe.docs/references/arch.md

@@ -0,0 +1,28 @@
+# /vibe.docs arch — Architecture Documentation
+
+> vibe.docs SKILL.md 의 서브커맨드 표에서 **`arch` 가 선택됐을 때만** 로드한다.
+
+### `/vibe.docs arch` — Architecture Documentation
+
+Generate architecture overview with diagrams:
+
+1. **Module map**: Directory structure → responsibility mapping
+2. **Dependency graph**: Import analysis → Mermaid diagram
+3. **Data flow**: Entry points → processing → output
+4. **Key decisions**: Extract from CLAUDE.md and code comments
+
+Output: `docs/ARCHITECTURE.md`
+
+**Mermaid diagram generation:**
+```
+File-pattern search: src/**/ → module list
+Text search: pattern="^import .+ from" → dependency edges
+Full-file reading: CLAUDE.md → architecture notes
+
+Generate:
+graph TD
+    CLI[CLI Commands] --> Core[Core Logic]
+    Core --> Infra[Infrastructure]
+    Infra --> DB[(Database)]
+    Infra --> API[External APIs]
+```

package/skills/vibe.docs/references/codemaps.md

@@ -0,0 +1,17 @@
+# /vibe.docs codemaps — Codemaps Generation
+
+> vibe.docs SKILL.md 의 서브커맨드 표에서 **`codemaps` 가 선택됐을 때만** 로드한다.
+
+### `/vibe.docs codemaps` — Codemaps Generation
+
+Generate auto-documentation from codebase structure directly (native
+capability — no dedicated agent).
+
+**Output Location:** `docs/CODEMAPS/`
+
+> Read `references/codemaps-output.md` for the full generated-files tree, per-file contents, and tools used.
+
+**Example:**
+```
+/vibe.docs codemaps
+```

package/skills/vibe.docs/references/diagram.md

@@ -0,0 +1,24 @@
+# /vibe.docs diagram — Diagram Generation
+
+> vibe.docs SKILL.md 의 서브커맨드 표에서 **`diagram` 가 선택됐을 때만** 로드한다.
+
+### `/vibe.docs diagram` — Diagram Generation
+
+Generate Mermaid diagrams for architecture, ERD, flowchart, or sequence
+visualization directly (native capability — no dedicated agent). Ground the
+diagram in sources first: folder structure and imports for architecture;
+`models/`, `migrations/`, `schema.*`, ORM definitions for ERDs; the real
+branch/return structure of the code for flowcharts.
+
+**Options:**
+- `/vibe.docs diagram` (default): Architecture overview
+- `/vibe.docs diagram --er`: Entity-Relationship Diagram
+- `/vibe.docs diagram --flow`: Flowchart
+- `/vibe.docs diagram --seq`: Sequence Diagram
+
+> Read `references/diagram-spec.md` for the full output conventions (Mermaid syntax per diagram type, save location, accuracy constraints).
+
+**Example:**
+```
+/vibe.docs diagram --er
+```

package/skills/vibe.docs/references/guide.md

@@ -0,0 +1,23 @@
+# /vibe.docs guide — User Guide
+
+> vibe.docs SKILL.md 의 서브커맨드 표에서 **`guide` 가 선택됐을 때만** 로드한다.
+
+### `/vibe.docs guide` — User Guide
+
+Generate a step-by-step user guide:
+
+1. **Installation**: Detect package manager, prerequisites
+2. **Configuration**: Find all config files, document each option
+3. **Usage**: Extract CLI commands or API usage patterns
+4. **FAQ**: Common issues from error handling patterns
+5. **Troubleshooting**: Known edge cases from test files
+
+Output: `docs/GUIDE.md`
+
+**Analysis approach:**
+```
+Full-file reading: package.json → bin, scripts, peerDependencies
+File-pattern search: src/cli/commands/*.ts → CLI command list
+Text search: pattern="throw new|Error\(" → common error scenarios
+Text search: pattern="(process\.env|config)\.\w+" → configuration options
+```