CLAUDE.md git:20260902.c52dab4A

Immutable. This exact content never changes and is served at /api/v1/blob/570bb416cbf1f9c5.

# 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

```yaml
---
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`**:
  ```json
  {"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`)

`${CLAUDE_SKILL_DIR}` points to the installed skill directory at runtime. Reference sibling skills:
```bash
bash "${CLAUDE_SKILL_DIR}/../other-skill/bin/script.sh"
```

### Testing hook scripts directly

```bash
# Safe exception — should return {}
echo '{"tool_input":{"command":"rm -rf node_modules"}}' \
  | bash skills/careful/bin/check-careful.sh

# Dangerous path — should return an "ask" decision under hookSpecificOutput
echo '{"tool_input":{"command":"rm -rf /var/important"}}' \
  | bash skills/careful/bin/check-careful.sh

# Catastrophic path — should return a "deny" decision
echo '{"tool_input":{"command":"rm -rf /"}}' \
  | bash skills/careful/bin/check-careful.sh

# Quoted argument ahead of a destructive tail — must NOT return {}
echo '{"tool_input":{"command":"git commit -m \"wip\" && rm -rf /"}}' \
  | bash skills/careful/bin/check-careful.sh

# Unparseable payload — careful asks, freeze denies; neither returns {}
echo 'not json' | bash skills/careful/bin/check-careful.sh

# Freeze check with no state file — should return {}
echo '{"tool_input":{"file_path":"/tmp/test.txt"}}' \
  | bash skills/freeze/bin/check-freeze.sh
```

## Session state

Persistent state lives in `~/.vibestack/` (or `$VIBESTACK_HOME`):

```
~/.vibestack/
└── freeze-dir.txt    # written by /freeze, read by check-freeze.sh
```

Naming: descriptive flat files with a `.txt` extension. Always guard reads with `[ -f "$file" ]`. Provide a paired "off" skill to clean up.

## Using shared snippets

Skills can pull in shared markdown sections via include directives.
Put the canonical content in `lib/snippets/<name>.md`, then reference
it from any skill source file:

```
{{include lib/snippets/<name>.md}}
```

Rules for the include directive:

- The directive line must match the regex
  `^\{\{include lib/snippets/[A-Za-z0-9_-]+\.md\}\}$` exactly — no
  leading/trailing whitespace, no comment characters.
- Indented or fenced occurrences are treated as content (so you can
  document the directive inside a ```` ``` ```` code block without
  triggering it).
- Snippets must NOT contain other include directives — v1 supports
  one level only. The renderer detects nested includes and exits 2.
- One token substitution: `{SKILL_NAME}` in snippet content is
  replaced with the source skill's directory basename at render
  time. Use it when a snippet's content needs to embed the skill's
  own name (e.g., the JSON `"skill"` field in a logging command).

When `./install` runs, `bin/vibe-render-skill` expands directives
and writes the rendered file to `~/.claude/skills/<name>/SKILL.md`
as a regular file. A sidecar `.vibe-render.json` is also written
when expansion happened, listing the source path and included parts.

To check whether installed output has drifted from sources:

```bash
bin/vibe-render-skill --check skills/<name>/SKILL.md ~/.claude/skills/<name>/SKILL.md
# exit 0 = no drift; exit 1 = drift; the diff is printed to stderr.
```

## Install and update

```bash
./install                          # interactive: asks per-target (claude, cursor, kiro, codex)
./install --target=all             # all four, non-interactive
./install --target=claude          # claude only
./install --target=cursor,kiro     # cursor + kiro
./install --target=codex           # Codex CLI only
./install --scope=project --project-root=<dir> --target=claude
                                   # project-local: pins the pack into <dir>/.claude/skills
./install --yes                    # all four, skip prompts (CI-friendly)
./install --dry-run --target=all   # preview, no writes

./uninstall                        # claude only (default for v1.3.x compat)
./uninstall --target=all           # remove from all four
./uninstall --target=cursor        # cursor only
```

vibestack supports four agent runtimes via the [Agent Skills open
standard](https://agentskills.io/specification): Claude Code
(`~/.claude/skills/`), Cursor (`~/.cursor/skills/`), Kiro
(`~/.kiro/skills/`), and Codex CLI (`~/.agents/skills/`). The same rendered
`SKILL.md` is written to each target's directory — no format translation.
`bin/` and sub-doc symlinks are installed per target so the "edit source,
immediately reflected" workflow works in any chosen target.

**A target name is not a directory name.** Codex reads user skills from
`~/.agents/skills` and repo skills from `.agents/skills`, while its config lives
in `~/.codex` — so `install` keeps three maps: `TARGET_CONFIG_DIR` (detection
only), `TARGET_ROOT` (user scope) and `TARGET_PROJECT_REL` (project scope).
`TARGET_LEGACY_ROOT` names superseded roots; `prune_legacy_root` removes **our
own skill names** from them (never the root — Codex's bundled `.system/` lives
there). Adding a runtime is one row per map. The `agents/openai.yaml` manifest
registers the pack with Codex.

**Withdrawing a skill needs the install manifest.** `prune_removed_skills`
writes `.vibestack-manifest` — the names `vibestack_owned_names` emitted, one per
line — into each target root, and on the next run removes any name that file
claims which the pack no longer ships. Without it a withdrawn skill is
indistinguishable from a skill another tool installed, so `adopt_foreign_entries`
carries it back into the live root and it lives on forever. Remove a name only
when the manifest claims it *and* `$root/$name/SKILL.md` still exists; `uninstall`
deletes the manifest with the skills. Deleting `skills/<name>/` is therefore the
whole of a removal — the pruning follows from the name leaving
`vibestack_owned_names`.

Invocation differs per runtime. Claude Code, Cursor and Kiro expose skills as
`/name`. **Codex does not** — `/` there is reserved for its own commands, so `/office-hours`
completes to nothing. A Codex skill is referenced as `$name` inside an ordinary message
(`Use $office-hours to shape this idea`), or triggered implicitly from its `description`,
which its bundled `skill-creator` calls "the primary triggering mechanism". Verified
against codex-cli 0.147.0: `Use $office-hours` loads the skill body; there is no
`/skills` picker in that build.

Update flow: `git pull && ./install`. The install is idempotent — re-runs
produce identical bytes. No restart needed if your agent supports
hot-reload; otherwise start a new session.

## Multi-target output

When adding a new skill, remember it'll install into Claude Code, Cursor,
Kiro, and Codex CLI by default. Three implications:

1. **Write skill bodies in tool-name terms that modern LLMs understand.**
   Claude Code tools like `AskUserQuestion`, `Agent`, `Read`, `Edit` are
   recognized by Cursor/Kiro's hosted LLMs and mapped to native equivalents.
   Don't worry about per-target tool-name translation in v1.

2. **Hook-bearing skills (`hooks:` frontmatter) get a tier disclosure.**
   Claude Code intercepts via `PreToolUse`. Cursor/Kiro behavior is
   verified manually per `docs/hook-verification.md`. The install prints
   a one-line warning when hook-bearing skills land in non-Claude targets.

3. **Run `bash test/test-install-integration.sh` after touching install/
   uninstall.** Covers regression (claude byte-identical), multi-target
   install, idempotency, dry-run, hook warnings, uninstall round-trip, and the
   withdrawn-skill prune — that a re-install removes a skill the manifest claims
   and the pack dropped, leaves an unrelated directory alone, and takes the
   manifest with it on uninstall.

## Naming and attribution

Everything this repo publishes goes out under its own name. Describe what the
code does and why — never where a behavior came from.

This applies to **commit messages, PR titles and bodies, and release notes** as
much as to the files themselves. A commit message is as public as the code, and
once merged it cannot be corrected without rewriting published history.

```bash
bin/vibe-brand-audit                      # tracked files
bin/vibe-brand-audit --commits main..HEAD # + this branch's commit messages
bin/vibe-brand-audit --text /tmp/pr.md    # + a PR body or release notes
```

CI runs all three on every PR. `bin/vibe-brand-audit --help` lists what it
looks for. Two deliberate carve-outs:

- Bare `upstream` is fine — it is git vocabulary ("the branch's upstream",
  "something upstream broke"). Only phrasings that assert another project is
  the source are rejected.
- Vendored third-party files (`extension/lib/`, `lib/diagram-render/dist/`) are
  skipped. Their headers carry licence text and author credit that must stay;
  crediting a dependency's authors is a different thing entirely.

## Commit discipline

- One logical change per commit
- Imperative mood: `fix:`, `feat:`, `docs:`, `chore:`
- Good: `fix: safe exception sed — replace \s with [[:space:]] for macOS BSD sed`
- Bad: `update check-careful.sh`

## Shipping (this repo)

When work in this repo is complete and verified (tests green, no drift, brand
audit clean), **proceed straight to `/ship` — do not pause to ask for commit or
PR permission.** This is a standing, repo-scoped authorization that overrides
the global "never commit/push without explicit permission" rule for vibestack
only. `/ship` branches off main, runs tests, reviews the diff, bumps `VERSION`,
updates `CHANGELOG.md`, commits, pushes, and opens the PR. If `VERSION` /
`CHANGELOG` were already bumped by hand for the change, reconcile rather than
double-bump.

## Adding a skill checklist

- [ ] `skills/<name>/SKILL.md` exists with valid frontmatter
- [ ] `name:` matches the directory name exactly
- [ ] `description:` is one clear sentence (used for auto-invoke matching)
- [ ] `allowed-tools:` lists only what the skill uses
- [ ] If hooks: `bin/` scripts exist, are executable, use POSIX-safe patterns
- [ ] Hook scripts tested manually with `echo '{...}' | bash skills/.../check-*.sh`
- [ ] If using shared snippets: directive matches the grammar above; no nested includes
- [ ] New session confirms slash command works
- [ ] README skills table updated
- [ ] `docs/skills.md` entry added (the full per-skill reference)
- [ ] `skills/vibe/SKILL.md` router updated so the skill is reachable by name
- [ ] `./install` runs without errors
- [ ] `bash test/test-render-skill.sh` passes if the renderer or any snippet was touched
- [ ] `bash test/test-install-integration.sh` passes if install/uninstall was touched
- [ ] `docs/agent-skills-compatibility-audit.md` updated if the new skill uses
      `${CLAUDE_SKILL_DIR}`, declares `hooks:`, or otherwise has Claude-Code-
      specific runtime dependencies (so the per-skill compatibility row is
      accurate for Cursor/Kiro users)