setup-skill

name	setup-skill
description	XVE setup — apply personal Claude Code settings, agents, and commands to this machine.
disable-model-invocation	true

Set up this machine's Claude Code environment to match the XVE standard configuration.

Step 1 — Detect repo location

Find where this marketplace is checked out:

REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" 2>/dev/null && git rev-parse --show-toplevel 2>/dev/null || echo "UNKNOWN")"

If unknown, ask user for the path.

Step 2 — Apply ~/.claude/settings.json

Read plugins/xve/config/settings.json from this repo. Merge with existing ~/.claude/settings.json (preserve any machine-specific additions, overwrite matching keys).

Key things applied:

• env vars (ENABLE_TOOL_SEARCH, BASH_DEFAULT_TIMEOUT_MS, CLAUDE_CODE_MAX_OUTPUT_TOKENS, etc.)
• permissions allow/deny lists
• model: sonnet, effortLevel: xhigh, advisorModel: opus
• UserPromptSubmit hook → assertion checker

Advisor strategy: model: sonnet (fast executor) + advisorModel: opus (strategic oversight via Opus 4.7) + effortLevel: xhigh + DISABLE_ADAPTIVE_THINKING: 1. Sonnet handles execution; Opus advises before major decisions. ~11% cheaper than Opus-only with near-identical quality on agentic tasks. Adaptive thinking disabled on Sonnet intentionally — the advisor covers that layer.

Call advisor: before writing code, when stuck, before declaring done. Not after every step.

Step 3 — Install session-start hook (confirm first)

Ask the user:

"Install session hooks? These run automatically on every Claude session:

• session-start.sh — injects context at session start (enables/disables advisor via env vars)
• env-guard.sh — blocks Claude from reading/executing .env files via any tool
• writing-guard.sh — Stop hook; flags AI writing tells (em dashes, banned vocab) and asks Claude to revise. Safety net behind the CLAUDE.md Writing Guidelines.

Install? [Y/n]"

If yes:

cp "$REPO_DIR/hooks/session-start.sh" ~/.claude/session-start.sh
chmod +x ~/.claude/session-start.sh

curl -fsSL https://raw.githubusercontent.com/XVE-BV/claude-marketplace/main/hooks/env-guard.sh \
  -o ~/.claude/env-guard.sh 2>/dev/null || cp "$REPO_DIR/hooks/env-guard.sh" ~/.claude/env-guard.sh
chmod +x ~/.claude/env-guard.sh

cp "$REPO_DIR/hooks/writing-guard.sh" ~/.claude/writing-guard.sh
chmod +x ~/.claude/writing-guard.sh

session-start.sh injects context at session start based on env vars:

• DISABLE_ADVISOR=1 → blocks advisor() calls

env-guard.sh is a PreToolUse hook that blocks access to .env files via Read/Edit/Write and any bash command referencing .env. Deny rules in settings.json alone are insufficient — this hook is the actual gate.

writing-guard.sh is a Stop hook that scans Claude's last response for AI writing tells (banned vocabulary, em dash overuse, AI phrases). When violations are found in prose responses over 150 words, it blocks the stop and forces Claude to revise. Note: this fires after the original response is already on screen — Claude posts a corrected version in a follow-up turn. The ## Writing Guidelines block in CLAUDE.md is the primary prevention; this hook is the safety net. Requires jq.

Step 4 — Install xve-hud statusline (confirm first)

Ask the user:

"Install the XVE statusline (xve-hud)? Shows a handoff-urgency banner on the statusline — amber at 60% context, red at 85%, early bump if you're burning quota fast. Requires jq. [Y/n]"

If yes:

command -v jq >/dev/null || { echo "jq missing — skipping. Install jq and re-run /xve:hud-setup later."; SKIP_HUD=1; }

If jq is present, merge the following into ~/.claude/settings.json (preserve other keys with jq):

{
  "statusLine": {
    "type": "command",
    "command": "${CLAUDE_PLUGIN_ROOT}/statusline/xve-hud.sh"
  }
}

Remind the user: a full Claude Code restart is required for the statusline change to take effect.

Step 5 — Check env vars

echo "DISABLE_ADVISOR:    ${DISABLE_ADVISOR:-0 (advisor enabled)}"

Other env vars (optional — mention, don't prompt):

# export DISABLE_ADVISOR=1       # uncomment to disable Opus advisor
# XVE_CUSTOMER_N — see .env.example for full template

Step 6 — Write guidance to CLAUDE.md

Force-overwrite the xve-managed sections in ~/.claude/CLAUDE.md with the latest canonical versions. A timestamped backup is taken first so the user can recover any local edits.

Behavior: On every run — first install or re-run — managed sections are stripped and replaced with the canonical versions below. Any user edits inside those sections will be overwritten (they live in the .bak file). Sections outside this set are left untouched.

CLAUDE_MD="$HOME/.claude/CLAUDE.md"
touch "$CLAUDE_MD"

# Always back up first so user can recover local edits.
BACKUP="$HOME/.claude/CLAUDE.md.bak.$(date +%Y%m%d-%H%M%S)"
cp "$CLAUDE_MD" "$BACKUP"
echo "Backup: $BACKUP"

# Strip every xve-managed section (## Heading until next ## or EOF).
awk '
  BEGIN {
    managed["## Advisor"] = 1
    managed["## LLM Council"] = 1
    managed["## Decisive Thinking"] = 1
    managed["## Coding Guidelines"] = 1
    managed["## Review Mindset"] = 1
    managed["## Writing Guidelines"] = 1
    in_strip = 0
  }
  $0 in managed { in_strip = 1; next }
  in_strip && /^## / { in_strip = 0 }
  !in_strip { print }
' "$CLAUDE_MD" > "$CLAUDE_MD.tmp" && mv "$CLAUDE_MD.tmp" "$CLAUDE_MD"

# Append all canonical sections in one heredoc.
cat >> "$CLAUDE_MD" << 'EOF'

## Advisor

Call advisor() BEFORE substantive work — before writing, before committing to an approach. Reading files to orient is fine first.

Also call when:
- Stuck (errors recurring, approach not converging)
- Changing approach
- Task complete — but first make deliverables durable (write file, commit)

On longer tasks: once before committing to approach, once before declaring done. Don't call after every step — advisor adds most value before the approach crystallizes.

Give advice serious weight. If data and advice conflict, don't silently switch — make one more advisor call: "I found X, you suggest Y, which breaks the tie?"

## LLM Council

Use `council this` when the cost of a bad call is high and there are real tradeoffs between options.

Good fit:
- Genuine uncertainty with meaningful options (architecture choices, hiring, pricing, strategy)
- Decision you keep going back and forth on

Not a good fit:
- Factual lookups — just ask directly
- Creation tasks (write a tweet, summarise this)
- Already decided — don't run council to validate

## Decisive Thinking

When deciding how to approach a problem, choose an approach and commit to it.
Avoid revisiting decisions unless you encounter new information that directly
contradicts your reasoning. If weighing two approaches, pick one and see it
through — you can course-correct later if it fails.

Thinking adds latency and should only be used when it will meaningfully
improve answer quality. When in doubt, respond directly.

State conclusions, not deliberation. If you reconsider, do it once and move
on — don't loop. If you catch yourself revisiting the same decision a second
time, call advisor() before continuing rather than spiraling further.

## Coding Guidelines

### Think Before Coding
- State assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them — don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.

### Simplicity First
- Minimum code that solves the problem. No speculative features.
- No abstractions for single-use code, no unrequested "flexibility".
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.

### Surgical Changes
- Touch only what the request requires. Don't improve adjacent code.
- Match existing style, even if you'd do it differently.
- If you notice unrelated dead code, mention it — don't delete it.
- Every changed line should trace directly to the user's request.

### Goal-Driven Execution
- Transform tasks into verifiable goals before starting.
- For multi-step tasks, state a brief plan with verification steps.
- Define success criteria upfront so you can loop independently.

## Review Mindset

Treat every output — code, prose, decisions — as if a senior engineer will review it line by line and catch sloppy work. Not a hypothetical: assume it.

This isn't about being defensive or hedging. It's about the bar: would this hold up under scrutiny by someone who knows the domain better than you? If not, fix it before shipping.

## Writing Guidelines

Write like a human, not a language model. These rules apply to all output — responses, docs, messages, anything.

**Banned vocabulary (never use):** delve, tapestry, landscape (abstract), pivotal, underscore (verb), testament, meticulous, nuanced, multifaceted, embark, spearhead, bolster, garner, realm, robust, seamless, groundbreaking, transformative, paramount, myriad, cornerstone, catalyst, nestled, bustling, vibrant, comprehensive, invaluable, reimagine, empower.

**Structural tells to avoid:**
- Em dashes as a stylistic habit — use commas, periods, or parentheses instead. Max one per 500 words.
- Parallel negation: "Not X, but Y" → just state the positive.
- Rule of three: forcing ideas into trios. Pick one or two.
- Inflation of importance: "pivotal moment", "testament to", "crucial development" → delete. State facts.
- Signposting: "Let's dive in", "Here's what you need to know" → drop it, start with the substance.
- Neat endings on every paragraph → let some thoughts just stop.
- Sycophantic openers: "Great question!", "Certainly!" → cut entirely.

**Always do:**
- Vary sentence length. Short. Then a longer one. Then a fragment. AI writes at a steady rhythm; don't.
- Have opinions. Remove "it could be argued" and say the thing.
- Use specific details — numbers, names, dates — over vague claims.
- Start some sentences with "And" or "But."
- Don't dumb it down. "Human" isn't "simplistic."
EOF

echo "Updated CLAUDE.md sections. Old version: $BACKUP"

Step 7 — Summary

XVE Claude Code Setup
─────────────────────
settings.json:        ✓ applied
session-start.sh:     ✓ / ✗
env-guard.sh:         ✓ / ✗
writing-guard.sh:     ✓ / ✗
xve-hud:              ✓ wired / ✗ skipped
CLAUDE.md sections:   ✓ refreshed (backup: ~/.claude/CLAUDE.md.bak.<timestamp>)

Step 8 — Open the guide

Run /xve:docs to open the XVE docs in the browser so the user has the getting started guide on screen.