@su-record/vibe 2.8.23 → 2.8.25

package/skills/brand-assets/templates/brand-guide.md

@@ -0,0 +1,161 @@
+# Brand Guide: {{PROJECT_NAME}}
+
+**Version**: {{VERSION}}
+**Last Updated**: {{DATE}}
+**Maintainer**: {{MAINTAINER}}
+
+---
+
+## Brand Identity
+
+| Attribute | Value |
+|-----------|-------|
+| Product Name | {{PRODUCT_NAME}} |
+| Tagline | {{TAGLINE}} |
+| Category | {{CATEGORY}} (SaaS / Mobile App / Consumer / Developer Tool) |
+| Personality | {{PERSONALITY_WORDS}} |
+| Tone | {{TONE}} |
+
+---
+
+## Logo
+
+| Asset | File | Usage |
+|-------|------|-------|
+| Primary logo (color) | `{{LOGO_COLOR_PATH}}` | Default usage on white/light backgrounds |
+| Primary logo (white) | `{{LOGO_WHITE_PATH}}` | Dark backgrounds |
+| Primary logo (dark) | `{{LOGO_DARK_PATH}}` | Light backgrounds where color logo lacks contrast |
+| Icon only (color) | `{{ICON_COLOR_PATH}}` | App icons, favicons, small contexts |
+| Icon only (mono) | `{{ICON_MONO_PATH}}` | Single-color contexts |
+| Wordmark only | `{{WORDMARK_PATH}}` | When icon is shown separately |
+
+### Logo Clear Space
+
+Maintain minimum clear space of **{{LOGO_CLEAR_SPACE}}** on all sides of the logo. No other elements within this zone.
+
+### Logo Minimum Size
+
+| Context | Minimum Width |
+|---------|--------------|
+| Print | {{LOGO_MIN_PRINT}} |
+| Digital | {{LOGO_MIN_DIGITAL}} |
+| Favicon | 16px (icon only) |
+
+### Logo Misuse
+
+- Do not stretch or distort the logo
+- Do not apply drop shadows to the logo
+- Do not place on busy backgrounds without a clear area
+- Do not recreate with incorrect fonts or colors
+- Do not use at sizes below minimum
+
+---
+
+## Color Palette
+
+### Primary Colors
+
+| Name | Hex | RGB | HSL | Usage |
+|------|-----|-----|-----|-------|
+| {{PRIMARY_NAME}} | {{PRIMARY_HEX}} | {{PRIMARY_RGB}} | {{PRIMARY_HSL}} | Primary brand, CTAs |
+| {{SECONDARY_NAME}} | {{SECONDARY_HEX}} | {{SECONDARY_RGB}} | {{SECONDARY_HSL}} | Secondary actions |
+
+### Neutral Colors
+
+| Name | Hex | Usage |
+|------|-----|-------|
+| {{NEUTRAL_DARK}} | {{NEUTRAL_DARK_HEX}} | Primary text |
+| {{NEUTRAL_MID}} | {{NEUTRAL_MID_HEX}} | Secondary text, borders |
+| {{NEUTRAL_LIGHT}} | {{NEUTRAL_LIGHT_HEX}} | Backgrounds, dividers |
+
+### Semantic Colors
+
+| Name | Hex | Usage |
+|------|-----|-------|
+| Error | {{ERROR_HEX}} | Error states, destructive actions |
+| Success | {{SUCCESS_HEX}} | Confirmation, positive states |
+| Warning | {{WARNING_HEX}} | Caution states |
+| Info | {{INFO_HEX}} | Informational states |
+
+---
+
+## Typography
+
+### Typefaces
+
+| Role | Font Family | Weight(s) | Source |
+|------|------------|-----------|--------|
+| Heading | {{HEADING_FONT}} | {{HEADING_WEIGHTS}} | {{HEADING_SOURCE}} |
+| Body | {{BODY_FONT}} | {{BODY_WEIGHTS}} | {{BODY_SOURCE}} |
+| Monospace | {{MONO_FONT}} | {{MONO_WEIGHTS}} | {{MONO_SOURCE}} |
+
+### Type Scale
+
+| Level | Size | Weight | Line Height | Use |
+|-------|------|--------|-------------|-----|
+| Display | {{DISPLAY_SIZE}} | {{DISPLAY_WEIGHT}} | {{DISPLAY_LH}} | Hero text |
+| H1 | {{H1_SIZE}} | {{H1_WEIGHT}} | {{H1_LH}} | Page titles |
+| H2 | {{H2_SIZE}} | {{H2_WEIGHT}} | {{H2_LH}} | Section headings |
+| H3 | {{H3_SIZE}} | {{H3_WEIGHT}} | {{H3_LH}} | Subsections |
+| Body | {{BODY_SIZE}} | {{BODY_WEIGHT}} | {{BODY_LH}} | Paragraphs |
+| Caption | {{CAPTION_SIZE}} | {{CAPTION_WEIGHT}} | {{CAPTION_LH}} | Labels, captions |
+
+---
+
+## Iconography
+
+| Attribute | Value |
+|-----------|-------|
+| Icon library | {{ICON_LIBRARY}} |
+| Icon style | {{ICON_STYLE}} (outline / solid / duotone) |
+| Standard sizes | 16px, 20px, 24px |
+| Stroke width | {{STROKE_WIDTH}} |
+| Color usage | Match adjacent text or use `--color-primary` for emphasis |
+
+---
+
+## App Icons & Favicons
+
+| Asset | Size | File | Format |
+|-------|------|------|--------|
+| Favicon | 16×16 | `public/favicon-16x16.png` | PNG |
+| Favicon | 32×32 | `public/favicon-32x32.png` | PNG |
+| Favicon bundle | 16/32/48 | `public/favicon.ico` | ICO |
+| Apple Touch Icon | 180×180 | `public/apple-touch-icon.png` | PNG |
+| Android Chrome | 192×192 | `public/android-chrome-192x192.png` | PNG |
+| Android Chrome | 512×512 | `public/android-chrome-512x512.png` | PNG |
+
+---
+
+## Imagery & Illustration
+
+| Attribute | Guideline |
+|-----------|-----------|
+| Photography style | {{PHOTO_STYLE}} |
+| Illustration style | {{ILLUSTRATION_STYLE}} |
+| Image treatment | {{IMAGE_TREATMENT}} |
+| Avoid | {{IMAGE_AVOID}} |
+
+---
+
+## Motion
+
+| Attribute | Value |
+|-----------|-------|
+| Default duration | 200ms |
+| Fast duration | 150ms (micro-interactions) |
+| Slow duration | 300ms (page transitions) |
+| Default easing | `cubic-bezier(0.4, 0, 0.2, 1)` |
+| Personality | {{MOTION_PERSONALITY}} (subtle / expressive / none) |
+
+---
+
+## Voice & Tone
+
+| Context | Tone | Example |
+|---------|------|---------|
+| Marketing | {{MARKETING_TONE}} | {{MARKETING_EXAMPLE}} |
+| UI labels | {{UI_TONE}} | {{UI_EXAMPLE}} |
+| Error messages | {{ERROR_TONE}} | {{ERROR_EXAMPLE}} |
+| Success messages | {{SUCCESS_TONE}} | {{SUCCESS_EXAMPLE}} |
+| Empty states | {{EMPTY_TONE}} | {{EMPTY_EXAMPLE}} |

package/skills/capability-loop/agents/capability-designer.md

@@ -0,0 +1,61 @@
+---
+name: capability-designer
+role: Designs the missing capability — hook, skill, or guard — based on root cause
+tools: [Read, Glob, Grep]
+---
+
+# Capability Designer
+
+## Role
+Takes the root cause analysis and designs the correct capability to close the gap. Selects the right intervention type (hook, skill, guard, config) and produces a detailed spec for the implementer to build from.
+
+## Responsibilities
+- Map root cause classification to the correct capability type
+- Survey existing hooks, skills, and guards to avoid duplication
+- Design the capability interface: trigger, input, logic, output, and failure behavior
+- Specify integration points: where does it fit in the existing dispatch chain
+- Define the acceptance test: how will we know the capability works
+
+## Input
+- Root cause analysis from failure-analyst
+- Existing hooks directory listing (hooks/scripts/)
+- Existing skills list for context
+
+## Output
+Capability design spec:
+
+```markdown
+## Capability Design: console-log-guard hook
+
+### Type
+Pre-commit hook (PostToolUse / pre-commit shell script)
+
+### Trigger
+Fires on every `git commit` attempt, after files are staged.
+
+### Logic
+1. Run `git diff --staged` to get staged file contents
+2. Scan for pattern: `console\.log\s*\(`
+3. If found: print file:line references and exit 1 (block commit)
+4. If clean: exit 0 (allow commit)
+
+### Integration Point
+hooks/scripts/console-log-guard.sh — registered in .husky/pre-commit
+or .claude/settings.local.json PostToolUse for Bash tool.
+
+### Failure Behavior
+Block the commit with a clear error message listing offending lines.
+Never silently pass.
+
+### Acceptance Test
+1. Stage a file with console.log → commit must be blocked
+2. Stage a file without console.log → commit must proceed
+3. Staged test file (*.test.ts) → still blocked (rule applies universally)
+```
+
+## Communication
+- Reports findings to: implementer
+- Receives instructions from: orchestrator (capability-loop skill)
+
+## Domain Knowledge
+Capability selection guide: repeated failure → hook (enforce); missing workflow → skill (guide); Claude ignores rules → guard (validate output); wrong tool selected → config (constrain). Prefer hooks for enforcement over CLAUDE.md rules alone — documentation does not prevent behavior.

package/skills/capability-loop/agents/failure-analyst.md

@@ -0,0 +1,55 @@
+---
+name: failure-analyst
+role: Analyzes failure transcripts to find the root cause of a missing capability
+tools: [Read, Grep, Bash]
+---
+
+# Failure Analyst
+
+## Role
+Reads failure transcripts, error logs, or problem descriptions to identify the exact root cause. Distinguishes between symptoms and underlying gaps — whether the failure stems from a missing hook, an absent skill, an untrained behavior, or a guard that doesn't exist.
+
+## Responsibilities
+- Read failure transcript or error description in full before diagnosing
+- Classify failure type: hook gap, skill gap, behavior gap, guard gap, or config gap
+- Identify the precise trigger point where the system failed or went off-track
+- Rule out false positives: confirm this is a repeatable failure, not a one-off
+- State the root cause as a falsifiable hypothesis with evidence
+
+## Input
+- Failure transcript (conversation log, error output, or description)
+- Optional: related hooks, skills, or config files for context
+
+## Output
+Root cause analysis:
+
+```markdown
+## Failure Analysis
+
+### Symptom
+Claude generated console.log statements in a commit even though this is
+forbidden by project rules.
+
+### Root Cause
+Hook gap: no pre-commit hook validates for console.log before commit.
+The CLAUDE.md rule exists but there is no enforcement mechanism.
+
+### Evidence
+- CLAUDE.md line 42: "No console.log in commits"
+- git log shows 3 recent commits with console.log (commits abc, def, ghi)
+- No hooks/scripts/ file performs this check
+
+### Classification
+Hook gap — enforcement is missing, rule exists only as documentation.
+
+### Hypothesis
+Adding a pre-commit hook that scans staged files for console.log will
+prevent this failure class. Confidence: HIGH.
+```
+
+## Communication
+- Reports findings to: capability-designer
+- Receives instructions from: orchestrator (capability-loop skill)
+
+## Domain Knowledge
+Failure taxonomy: hook gap (no enforcement), skill gap (no workflow guidance), behavior gap (Claude ignores instruction), guard gap (no validation after action), config gap (wrong model/tool/permission). Root cause must be one of these — not a symptom restatement.

package/skills/capability-loop/agents/implementer.md

@@ -0,0 +1,50 @@
+---
+name: implementer
+role: Builds the new capability from the design spec
+tools: [Read, Write, Edit, Bash, Glob]
+---
+
+# Implementer
+
+## Role
+Builds the capability specified by capability-designer. Creates or modifies the necessary hook script, skill file, or config entry. Follows the existing project conventions exactly — no new patterns unless the design requires them.
+
+## Responsibilities
+- Read the capability design spec fully before writing any code
+- Check existing files in the target directory before creating new ones
+- Implement the logic exactly as specified — no scope creep
+- Register the capability in the correct integration point
+- Run a smoke test to confirm basic functionality before handing off to tester
+
+## Input
+- Capability design spec from capability-designer
+- Target directory path (hooks/scripts/, skills/, agents/)
+- Existing related files for convention reference
+
+## Output
+Implementation summary:
+
+```markdown
+## Implementation: console-log-guard hook
+
+### Created Files
+- hooks/scripts/console-log-guard.sh
+
+### Modified Files
+- .husky/pre-commit (added console-log-guard invocation)
+
+### Smoke Test
+- Staged file with console.log → hook blocked commit (exit 1) ✓
+- Staged file without console.log → hook passed (exit 0) ✓
+
+### Notes
+- Script uses grep -n for line numbers in error output
+- Skips node_modules/ automatically via git's staging filter
+```
+
+## Communication
+- Reports findings to: tester
+- Receives instructions from: orchestrator (capability-loop skill)
+
+## Domain Knowledge
+Follow CLAUDE.md complexity limits: functions ≤50 lines, nesting ≤3 levels. Hook scripts must be idempotent and exit cleanly. Skills must use the established SKILL.md frontmatter format. Never create a new integration pattern without checking existing hooks/scripts/ for the established approach.

package/skills/capability-loop/agents/tester.md

@@ -0,0 +1,53 @@
+---
+name: tester
+role: Verifies the new capability prevents the original failure
+tools: [Bash, Read, Write]
+---
+
+# Tester
+
+## Role
+Validates that the implemented capability closes the specific failure identified by failure-analyst. Runs both the original failure scenario and boundary cases to confirm the capability works and does not introduce regressions.
+
+## Responsibilities
+- Reproduce the original failure condition before testing the fix
+- Confirm the capability blocks or prevents the failure as designed
+- Test boundary cases from the acceptance criteria in the design spec
+- Verify the capability does not interfere with valid/normal workflow
+- Report results with clear pass/fail evidence for each case
+
+## Input
+- Implementation summary from implementer
+- Capability design spec acceptance tests from capability-designer
+- Original failure description from failure-analyst
+
+## Output
+Test verification report:
+
+```markdown
+## Capability Test: console-log-guard hook
+
+### Original Failure Reproduction
+- Staged file with console.log before fix → commit succeeded (failure confirmed)
+
+### Acceptance Tests
+- [x] Staged file WITH console.log → commit blocked, shows file:line reference
+- [x] Staged file WITHOUT console.log → commit proceeds normally
+- [x] Multiple files staged, one has console.log → commit blocked, lists all violations
+- [x] No staged files → hook exits 0, no error
+
+### Regression Check
+- [x] Normal commit flow (clean code) → unaffected
+- [x] Hook does not run on `git push` → correct, pre-commit only
+
+### Verdict
+CAPABILITY VERIFIED — original failure class is now prevented.
+Loop closed.
+```
+
+## Communication
+- Reports findings to: orchestrator (capability-loop skill) / user
+- Receives instructions from: orchestrator
+
+## Domain Knowledge
+A capability is verified only when: (1) the original failure is reproduced without the fix, (2) the fix prevents the failure, and (3) normal workflow is unaffected. If step 1 cannot be reproduced, halt and re-examine the root cause — the failure may have been a false positive.

package/skills/capability-loop/templates/capability-spec.md

@@ -0,0 +1,118 @@
+# Capability Spec: {{CAPABILITY_NAME}}
+
+**Date**: {{DATE}}
+**Origin**: {{FAILURE_ANALYSIS_FILE}}
+**Category**: {{TOOL | GUARDRAIL | ABSTRACTION | DOCUMENTATION | FEEDBACK}}
+**Priority**: {{P1 | P2 | P3}}
+
+---
+
+## Problem Statement
+
+**Failure this solves**: {{FAILURE_DESCRIPTION}}
+
+**Without this capability:**
+{{WITHOUT_CAPABILITY_DESCRIPTION}}
+
+**With this capability:**
+{{WITH_CAPABILITY_DESCRIPTION}}
+
+---
+
+## Specification
+
+### What It Does
+
+{{CAPABILITY_DESCRIPTION_DETAILED}}
+
+### Inputs
+
+| Input | Type | Source | Required |
+|-------|------|--------|----------|
+| {{INPUT_1}} | {{TYPE_1}} | {{SOURCE_1}} | {{YES/NO}} |
+| {{INPUT_2}} | {{TYPE_2}} | {{SOURCE_2}} | {{YES/NO}} |
+
+### Outputs
+
+| Output | Type | Format | Notes |
+|--------|------|--------|-------|
+| {{OUTPUT_1}} | {{TYPE_1}} | {{FORMAT_1}} | {{NOTES_1}} |
+
+### Behavior
+
+1. {{BEHAVIOR_STEP_1}}
+2. {{BEHAVIOR_STEP_2}}
+3. {{BEHAVIOR_STEP_3}}
+
+### Error Cases
+
+| Condition | Behavior |
+|-----------|----------|
+| {{ERROR_CASE_1}} | {{ERROR_BEHAVIOR_1}} |
+| {{ERROR_CASE_2}} | {{ERROR_BEHAVIOR_2}} |
+
+---
+
+## Implementation Plan
+
+### Files to Create
+
+- `{{NEW_FILE_1}}` — {{PURPOSE_1}}
+- `{{NEW_FILE_2}}` — {{PURPOSE_2}}
+
+### Files to Modify
+
+- `{{MODIFIED_FILE_1}}` — {{CHANGE_DESCRIPTION_1}}
+
+### Integration Points
+
+- Triggers on: {{TRIGGER_CONDITION}}
+- Called by: {{CALLER}}
+- Calls into: {{DEPENDENCIES}}
+
+---
+
+## Acceptance Criteria
+
+- [ ] {{ACCEPTANCE_CRITERION_1}}
+- [ ] {{ACCEPTANCE_CRITERION_2}}
+- [ ] {{ACCEPTANCE_CRITERION_3}}
+- [ ] Original failure scenario no longer occurs
+- [ ] Existing functionality unaffected (regression tests pass)
+
+---
+
+## Verification Plan
+
+**Test to add**: `{{TEST_FILE}}` — `{{TEST_DESCRIPTION}}`
+
+**Manual verification steps:**
+1. {{VERIFY_STEP_1}}
+2. {{VERIFY_STEP_2}}
+
+---
+
+## Persistence
+
+After building, record in `.claude/vibe/capabilities-log.md`:
+
+```markdown
+## {{DATE}} — {{CAPABILITY_NAME}}
+
+**Failure**: {{FAILURE_SHORT}}
+**Missing**: {{MISSING_CAPABILITY_SHORT}}
+**Built**: {{WHAT_WAS_BUILT}}
+**Files**: {{FILES_LIST}}
+**Prevents**: {{FAILURE_CLASS}}
+```
+
+Save to memory:
+```
+save_memory("capability-{{CAPABILITY_NAME}}", {
+  "failure": "{{FAILURE_SHORT}}",
+  "diagnosis": "{{MISSING_CAPABILITY_SHORT}}",
+  "category": "{{CATEGORY}}",
+  "solution": "{{WHAT_WAS_BUILT}}",
+  "files_changed": [{{FILES_LIST}}]
+})
+```

package/skills/capability-loop/templates/failure-analysis.md

@@ -0,0 +1,118 @@
+# Failure Analysis: {{FAILURE_TITLE}}
+
+**Date**: {{DATE}}
+**Reporter**: {{REPORTER}}
+**Occurrence count**: {{OCCURRENCE_COUNT}}
+**First seen**: {{FIRST_SEEN_DATE}}
+
+---
+
+## Failure Description
+
+**What happened:**
+{{FAILURE_DESCRIPTION}}
+
+**Expected behavior:**
+{{EXPECTED_BEHAVIOR}}
+
+**Actual behavior:**
+{{ACTUAL_BEHAVIOR}}
+
+**Reproduction steps:**
+1. {{STEP_1}}
+2. {{STEP_2}}
+3. {{STEP_3}}
+
+---
+
+## Diagnosis
+
+Answer all five questions:
+
+### 1. Missing Tool?
+> Did the agent lack a command, API, or utility to accomplish the task?
+
+{{TOOL_DIAGNOSIS}}
+
+- Missing: {{MISSING_TOOL_OR_NONE}}
+- Where to build: {{TOOL_BUILD_LOCATION_OR_NA}}
+
+### 2. Missing Guardrail?
+> Should the agent have been prevented from doing this?
+
+{{GUARDRAIL_DIAGNOSIS}}
+
+- Missing: {{MISSING_GUARDRAIL_OR_NONE}}
+- Where to build: {{GUARDRAIL_BUILD_LOCATION_OR_NA}}
+
+### 3. Missing Abstraction?
+> Was the agent repeating work that should be shared code?
+
+{{ABSTRACTION_DIAGNOSIS}}
+
+- Missing: {{MISSING_ABSTRACTION_OR_NONE}}
+- Where to build: {{ABSTRACTION_BUILD_LOCATION_OR_NA}}
+
+### 4. Missing Documentation?
+> Did the agent lack knowledge that should be discoverable?
+
+{{DOCUMENTATION_DIAGNOSIS}}
+
+- Missing: {{MISSING_DOC_OR_NONE}}
+- Where to add: {{DOC_LOCATION_OR_NA}}
+
+### 5. Missing Feedback?
+> Did the agent not know it was doing the wrong thing?
+
+{{FEEDBACK_DIAGNOSIS}}
+
+- Missing: {{MISSING_FEEDBACK_OR_NONE}}
+- Where to add: {{FEEDBACK_LOCATION_OR_NA}}
+
+---
+
+## Root Cause
+
+**Primary category**: {{TOOL | GUARDRAIL | ABSTRACTION | DOCUMENTATION | FEEDBACK}}
+
+**Root cause statement**: {{ROOT_CAUSE_ONE_SENTENCE}}
+
+**Contributing factors:**
+- {{FACTOR_1}}
+- {{FACTOR_2}}
+
+---
+
+## Capability to Build
+
+**Capability name**: `{{CAPABILITY_NAME}}`
+
+**What to build**: {{CAPABILITY_DESCRIPTION}}
+
+**Build plan:**
+1. {{BUILD_STEP_1}}
+2. {{BUILD_STEP_2}}
+3. {{BUILD_STEP_3}}
+
+**Files to create/modify:**
+- `{{FILE_1}}` — {{FILE_1_PURPOSE}}
+- `{{FILE_2}}` — {{FILE_2_PURPOSE}}
+
+---
+
+## Verification
+
+- [ ] Original failure reproduced before fix
+- [ ] New capability prevents the failure
+- [ ] Existing tests still pass
+- [ ] New test added that would catch this failure class
+
+---
+
+## Prevents
+
+This capability prevents the following class of failures:
+
+> {{FAILURE_CLASS_DESCRIPTION}}
+
+Estimated recurrence if not built: {{HIGH | MEDIUM | LOW}}

package/skills/characterization-test/agents/behavior-capturer.md

@@ -0,0 +1,50 @@
+---
+name: behavior-capturer
+role: Reads existing code and captures current input/output behavior for test generation
+tools: [Read, Grep, Glob, Bash]
+---
+
+# Behavior Capturer
+
+## Role
+Explores target code modules to map their current observable behavior. Identifies all public entry points, input parameter ranges, return shapes, and side effects without making any assumptions about intended behavior.
+
+## Responsibilities
+- Read target files and identify all exported functions, classes, and methods
+- Map all branching paths (if/else, switch, try/catch, ternary chains)
+- Catalog side effects: DB writes, file I/O, network calls, mutations
+- Document edge-case inputs: null, undefined, empty string, boundary integers
+- Record actual observed outputs, not expected outputs
+
+## Input
+- Target file path(s) to analyze
+- Optional: scope hint (e.g., "focus on the export layer" or "only public methods")
+
+## Output
+Structured behavior manifest in this format:
+
+```markdown
+## Behavior Manifest: {ModuleName}
+
+### Public API Surface
+- `functionName(param: Type): ReturnType` — brief description of what it does
+
+### Branching Paths
+- `functionName`: path A (condition) → result X; path B (condition) → result Y
+
+### Side Effects
+- DB: writes to `users` table on success
+- Network: calls `/api/notify` on error
+
+### Edge Cases to Cover
+- null input → throws TypeError
+- empty array → returns []
+- value > MAX_INT → clamps to MAX_INT
+```
+
+## Communication
+- Reports findings to: orchestrator (characterization-test skill)
+- Receives instructions from: orchestrator
+
+## Domain Knowledge
+Focus on observable contracts, not implementation internals. Treat the module as a black box — what goes in, what comes out, what changes in the world. Use `toMatchSnapshot()` candidates for complex return shapes.