Hooks and Custom Commands

Create a PreToolUse hook that blocks destructive sf CLI commands against
any org alias containing "prod".

1. Create .claude/hooks/block-prod.sh that:
   - Reads the tool invocation from stdin as JSON
   - Extracts .tool_input.command with jq
   - If the command matches: sf data (update|delete|upsert), sf org delete,
     or sf project deploy start
     AND the --target-org or --alias flag contains "prod"
   - Print a clear block message to stderr and exit 2
   - Otherwise exit 0

2. chmod +x .claude/hooks/block-prod.sh

3. Wire it in .claude/settings.json under hooks.PreToolUse with
   matcher "Bash".

Do not modify any other files. Show me the final contents of both files.

#!/usr/bin/env bash
INPUT="$(cat)"
COMMAND="$(echo "$INPUT" | jq -r '.tool_input.command // ""')"

if echo "$COMMAND" | grep -qE "sf (data (update|delete|upsert)|org delete|project deploy start)"; then
  if echo "$COMMAND" | grep -qE "(--target-org|--alias) \S*prod"; then
    echo "Blocked: destructive operation against a production-aliased org. If this is intended, run it manually." >&2
    exit 2
  fi
fi
exit 0

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": ".claude/hooks/block-prod.sh"
      }
    ]
  }
}

Create a PostToolUse hook that validates Apex edits before they land.

1. Create .claude/hooks/validate-apex.sh that:
   - Reads the tool result from stdin as JSON
   - Extracts .tool_input.file_path with jq
   - If the file ends in .cls or .trigger:
     - Run sf project deploy validate --source-dir <that file's folder> --json
     - If the result's status is 1, print the component failure problems to stderr and exit 2
     - Otherwise exit 0
   - If the file is not Apex, exit 0 immediately

2. chmod +x .claude/hooks/validate-apex.sh

3. Wire it in .claude/settings.json under hooks.PostToolUse with
   matcher "Edit|Write".

Show me both files when done.

#!/usr/bin/env bash
INPUT="$(cat)"
FILE="$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')"

if [[ "$FILE" == *.cls || "$FILE" == *.trigger ]]; then
  OUT="$(sf project deploy validate --source-dir "$(dirname "$FILE")" --json 2>&1 || true)"
  if echo "$OUT" | jq -e '.status == 1' > /dev/null; then
    echo "Validation failed for $FILE:" >&2
    echo "$OUT" | jq -r '.result.details.componentFailures[]?.problem' >&2
    exit 2
  fi
fi
exit 0

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": ".claude/hooks/validate-apex.sh"
      }
    ]
  }
}

Create a SessionStart hook that prints current SF and git context into
the session.

1. Create .claude/hooks/session-start.sh that prints three lines:
   - Current default org alias (from sf config get target-org --json)
   - Current git branch (git branch --show-current)
   - Count of uncommitted files (git status --porcelain | wc -l)

2. chmod +x .claude/hooks/session-start.sh

3. Wire it in .claude/settings.json under hooks.SessionStart.

Show me the final files.

#!/usr/bin/env bash
echo "Current default org: $(sf config get target-org --json | jq -r '.result[0].value // "none"')"
echo "Current branch: $(git branch --show-current)"
echo "Uncommitted files: $(git status --porcelain | wc -l | tr -d ' ')"

{
  "hooks": {
    "SessionStart": [
      {
        "command": ".claude/hooks/session-start.sh"
      }
    ]
  }
}

Create a PostToolUse audit hook for sf CLI commands.

1. Create .claude/hooks/audit-sf.sh that:
   - Reads tool input from stdin as JSON
   - Extracts .tool_input.command with jq
   - If the command starts with "sf ":
     - Append a line to .claude/sf-audit.log with:
       ISO timestamp | cwd basename | the full command
   - Always exit 0 (never block)

2. chmod +x .claude/hooks/audit-sf.sh

3. Wire it in .claude/settings.json under hooks.PostToolUse with matcher "Bash".

4. Add .claude/sf-audit.log to .gitignore.

Show me the final files.

#!/usr/bin/env bash
INPUT="$(cat)"
COMMAND="$(echo "$INPUT" | jq -r '.tool_input.command // ""')"

if [[ "$COMMAND" == sf\ * ]]; then
  TS="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
  PROJECT="$(basename "$(pwd)")"
  echo "$TS | $PROJECT | $COMMAND" >> .claude/sf-audit.log
fi
exit 0

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "command": ".claude/hooks/audit-sf.sh"
      }
    ]
  }
}

.claude/sf-audit.log

Create a TaskCompleted hook that blocks completion of test-related tasks
if Apex tests are failing.

1. Create .claude/hooks/task-gate.sh that:
   - Reads the task info from stdin as JSON
   - Extracts .task.title with jq
   - If the title contains "test" or "coverage" (case-insensitive):
     - Run sf apex run test --wait 10 --json, save output to /tmp/apex-tests.json
     - If the command exits non-zero, print a block message to stderr and exit 2
   - Otherwise exit 0

2. chmod +x .claude/hooks/task-gate.sh

3. Wire it in .claude/settings.json under hooks.TaskCompleted.

Show me the final files.

#!/usr/bin/env bash
INPUT="$(cat)"
TASK="$(echo "$INPUT" | jq -r '.task.title // ""')"

if echo "$TASK" | grep -qiE "(test|coverage)"; then
  if ! sf apex run test --wait 10 --json > /tmp/apex-tests.json 2>&1; then
    echo "Cannot complete task: apex tests failing. See /tmp/apex-tests.json" >&2
    exit 2
  fi
fi
exit 0

{
  "hooks": {
    "TaskCompleted": [
      {
        "command": ".claude/hooks/task-gate.sh"
      }
    ]
  }
}

Create a custom slash command at .claude/commands/deploy.md that:

- Has description: "Deploy force-app to the default scratch org with validation first"
- Body:
  1. Confirms the default org is a scratch org, not prod. If prod, stop and ask.
  2. Runs sf project deploy validate --source-dir force-app
  3. If validation passes, runs sf project deploy start --source-dir force-app
  4. Shows me the deploy ID and a one-line summary
  5. Does not attempt to fix deployment errors, only shows them

Use YAML frontmatter for the description. Show me the file when done.

---
description: Deploy force-app to the default scratch org with validation first
---

Run these steps.

1. Confirm the default org is a scratch org, not prod. If it is prod, stop and ask.
2. Run `sf project deploy validate --source-dir force-app`.
3. If validation passes, run `sf project deploy start --source-dir force-app`.
4. Show me the deploy ID and a one-line summary.

Do not attempt to fix any deployment errors. Show them to me and stop.

Create .claude/commands/reset-org.md with:

- Description: "Reset the current default scratch org from scratch-def and demo data"
- Body: Run scripts/demo-reset.sh with the default org alias. If the script
  fails, show the failing step and stop. Do not run individual sf commands
  as a fallback.

YAML frontmatter. Show the file when done.

---
description: Reset the current default scratch org from scratch-def and demo data
---

Run scripts/demo-reset.sh with the default org alias.
If the script fails, show the failing step and stop.
Do not run individual sf commands as a fallback.

Create .claude/commands/soql.md:

- Description: "Run a SOQL query against the default org"
- argument-hint: "<soql-query>"
- Body:
  - Run sf data query --query "$ARGUMENTS"
  - If the query returns more than 50 rows, show the first 50 and say how
    many were truncated
  - If the filter uses a non-indexed field, warn me before executing and
    wait for confirmation

YAML frontmatter. Show the file when done.

---
description: Run a SOQL query against the default org
argument-hint: <soql-query>
---

Run `sf data query --query "$ARGUMENTS"`.

If the query returns more than 50 rows, show the first 50 and tell me
how many were truncated.

If the filter uses a non-indexed field, warn me before executing and
wait for confirmation.

Create .claude/commands/review.md:

- Description: "Review the current git diff for Apex governor limits, security, and tests"
- Body:
  1. Show me git diff --stat of uncommitted changes
  2. For each .cls or .trigger in the diff, delegate to the apex-reviewer subagent
  3. For each permset in the diff, delegate to the permset-auditor subagent
  4. Consolidate findings into a single markdown report
  5. Do not make edits. Review only.

YAML frontmatter. Show the file when done.

---
description: Review the current git diff for Apex governor limits, security, and tests
---

Run these steps.

1. Show me `git diff --stat` of uncommitted changes.
2. For each .cls and .trigger in the diff, hand off to the apex-reviewer subagent.
3. For each permset in the diff, hand off to the permset-auditor subagent.
4. Consolidate findings into a single markdown report.

Do not make edits. Review only.

Create .claude/commands/handoff.md:

- Description: "Generate or update docs/handoff.md for the current POC"
- Body:
  - Read docs/handoff.md if it exists
  - Compare its contents against:
    - force-app/main/default/ (what is actually in the project)
    - docs/architecture.md and docs/demo-script.md (design intent)
    - The last 20 commit messages (recent changes)
  - Propose edits to handoff.md so it reflects the current project state
  - Write the updated file
  - Show me the diff

YAML frontmatter. Show the file when done.

---
description: Generate or update docs/handoff.md for the current POC
---

Read docs/handoff.md if it exists. Compare its contents against:
- force-app/main/default/ (what's actually in the project)
- docs/architecture.md and docs/demo-script.md (design intent)
- The last 20 commit messages (what's changed recently)

Propose edits to handoff.md so it reflects the current state of the POC.
Write the updated file. Show me the diff.