vibestack CLAUDE.md

CLAUDE.md — vibestack Development Guide

This file guides development of vibestack itself. Read it before editing skills or tooling.

Skill structure

Every skill is a directory in skills/ with a SKILL.md and an optional bin/ directory:

skills/my-skill/
├── SKILL.md        # required — frontmatter + instruction body
└── bin/            # optional — hook scripts
    └── check-*.sh

SKILL.md frontmatter

---
name: my-skill               # slash command name — no spaces, matches directory name
description: |               # one clear sentence; drives auto-invoke matching
  What this skill does and when to use it.
allowed-tools:               # list only what the skill actually uses
  - Bash
  - Read
  - Edit
  - Write
  - Grep
  - Glob
triggers:                    # phrases that auto-invoke the skill
  - phrase that triggers it
hooks:                       # optional: PreToolUse interceptors
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "bash ${CLAUDE_SKILL_DIR}/bin/check.sh"
          statusMessage: "Checking..."
---

Body style

• Write in natural language, not bash. The model follows prose instructions.
• Use ## sections for phases or major steps.
• Embed an output template so Claude knows exactly how to format results.
• Keep it tight — remove anything the model doesn't need to act on.

Hook scripts

Hook scripts live in skills/<name>/bin/. Rules:

• Read JSON from stdin (the tool call payload from Claude Code)
• Return {} to allow the tool call through silently
• To pause or block, return the decision nested under hookSpecificOutput:

  {"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"..."}}
  

  permissionDecision is "ask" or "deny"; the human-readable text goes in permissionDecisionReason. Claude Code ignores a top-level permissionDecision — a hook that emits one runs, matches, prints, and changes nothing. The failure is silent, so it survives casual testing.
• Never hand-build that JSON with printf/sed interpolation. A path or message containing a quote or newline produces malformed JSON, and the whole decision is discarded. Source skills/careful/bin/hook-extract.sh and call vibe_hook_decision <ask|deny> "<reason>".
• Parse the payload with vibe_hook_extract_field "$INPUT" <field> from the same file, never with grep -o '"field"..."[^"]*"' — that pattern truncates at the first escaped quote, so git commit -m "wip" && rm -rf / reaches the checks as git commit -m \.
• Decide the polarity for an unreadable payload deliberately, and say which you chose in a comment. Ask-tier hooks (/careful) ask; deny-tier boundary hooks (/freeze) deny. A boundary that fails open is not a boundary.
• Use #!/usr/bin/env bash with set -euo pipefail
• Use POSIX ERE patterns — [[:space:]] not \s, (^|[^[:alnum:]_])x not \bx\b (BSD grep and sed on macOS do not support the GNU escapes)
• Use ^ anchors in sed, not .*pattern greedy matches
• Be executable (chmod +x)