@su-record/vibe 3.2.1 → 3.2.2

package/skills/docs/SKILL.md

@@ -1,259 +0,0 @@
----
-name: docs
-description: 프로젝트 문서 생성 본체 — README / 아키텍처 / 사용자 가이드 / 릴리즈 노트 / Mermaid 다이어그램 / codemaps.
-when_to_use: /vibe.docs 진입점에서 체인 호출. 직접 호출 금지.
-user-invocable: false
-tier: standard
----
-
-# vibe.docs — Project Documentation Generator
-
-Generate or update project documentation by analyzing the actual codebase.
-
-## Subcommands
-
-### `/vibe.docs readme` — README Generation
-
-Analyze the codebase and generate a complete README.md:
-
-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/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 `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
-
-`/vibe.docs` completes the development pipeline:
-
-```
-/vibe.spec    → Design (what to build)
-/vibe.run     → Implement (build it)
-/vibe.trace   → Verify (prove it works)
-/vibe.docs    → Document (explain it)
-```
-
-### Auto-trigger after `/vibe.trace`
-
-When `/vibe.trace` completes with all scenarios passing, suggest:
-> "All scenarios verified. Run `/vibe.docs readme` to update documentation?"
-
-## Guidelines
-
-### DO
-- Read the actual codebase before generating — never guess
-- Preserve existing documentation that's still accurate
-- Include concrete code examples from the actual project
-- Keep language consistent with project (Korean/English based on CLAUDE.md)
-- For `/vibe.docs release` (changelog mode), follow `references/api-docs-changelog.md` natively — no dedicated agent
-- For API-heavy projects (api-docs mode), follow `references/api-docs-changelog.md` natively
-- For `/vibe.docs arch` and `/vibe.docs diagram` Mermaid generation, follow `references/diagram-spec.md` natively
-- Use the `agents-md` skill for `/vibe.docs agent` — applies equally to CLAUDE.md and AGENTS.md
-
-### DON'T
-- Don't generate placeholder text ("Lorem ipsum", "TODO: fill in")
-- Don't document internal implementation details in user-facing docs
-- Don't create files without reading existing ones first
-- Don't assume features — verify by reading code
-
-## Quality Checklist
-
-Before finalizing any document:
-
-- [ ] All code examples are runnable (copy-paste ready)
-- [ ] Installation steps tested against package.json
-- [ ] Links and paths are valid
-- [ ] No placeholder text remaining
-- [ ] Consistent with project language (Korean/English)

package/skills/exec-plan/SKILL.md

@@ -1,151 +0,0 @@
----
-name: exec-plan
-user-invocable: false
-invocation: [auto, chain]
-tier: core
-description: "Convert a SPEC (3+ phases or multi-file) into a self-contained execution plan — explicit file paths, interfaces, acceptance criteria — that agents can run autonomously."
-triggers: [exec plan, execution plan, autonomous plan, self-contained plan, execute this spec, run this plan, parallel implementation]
-priority: 60
-chain-next: [commit-push-pr]
----
-
-# ExecPlan — Self-Contained Execution Plan Generator
-
-> **Principle**: "If the agent can't see it, it doesn't exist." Every decision, file path, pattern, and verification step must be explicit in the plan — no implicit knowledge allowed.
-
-## When to Use
-
-Before `/vibe.run`, generate an ExecPlan to make execution deterministic:
-
-| Scenario | Signal |
-|----------|--------|
-| Complex SPEC (3+ phases) | Agent needs long autonomous execution |
-| Team/multi-agent execution | Multiple agents need shared understanding |
-| Context window pressure | Plan survives `/new` session handoff |
-| Unfamiliar codebase | Agent can't rely on implicit knowledge |
-
-## Core Flow
-
-```
-SPEC + Feature → ANALYZE → RESOLVE → GENERATE → PERSIST
-```
-
-### Step 1: ANALYZE — Extract Everything Needed
-
-Read the SPEC and Feature files, then extract:
-
-```
-For each Phase → For each Scenario:
-  1. Requirements (REQ-* IDs)
-  2. Given/When/Then conditions
-  3. Affected files (MUST exist — verify with Glob)
-  4. Dependencies (imports, packages)
-  5. Existing patterns to follow (read actual code, don't assume)
-```
-
-**Parallel exploration** (3+ agents):
-- Agent 1: Map all file paths mentioned/implied in SPEC → verify they exist
-- Agent 2: For each affected file, extract current interfaces/types/exports
-- Agent 3: Find existing patterns (naming conventions, error handling, test structure)
-
-### Step 2: RESOLVE — Eliminate All Ambiguity
-
-For every decision point in the SPEC, resolve it NOW:
-
-| Ambiguity | Resolution |
-|-----------|------------|
-| "Add validation" | → Which fields? What rules? What error messages? |
-| "Handle errors" | → Which error codes? What response format? |
-| "Follow existing pattern" | → Copy the ACTUAL pattern code into the plan |
-| "Update tests" | → Which test file? What test framework? What assertions? |
-
-**Rule**: If you'd need to "figure it out later", resolve it now. The plan must be executable by an agent with ZERO codebase knowledge.
-
-### Step 3: GENERATE — Write the ExecPlan
-
-Output format: `.vibe/specs/{feature-name}-execplan.md`
-
-```markdown
-# ExecPlan: {feature-name}
-
-## Meta
-- SPEC: .vibe/specs/{name}.md
-- Feature: .vibe/features/{name}.feature
-- Generated: {timestamp}
-- Phases: {count}
-- Scenarios: {count}
-
-## Pre-flight Checks
-- [ ] `npm run build` passes
-- [ ] `npx vitest run` passes (baseline)
-- [ ] Required files exist: {list}
-
-## Phase {N}: {phase-name}
-
-### Environment
-- Files to modify: {exact paths}
-- Files to create: {exact paths}
-- Dependencies to add: {package@version}
-- Patterns to follow: (inline code snippets from codebase)
-
-### Scenario {N}.{M}: {scenario-name}
-
-**Given**: {precondition}
-→ Setup: {exact code/commands to establish precondition}
-
-**When**: {action}
-→ Implement: {step-by-step implementation instructions}
-  - File: {path}
-  - Location: after line containing `{anchor text}`
-  - Code: (inline snippet)
-  - Imports needed: {list}
-
-**Then**: {expected result}
-→ Verify:
-  - Command: `{test command}`
-  - Expected: {output/behavior}
-  - Fallback: {what to do if verification fails}
-
-### Phase {N} Gate
-- [ ] Build: `npm run build`
-- [ ] Tests: `npx vitest run {relevant-test-files}`
-- [ ] Type check: `npx tsc --noEmit`
-
-## Completion Criteria
-- Coverage threshold: ≥95%
-- All scenarios passing
-- No regressions in existing tests
-- RTM: `generateTraceabilityMatrix("{feature-name}")`
-```
-
-### Step 4: PERSIST — Save and Link
-
-1. Save ExecPlan to `.vibe/specs/{feature-name}-execplan.md`
-2. Save session context: `save_memory("execplan-{feature}", {summary})`
-3. Output execution command:
-
-```
-Ready to execute:
-  /vibe.run "{feature-name}" ultrawork
-
-Or hand off to new session:
-  /vibe.continue
-  → Load: .vibe/specs/{feature-name}-execplan.md
-```
-
-## Quality Checks
-
-| Check | Criteria |
-|-------|----------|
-| No implicit knowledge | Every file path verified with Glob |
-| No "figure it out" | Every decision resolved with actual code |
-| Survives handoff | Plan readable without any prior context |
-| Inline patterns | Actual code snippets, not "follow existing pattern" |
-| Verification steps | Every scenario has a concrete verification command |
-
-## Anti-patterns
-
-- "See the existing implementation" → Copy the relevant code inline
-- "Follow the pattern in X" → Show the actual pattern
-- "Standard error handling" → Specify exact error codes and messages
-- "Update tests accordingly" → Name the test file, framework, and assertions