@windyroad/voice-tone 0.1.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "wr-voice-tone",
+  "version": "0.1.0",
+  "description": "Voice and tone enforcement for Claude Code"
+}

package/agents/agent.md

@@ -0,0 +1,74 @@
+---
+name: agent
+description: Voice and tone reviewer for copy changes. Use before editing any
+  user-facing copy in source files. Reads docs/VOICE-AND-TONE.md and reviews
+  proposed changes against the guide's voice principles, tone guidance, banned
+  patterns, and word list. Reports violations with suggested fixes.
+tools:
+  - Read
+  - Glob
+  - Grep
+model: inherit
+---
+
+You are the Voice and Tone Lead. You review proposed copy changes against the project's docs/VOICE-AND-TONE.md guide before any user-facing text is edited. You are a reviewer, not an editor.
+
+## Your Role
+
+1. Read `docs/VOICE-AND-TONE.md` in the project to load the current guide
+2. Read the file(s) being edited to understand the existing copy and context
+3. Review proposed changes against every section of the guide
+4. Report: OK if compliant, or list specific violations with suggested fixes
+
+## What You Check
+
+All review criteria come from `docs/VOICE-AND-TONE.md`. Read the guide first and apply its sections. Typical sections include:
+
+- **Voice principles** — the personality and values behind the copy
+- **Tone by context** — how tone varies by situation (errors, onboarding, success, etc.)
+- **Banned patterns** — specific phrases or anti-patterns to reject
+- **Word list / terminology** — preferred terms and domain vocabulary
+- **Language & locale** — spelling conventions, casing rules, app name formatting
+
+If the guide defines additional sections, check those too. Do not invent rules that are not in the guide.
+
+## How to Report
+
+If the copy is compliant:
+> **Voice & Tone Review: PASS**
+> No violations found. Copy aligns with the voice guide.
+
+If there are violations, list each one:
+
+> **Voice & Tone Review: VIOLATIONS FOUND**
+>
+> 1. **[Principle/Rule]** - File: `path`, Line ~N
+>    - **Issue**: What is wrong
+>    - **Copy**: The offending text
+>    - **Fix**: Suggested replacement
+>
+> 2. ...
+
+## Guide Gap Detection
+
+If the code introduces a UI context, audience, or copy pattern not covered by `docs/VOICE-AND-TONE.md`, flag this as a guide gap:
+
+> **Voice & Tone Review: GUIDE UPDATE NEEDED**
+>
+> The code introduces [context/audience/pattern] which is not covered by the current voice and tone guide.
+> Recommended addition to `docs/VOICE-AND-TONE.md`: [specific section/content to add]
+
+This is a FAIL verdict — the guide must be updated before the code can proceed. Write `printf 'FAIL' > /tmp/voice-tone-verdict` for guide gaps.
+
+## Verdict
+
+After completing your review, write your verdict to `/tmp/voice-tone-verdict`:
+- `printf 'PASS' > /tmp/voice-tone-verdict` — copy is compliant and guide covers the context
+- `printf 'FAIL' > /tmp/voice-tone-verdict` — violations found or guide gap detected
+
+## Constraints
+
+- You are read-only. You do not edit files (except writing the verdict file).
+- You review copy in user-facing source files.
+- If the change is purely structural (no user-visible text changes), report PASS.
+- Do not block styling-only changes (CSS classes, layout, imports with no copy).

package/bin/install.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const utils = await import(resolve(__dirname, "../lib/install-utils.mjs"));
+
+const PLUGIN = "wr-voice-tone";
+const DEPS = [];
+
+const flags = utils.parseStandardArgs(process.argv);
+
+if (flags.help) {
+  console.log(`
+Usage: npx @windyroad/voice-tone [options]
+
+Voice and tone enforcement for user-facing copy
+
+Options:
+  --update     Update this plugin and its skills
+  --uninstall  Remove this plugin
+  --dry-run    Show what would be done without executing
+  --help, -h   Show this help
+`);
+  process.exit(0);
+}
+
+if (flags.dryRun) {
+  utils.setDryRun(true);
+  console.log("[dry-run mode — no commands will be executed]\n");
+}
+
+utils.checkPrerequisites();
+
+if (flags.uninstall) {
+  utils.uninstallPackage(PLUGIN);
+} else if (flags.update) {
+  utils.updatePackage(PLUGIN);
+} else {
+  utils.installPackage(PLUGIN, { deps: DEPS });
+}

package/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/voice-tone-eval.sh" }] }
+    ],
+    "PreToolUse": [
+      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/voice-tone-enforce-edit.sh" }] }
+    ],
+    "PostToolUse": [
+      { "matcher": "Agent", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/voice-tone-mark-reviewed.sh" }] }
+    ],
+    "Stop": [
+      { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/voice-tone-reset-marker.sh" }] }
+    ]
+  }
+}

package/hooks/lib/review-gate.sh

@@ -0,0 +1,102 @@
+#!/bin/bash
+# Shared gate logic for review enforcement hooks (a11y, voice-tone, style-guide).
+# Sourced by *-enforce-edit.sh hooks and review-plan-enforce.sh.
+# Provides: check_review_gate, review_gate_deny, review_gate_parse_error
+
+# Source shared portable helpers (_mtime, _hashcmd)
+_REVIEW_GATE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$_REVIEW_GATE_DIR/gate-helpers.sh"
+
+# Check review gate marker. Returns 0 if marker is valid (allow), 1 if invalid (deny).
+# Sets REVIEW_GATE_REASON on failure.
+# Usage: check_review_gate "$SESSION_ID" "style-guide" "docs/STYLE-GUIDE.md"
+check_review_gate() {
+  local SESSION_ID="$1"
+  local SYSTEM="$2"        # e.g., "a11y", "voice-tone", "style-guide"
+  local POLICY_FILE="$3"   # e.g., "docs/STYLE-GUIDE.md"
+  local MARKER="/tmp/${SYSTEM}-reviewed-${SESSION_ID}"
+  local HASH_FILE="/tmp/${SYSTEM}-reviewed-${SESSION_ID}.hash"
+  local TTL_SECONDS="${REVIEW_TTL:-600}"
+
+  # 1. Marker must exist
+  if [ ! -f "$MARKER" ]; then
+    REVIEW_GATE_REASON="No ${SYSTEM} review marker found. The ${SYSTEM} agent must review first."
+    return 1
+  fi
+
+  # 2. TTL check — marker mtime must be within TTL
+  local NOW=$(date +%s)
+  local MARKER_TIME=$(_mtime "$MARKER")
+  local AGE=$(( NOW - MARKER_TIME ))
+  if [ "$AGE" -ge "$TTL_SECONDS" ]; then
+    rm -f "$MARKER" "$HASH_FILE"
+    REVIEW_GATE_REASON="${SYSTEM} review expired (${AGE}s old, TTL ${TTL_SECONDS}s). Re-run the ${SYSTEM} agent."
+    return 1
+  fi
+
+  # 3. Drift detection — policy file hash must match
+  if [ -f "$HASH_FILE" ] && [ -n "$POLICY_FILE" ]; then
+    local STORED_HASH=$(cat "$HASH_FILE")
+    local CURRENT_HASH=""
+    if [ -f "$POLICY_FILE" ]; then
+      CURRENT_HASH=$(cat "$POLICY_FILE" | _hashcmd | cut -d' ' -f1)
+    elif [ -d "$POLICY_FILE" ]; then
+      # Directory (e.g., docs/decisions/) — hash all .md files
+      CURRENT_HASH=$(find "$POLICY_FILE" -name '*.md' -not -name 'README.md' -print0 | sort -z | xargs -0 cat 2>/dev/null | _hashcmd | cut -d' ' -f1)
+    else
+      CURRENT_HASH="missing"
+    fi
+    if [ "$STORED_HASH" != "$CURRENT_HASH" ]; then
+      rm -f "$MARKER" "$HASH_FILE"
+      REVIEW_GATE_REASON="${SYSTEM} policy file changed since last review. Re-run the ${SYSTEM} agent."
+      return 1
+    fi
+  fi
+
+  # Slide TTL window forward
+  touch "$MARKER"
+  return 0
+}
+
+# Store policy file hash after a successful review.
+# Usage: store_review_hash "$SESSION_ID" "style-guide" "docs/STYLE-GUIDE.md"
+store_review_hash() {
+  local SESSION_ID="$1"
+  local SYSTEM="$2"
+  local POLICY_FILE="$3"
+  local HASH_FILE="/tmp/${SYSTEM}-reviewed-${SESSION_ID}.hash"
+
+  if [ -n "$POLICY_FILE" ]; then
+    local HASH=""
+    if [ -f "$POLICY_FILE" ]; then
+      HASH=$(cat "$POLICY_FILE" | _hashcmd | cut -d' ' -f1)
+    elif [ -d "$POLICY_FILE" ]; then
+      HASH=$(find "$POLICY_FILE" -name '*.md' -not -name 'README.md' -print0 | sort -z | xargs -0 cat 2>/dev/null | _hashcmd | cut -d' ' -f1)
+    else
+      HASH="missing"
+    fi
+    echo "$HASH" > "$HASH_FILE"
+  fi
+}
+
+# Emit fail-closed deny JSON for PreToolUse hooks.
+review_gate_deny() {
+  local REASON="$1"
+  cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "$REASON"
+  }
+}
+EOF
+}
+
+# Emit fail-closed deny JSON for parse failures.
+review_gate_parse_error() {
+  cat <<'EOF'
+{ "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny",
+    "permissionDecisionReason": "BLOCKED: Could not parse hook input. Gate is fail-closed." } }
+EOF
+}

package/hooks/voice-tone-enforce-edit.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+# Voice & Tone - PreToolUse enforcement hook
+# BLOCKS Edit/Write to copy-bearing files until voice-and-tone-lead is consulted.
+# Uses shared review-gate.sh for TTL, drift detection, and fail-closed.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/lib/review-gate.sh"
+
+INPUT=$(cat)
+
+FILE_PATH=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_input', {}).get('file_path', ''))
+except:
+    print('')
+" 2>/dev/null || echo "")
+
+SESSION_ID=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('session_id', ''))
+except:
+    print('')
+" 2>/dev/null || echo "")
+
+if [ -z "$SESSION_ID" ]; then
+  review_gate_parse_error
+  exit 0
+fi
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Gate copy-bearing files
+case "$FILE_PATH" in
+  *.html|*.jsx|*.tsx|*.vue|*.svelte|*.ejs|*.hbs) ;;
+  *) exit 0 ;;
+esac
+
+BASENAME=$(basename "$FILE_PATH")
+
+# If no policy file exists, block and direct to create skill
+if [ ! -f "docs/VOICE-AND-TONE.md" ]; then
+  review_gate_deny "BLOCKED: Cannot edit '${BASENAME}' because docs/VOICE-AND-TONE.md does not exist. Run /wr-voice-tone:create to generate a voice and tone guide for this project, then delegate to wr-voice-tone:agent for review."
+  exit 0
+fi
+
+# Check gate with TTL + drift detection
+if check_review_gate "$SESSION_ID" "voice-tone" "docs/VOICE-AND-TONE.md"; then
+  exit 0
+fi
+
+review_gate_deny "BLOCKED: Cannot edit '${BASENAME}' without voice & tone review. You MUST first delegate to wr-voice-tone:agent using the Agent tool (subagent_type: 'wr-voice-tone:agent'). ${REVIEW_GATE_REASON}"
+exit 0

package/hooks/voice-tone-eval.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+# Voice & Tone - UserPromptSubmit hook
+# Detects VOICE-AND-TONE.md in the project and injects delegation instruction.
+# If the file doesn't exist, instructs Claude to create it via the agent.
+
+if [ -f "docs/VOICE-AND-TONE.md" ]; then
+  cat <<'HOOK_OUTPUT'
+INSTRUCTION: MANDATORY VOICE & TONE CHECK. YOU MUST FOLLOW THIS.
+DETECTED: docs/VOICE-AND-TONE.md exists in this project.
+
+This is a NON-OPTIONAL instruction. You MUST use the voice-and-tone-lead agent
+before editing any user-facing copy in HTML, JSX, template, or component files.
+This is proactive. Do not wait for the user to ask.
+
+REQUIRED ACTIONS:
+1. Use the Agent tool to delegate to wr-voice-tone:agent
+   (subagent_type: "wr-voice-tone:agent")
+2. The voice-and-tone-lead will review proposed copy against docs/VOICE-AND-TONE.md
+3. Do NOT write or edit copy without voice-and-tone-lead review FIRST
+4. Do NOT skip this step even if you think you can handle it yourself
+
+SCOPE: User-facing files (.html, .jsx, .tsx, .vue, .svelte, .ejs, .hbs).
+Does NOT apply to: .css files, .ts/.js backend files, config files.
+HOOK_OUTPUT
+else
+  # Check if this is a web project (has UI files)
+  if ls src/**/*.tsx src/**/*.jsx src/**/*.html 2>/dev/null | head -1 | grep -q .; then
+    cat <<'HOOK_OUTPUT'
+NOTE: This project has UI files but no docs/VOICE-AND-TONE.md.
+If the user's task involves editing user-facing copy, the edit will be blocked
+until a voice and tone guide exists. Run /wr-voice-tone:create to generate one.
+HOOK_OUTPUT
+  fi
+fi

package/hooks/voice-tone-mark-reviewed.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# Voice & Tone - PostToolUse hook for Agent tool
+# Creates a session marker when voice-and-tone-lead has been consulted with PASS verdict.
+# This marker unlocks the voice-tone-enforce-edit.sh PreToolUse block.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/lib/review-gate.sh"
+
+INPUT=$(cat)
+
+SUBAGENT=$(echo "$INPUT" | jq -r '.tool_input.subagent_type // empty') || true
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty') || true
+
+if [ -z "$SESSION_ID" ]; then
+  exit 0
+fi
+
+case "$SUBAGENT" in
+  *voice-and-tone-lead*|*wr-voice-tone*)
+    VERDICT_FILE="/tmp/voice-tone-verdict"
+    VERDICT=""
+    if [ -f "$VERDICT_FILE" ]; then
+      VERDICT=$(cat "$VERDICT_FILE")
+      rm -f "$VERDICT_FILE"
+    fi
+
+    case "$VERDICT" in
+      PASS)
+        touch "/tmp/voice-tone-reviewed-${SESSION_ID}"
+        store_review_hash "$SESSION_ID" "voice-tone" "docs/VOICE-AND-TONE.md"
+        ;;
+      FAIL)
+        # Do NOT create marker — review found issues
+        ;;
+      *)
+        # No verdict file — backward compat, allow with marker
+        touch "/tmp/voice-tone-reviewed-${SESSION_ID}"
+        store_review_hash "$SESSION_ID" "voice-tone" "docs/VOICE-AND-TONE.md"
+        ;;
+    esac
+
+    # Plan review: agent completion = reviewed.
+    # The main agent must actually run the review agent to reach this hook.
+    # No verdict file needed — PostToolUse:Agent is the unforgeable signal.
+    touch "/tmp/voice-tone-plan-reviewed-${SESSION_ID}"
+    ;;
+esac
+
+exit 0

package/hooks/voice-tone-reset-marker.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+# Voice & Tone - Stop hook
+# Removes the session marker so the next prompt requires a fresh voice review.
+# This tightens the gate from per-session to per-turn.
+
+INPUT=$(cat)
+
+SESSION_ID=$(echo "$INPUT" | python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+print(data.get('session_id', ''))
+" 2>/dev/null)
+
+if [ -n "$SESSION_ID" ]; then
+  rm -f "/tmp/voice-tone-reviewed-${SESSION_ID}" \
+        "/tmp/voice-tone-reviewed-${SESSION_ID}.hash" \
+        "/tmp/voice-tone-verdict" \
+        "/tmp/voice-tone-plan-reviewed-${SESSION_ID}" \
+        "/tmp/voice-tone-plan-verdict"
+fi
+
+exit 0

package/lib/install-utils.mjs

@@ -0,0 +1,163 @@
+/**
+ * Shared install utilities for @windyroad/* packages.
+ * Used by both per-plugin installers and the meta-installer.
+ */
+
+import { execSync } from "node:child_process";
+
+const MARKETPLACE_REPO = "windyroad/agent-plugins";
+const MARKETPLACE_NAME = "windyroad";
+
+let _dryRun = false;
+
+export { MARKETPLACE_REPO, MARKETPLACE_NAME };
+
+export function setDryRun(value) {
+  _dryRun = value;
+}
+
+export function isDryRun() {
+  return _dryRun;
+}
+
+export function run(cmd, label) {
+  console.log(`  ${label}...`);
+  if (_dryRun) {
+    console.log(`    [dry-run] ${cmd}`);
+    return true;
+  }
+  try {
+    execSync(cmd, { stdio: "inherit" });
+    return true;
+  } catch {
+    console.error(`  FAILED: ${label}`);
+    return false;
+  }
+}
+
+export function checkPrerequisites() {
+  if (_dryRun) return;
+
+  try {
+    execSync("claude --version", { stdio: "pipe" });
+  } catch {
+    console.error(
+      "Error: 'claude' CLI not found. Install Claude Code first:\n  https://docs.anthropic.com/en/docs/claude-code\n"
+    );
+    process.exit(1);
+  }
+
+  try {
+    execSync("npx --version", { stdio: "pipe" });
+  } catch {
+    console.error(
+      "Error: 'npx' not found. Install Node.js first:\n  https://nodejs.org\n"
+    );
+    process.exit(1);
+  }
+}
+
+export function addMarketplace() {
+  return run(
+    `claude plugin marketplace add ${MARKETPLACE_REPO}`,
+    `Marketplace: ${MARKETPLACE_NAME}`
+  );
+}
+
+export function installPlugin(pluginName) {
+  return run(
+    `claude plugin install ${pluginName}@${MARKETPLACE_NAME}`,
+    pluginName
+  );
+}
+
+export function updatePlugin(pluginName) {
+  return run(`claude plugin update ${pluginName}`, pluginName);
+}
+
+export function uninstallPlugin(pluginName) {
+  return run(`claude plugin uninstall ${pluginName}`, `Removing ${pluginName}`);
+}
+
+export function installSkills() {
+  return run(
+    `npx -y skills add --yes --all ${MARKETPLACE_REPO}`,
+    "Skills (via skills package)"
+  );
+}
+
+export function updateSkills() {
+  return run("npx -y skills update", "Skills update");
+}
+
+export function removeSkills() {
+  return run(
+    `npx -y skills remove --yes --all ${MARKETPLACE_REPO}`,
+    "Removing skills"
+  );
+}
+
+/**
+ * Install a single package: marketplace add + plugin install + skills.
+ */
+export function installPackage(pluginName, { deps = [] } = {}) {
+  console.log(`\nInstalling @windyroad/${pluginName.replace("wr-", "")}...\n`);
+
+  addMarketplace();
+  installPlugin(pluginName);
+  installSkills();
+
+  if (deps.length > 0) {
+    console.log(`\nNote: This plugin works best with:`);
+    for (const dep of deps) {
+      console.log(`  - @windyroad/${dep.replace("wr-", "")} (npx @windyroad/${dep.replace("wr-", "")})`);
+    }
+  }
+
+  console.log(
+    `\nDone! Restart Claude Code to activate.\n`
+  );
+}
+
+/**
+ * Update a single package.
+ */
+export function updatePackage(pluginName) {
+  console.log(`\nUpdating @windyroad/${pluginName.replace("wr-", "")}...\n`);
+
+  run(
+    `claude plugin marketplace update ${MARKETPLACE_NAME}`,
+    "Updating marketplace"
+  );
+  updatePlugin(pluginName);
+  updateSkills();
+
+  console.log("\nDone! Restart Claude Code to apply updates.\n");
+}
+
+/**
+ * Uninstall a single package.
+ */
+export function uninstallPackage(pluginName) {
+  console.log(`\nUninstalling @windyroad/${pluginName.replace("wr-", "")}...\n`);
+
+  uninstallPlugin(pluginName);
+
+  console.log("\nDone. Restart Claude Code to apply changes.\n");
+  console.log("Note: Skills are shared across packages. Run");
+  console.log("  npx @windyroad/agent-plugins --uninstall");
+  console.log("to remove all skills.\n");
+}
+
+/**
+ * Parse standard flags used by all per-plugin installers.
+ */
+export function parseStandardArgs(argv) {
+  const args = argv.slice(2);
+  return {
+    help: args.includes("--help") || args.includes("-h"),
+    uninstall: args.includes("--uninstall"),
+    update: args.includes("--update"),
+    dryRun: args.includes("--dry-run"),
+  };
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@windyroad/voice-tone",
+  "version": "0.1.1",
+  "description": "Voice and tone enforcement for user-facing copy",
+  "bin": {
+    "windyroad-voice-tone": "./bin/install.mjs"
+  },
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/windyroad/agent-plugins.git",
+    "directory": "packages/voice-tone"
+  },
+  "keywords": [
+    "claude-code",
+    "claude-code-plugin",
+    "ai-agent",
+    "ai-coding"
+  ],
+  "files": [
+    "bin/",
+    "agents/",
+    "hooks/",
+    "skills/",
+    ".claude-plugin/",
+    "lib/"
+  ]
+}

package/skills/wr:voice-tone/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: wr:voice-tone
+description: Create or update the project's docs/VOICE-AND-TONE.md by examining existing content and asking the user about brand voice, audience, and tone preferences.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+# Voice and Tone Guide Generator
+
+Create or update `docs/VOICE-AND-TONE.md` tailored to this project's brand, audience, and content. The voice-and-tone-lead agent reads this file to review user-facing copy.
+
+## What belongs in docs/VOICE-AND-TONE.md
+
+- **Brand voice**: The personality and character of the product's communication
+- **Audience**: Who the product speaks to and their expectations
+- **Tone spectrum**: How tone shifts across contexts (error messages vs success vs onboarding)
+- **Do/Don't examples**: Concrete before/after examples drawn from the actual project
+- **Terminology**: Preferred terms and terms to avoid
+- **Last reviewed date**: When the guide was last reviewed or updated
+
+## Steps
+
+### 1. Discover project context
+
+Examine the project to understand what it does, who uses it, and what voice it currently has.
+
+**Find existing content** by scanning for:
+- User-facing copy in UI files (.tsx, .jsx, .html, .vue, .svelte, .ejs, .hbs)
+- README.md and documentation
+- Error messages and validation text
+- Marketing or landing page content
+- Existing brand guidelines or tone documentation
+
+**Identify the audience**:
+- Is this a developer tool, consumer product, enterprise SaaS, documentation site?
+- Who are the primary users? Technical or non-technical?
+- What is the relationship between the product and its users (formal, casual, peer)?
+
+**Sample existing voice**:
+- Read 5-10 representative UI strings or content blocks
+- Note patterns: formal vs casual, technical vs plain, terse vs verbose
+- Identify inconsistencies that the guide should resolve
+
+### 2. Check for existing guide
+
+If `docs/VOICE-AND-TONE.md` already exists, read it. Identify:
+- Whether the voice description still matches the current product direction
+- Whether examples reference features or copy that no longer exists
+- Whether the last reviewed date is stale (> 2 weeks)
+
+### 3. Draft the voice and tone guide
+
+Based on project discovery, draft sections covering:
+
+**Brand Voice** (3-5 adjectives with explanations):
+Example: "Confident but not arrogant. We know our product well but respect the user's expertise."
+
+**Audience**:
+Who we're speaking to and what they care about.
+
+**Tone Spectrum**:
+How tone adapts to context. Include at least:
+- Success/confirmation messages
+- Error/warning messages
+- Onboarding/help text
+- Empty states
+- Technical documentation
+
+**Do/Don't Examples**:
+At least 5 concrete pairs drawn from the actual project's content patterns. Show the wrong way and the right way, with brief explanations.
+
+**Terminology**:
+- Preferred terms (and what they replace)
+- Terms to avoid (and why)
+
+### 4. Confirm with the user
+
+You MUST use the AskUserQuestion tool to collect user confirmation. Do not proceed to step 5 until you have answers.
+
+Present:
+1. The drafted brand voice adjectives and ask if they match the intended personality
+2. The audience description and ask if it's accurate
+3. The do/don't examples and ask if the direction feels right
+4. Whether any specific tone requirements are missing (e.g., accessibility language, inclusive language, regulatory constraints)
+
+### 5. Write docs/VOICE-AND-TONE.md
+
+Write the guide including:
+- A header with "Last reviewed" date (today's date)
+- All sections from step 3, refined based on user feedback from step 4
+- A note that the wr-voice-tone:agent reads this file to review user-facing copy
+
+If updating rather than creating:
+- Preserve existing guidance the user hasn't asked to change
+- Show the user a diff of what changed
+- Update the "Last reviewed" date
+
+$ARGUMENTS