vibestack: Instructions file for Claude Code

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.

Skill authoring conventions CI enforces

Each rule has a suite that fails the build; the suite holds the detail.

• Every bash block runs in a fresh shell. A block restates what it needs — re-derive it, or use a '<NAME>' placeholder the model fills from an earlier block's printed NAME: line. lib/snippets/browse-detect.md is the canonical example. (test/test-fresh-shell-vars.sh)
• Untrusted text reaches a command only through a file. Plans, diffs, user instructions, reviewer comments and page content are written with the Write tool; shell source carries the path, never the text — no heredoc slots, --body-file/stdin instead of --body "<...>". (test/test-untrusted-shell-text.sh)
• Every synchronous subagent dispatch states run_in_background: false. Include lib/snippets/foreground-dispatch.md. (test/test-dispatch-flags.sh)
• Gates fail closed. A timeout, parse error, empty result or unverifiable tree is "unavailable", never a pass. (test/test-codex-verdict.sh, test/test-review-tree-binding.sh, test/test-land-deploy-gates.sh)
• Tests meet the value bar. A test earns its place with the four questions, and a regression test is proven red before the fix. Include lib/snippets/test-value-bar.md in any skill that writes or proposes tests. (test/test-test-value-bar.sh)
• Descriptions are a context budget. Every session lists them; keep them short and run bin/vibe-context-budget. (test/test-context-budget.sh; CI reports it)
• Brand audit. bin/vibe-brand-audit on files, commits and PR text. (test/test-brand-audit.sh, CI)
• Source lint. Balanced fences, no nested includes — bin/vibe-lint-sources. (test/test-source-lint.sh)