Hooks

Where it lives

• hooks/detect-legacy-pipeline.shRunsGitHub ↗
  Read the script

  #!/usr/bin/env bash
  # HCF SessionStart hook — surfaces a legacy .claude/pipeline.md and urges migration.
  # Self-silences (exit 0, no output) when there is no legacy file, so it goes quiet
  # the moment /hcf:project-update removes the file. Enforcement of the block lives in the
  # PreToolUse / UserPromptExpansion gates; this hook is the up-front heads-up.
  
  DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
  . "$DIR/pipeline-status.sh"
  
  status="$(pipeline_status)"
  [ "$status" = "none" ] && exit 0
  
  if [ "$status" = "custom" ]; then
    note="A legacy .claude/pipeline.md with CUSTOM pipeline configuration was found. HCF no longer reads it (agents enroll via frontmatter), so those customizations are currently INACTIVE. HCF planning is gated until you migrate: plan-create and plan-orchestrate are BLOCKED while this file exists. Strongly urge the user to run /hcf:project-update now (it is command-only, so they type it themselves) to migrate the customizations into agent frontmatter and remove the stale file. Surface this immediately, not as a passing note. Include this link so they can read about the change: https://github.com/markshust/hcf#pipeline"
  else
    note="A legacy .claude/pipeline.md was found — a stale file from an older HCF version. HCF now enrolls agents via frontmatter and no longer reads it. HCF planning is gated until you migrate: plan-create and plan-orchestrate are BLOCKED while this file exists. Strongly urge the user to run /hcf:project-update now (it is command-only, so they type it themselves) to remove the stale file and bring the project onto the current model. Surface this immediately, not as a passing note. Include this link so they can read about the change: https://github.com/markshust/hcf#pipeline"
  fi
  
  printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"HCF migration required: %s"}}\n' "$note"
  

• hooks/discover-hooks.shGitHub ↗
  Read the script

  #!/usr/bin/env bash
  # HCF hook discovery — deterministic enumeration of hook-enrolled agents.
  #
  # Why this exists: HCF's discovery routine used to be prose instructions that
  # the in-session model executed by improvising a bash glob loop. Different
  # sessions wrote different scripts, and a syntax error in one of them crashed
  # mid-enumeration; the partial output was consumed as complete, every hook
  # resolved empty, and the empty-hook silence rule made the failure invisible.
  # See https://github.com/markshust/hcf/issues/4.
  #
  # This script is the single implementation of HOOKS.md's Discovery Routine.
  # Callers run it and read its output; nobody enumerates agent files by hand.
  #
  # Usage:
  #   discover-hooks.sh                     # all 8 hooks (by-hand debugging view)
  #   discover-hooks.sh --hook=<name>       # one hook; empty prints nothing
  #   discover-hooks.sh --json              # machine-readable
  #   discover-hooks.sh --fingerprint       # stable enrollment digest
  #   discover-hooks.sh --expect=<value>    # halt if enrollment drifted
  #
  # Exit codes:
  #   0  success (including a legitimately empty hook)
  #   1  runtime error (plugin agents/ dir or project root unresolvable)
  #   2  bad arguments (incl. a malformed --expect value)
  #   3  enrollment validation failure (invalid phase or mode in an agent file)
  #   4  enrollment drift (--expect mismatch)
  
  set -o pipefail
  
  PROG="discover-hooks"
  VALID_HOOKS="pre-plan post-plan pre-implementation pre-batch post-batch post-implementation pre-commit post-commit"
  VALID_MODES="single batch"
  FP_PREFIX="discover-hooks-fingerprint"
  FP_VERSION="1"
  
  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
  PLUGIN_AGENTS="$SCRIPT_DIR/../agents"
  RESOLVER="$SCRIPT_DIR/resolve-project-dir.sh"
  # PROJECT_DIR and LOCAL_AGENTS are resolved after argument parsing, so --help
  # stays answerable from anywhere. See the resolution block below.
  
  HOOK_FILTER=""
  WANT_JSON=""
  WANT_FINGERPRINT=""
  EXPECT=""
  HAVE_EXPECT=""
  
  warn() { printf '%s: warning: %s\n' "$PROG" "$1" >&2; }
  err()  { printf '%s: error: %s\n'   "$PROG" "$1" >&2; }
  
  usage() {
    cat <<'EOF'
  discover-hooks.sh — resolve which agents run at an HCF hook point.
  
    --hook=<name>     Restrict output to one hook. Prints nothing when the hook
                      resolves empty (callers treat exit 0 + empty stdout as
                      "empty hook"). Omit to print all 8 hooks with explicit
                      empty markers, which is the by-hand debugging view.
    --json            Emit JSON instead of the human table.
    --fingerprint     Print a stable digest of the full resolved enrollment
                      across all 8 hooks, then exit.
    --expect=<value>  Compare current enrollment against a previously captured
                      fingerprint. Exits 4 if it changed. Accepts either the
                      full versioned line or the bare 64-hex digest.
    -h, --help        Show this help.
  
  Exit codes: 0 success, 1 runtime error, 2 bad arguments,
              3 enrollment validation failure, 4 enrollment drift.
  EOF
  }
  
  is_valid_hook() {
    case " $VALID_HOOKS " in *" $1 "*) return 0 ;; *) return 1 ;; esac
  }
  
  is_valid_mode() {
    case " $VALID_MODES " in *" $1 "*) return 0 ;; *) return 1 ;; esac
  }
  
  while [ $# -gt 0 ]; do
    case "$1" in
      --hook=*)
        HOOK_FILTER="${1#*=}"
        if [ -z "$HOOK_FILTER" ]; then
          err "--hook requires a value; use --hook=<name>"
          exit 2
        fi
        if ! is_valid_hook "$HOOK_FILTER"; then
          err "unknown hook '$HOOK_FILTER'"
          err "  valid hooks: $VALID_HOOKS"
          exit 2
        fi
        ;;
      --hook)
        err "--hook must be given as --hook=<name>, not as two arguments"
        exit 2
        ;;
      --expect=*)
        EXPECT="${1#*=}"
        HAVE_EXPECT=1
        ;;
      --expect)
        err "--expect must be given as --expect=<value>, not as two arguments"
        exit 2
        ;;
      --json)        WANT_JSON=1 ;;
      --fingerprint) WANT_FINGERPRINT=1 ;;
      -h|--help)     usage; exit 0 ;;
      *)
        err "unknown argument '$1'"
        err "  run with --help for usage"
        exit 2
        ;;
    esac
    shift
  done
  
  if [ -n "$WANT_FINGERPRINT" ] && [ -n "$HAVE_EXPECT" ]; then
    err "--fingerprint and --expect are mutually exclusive"
    exit 2
  fi
  
  # --- frontmatter parsing ----------------------------------------------------
  #
  # Anchored at start-of-line inside the FIRST `---` block only, so a commented
  # `# phase:` key never enrolls an agent. This matters concretely: the bundled
  # standards-enforcer ships dormant with its phase commented out, and an
  # unanchored match would silently enable it for every HCF user.
  
  has_frontmatter() {
    # NOTE: awk's `exit` runs the END block, so the result is carried in a flag
    # rather than as an exit status from inside the body.
    LC_ALL=C awk '
      { sub(/\r$/, "") }
      NR == 1 { if ($0 != "---") { bad = 1; exit } ; next }
      /^---$/ { found = 1; exit }
      END { if (found && !bad) exit 0; exit 1 }
    ' "$1"
  }
  
  # fm_get <file> <key> — echoes the trimmed, unquoted, comment-stripped value.
  fm_get() {
    LC_ALL=C awk -v key="$2" '
      { sub(/\r$/, "") }
      NR == 1 { next }
      /^---$/ { exit }
      index($0, key ":") == 1 {
        val = substr($0, length(key) + 2)
        sub(/^[ \t]+/, "", val)
        first = substr(val, 1, 1)
        if (first == "\"" || first == "'"'"'") {
          val = substr(val, 2)
          i = index(val, first)
          if (i > 0) val = substr(val, 1, i - 1)
        } else {
          # Strip a trailing inline comment. HOOKS.md and README.md both document
          # enrollment as `phase: post-plan   # enrolls this agent...`, so this is
          # the shape a copy-pasting user actually produces.
          sub(/[ \t]*#.*$/, "", val)
        }
        sub(/[ \t]+$/, "", val)
        print val
        exit
      }
    ' "$1"
  }
  
  # --- enumeration ------------------------------------------------------------
  
  names=()
  phases=()
  orders=()
  modes=()
  origins=()
  
  VALIDATION_ERRORS=0
  
  index_of_name() {
    local target="$1" i=0 n=${#names[@]}
    while [ "$i" -l

• hooks/gate-command.shRunsGitHub ↗
  Read the script

  #!/usr/bin/env bash
  # HCF UserPromptExpansion hook (matcher: plan-create|plan-orchestrate). Covers the
  # direct slash-command path (/plan-create, /plan-orchestrate) that PreToolUse does
  # NOT see. The matcher already scopes this to those commands, so we only need to
  # check for a legacy .claude/pipeline.md and block until it is migrated.
  
  DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
  . "$DIR/pipeline-status.sh"
  
  [ "$(pipeline_status)" = "none" ] && exit 0
  
  reason="HCF: this project still has a legacy .claude/pipeline.md. HCF now enrolls agents via frontmatter and no longer reads that file. Run /hcf:project-update first to migrate it into agent frontmatter and remove the stale file, then re-run this command. Share this link so they can read about the change: https://github.com/markshust/hcf#pipeline"
  printf '{"decision":"block","reason":"%s"}\n' "$reason"
  

• hooks/gate-skill.shRunsGitHub ↗
  Read the script

  #!/usr/bin/env bash
  # HCF PreToolUse hook (matcher: Skill). Covers the path where Claude invokes the
  # Skill tool. Denies plan-create / plan-orchestrate while a legacy
  # .claude/pipeline.md exists, forcing migration via /hcf:project-update first.
  # Everything else (including /hcf:project-update itself) is left untouched.
  
  DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
  . "$DIR/pipeline-status.sh"
  
  input="$(cat)"
  
  # Only gate the HCF planning skills. project-update and all other skills pass through.
  case "$input" in
    *plan-create*|*plan-orchestrate*) ;;
    *) exit 0 ;;
  esac
  
  [ "$(pipeline_status)" = "none" ] && exit 0
  
  reason="HCF: this project still has a legacy .claude/pipeline.md. HCF now enrolls agents via frontmatter and no longer reads that file, so it must be migrated before the planning workflow can run. Tell the user to run /hcf:project-update first — it migrates any customizations into agent frontmatter and removes the stale file — then retry. Do not attempt to plan or orchestrate until the file is gone. Share this link so they can read about the change: https://github.com/markshust/hcf#pipeline"
  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"%s"}}\n' "$reason"
  

• hooks/pipeline-status.shGitHub ↗
  Read the script

  #!/usr/bin/env bash
  # Shared helper for HCF hooks. Classifies a project's legacy .claude/pipeline.md.
  # Sourced by the other hook scripts (no exec bit needed).
  #
  # pipeline_status echoes exactly one of:
  #   none    - no .claude/pipeline.md present
  #   default - present but only enrolls the shipped default (devils-advocate, or
  #             nothing active); frontmatter already reproduces it, so nothing is lost
  #   custom  - present with custom enrollment; those customizations are INACTIVE
  #             because HCF now enrolls agents via frontmatter
  
  pipeline_status() {
    local project_dir pipeline names count
    project_dir="${CLAUDE_PROJECT_DIR:-$PWD}"
    pipeline="$project_dir/.claude/pipeline.md"
  
    [ -f "$pipeline" ] || { echo none; return; }
  
    # "Active" agents = non-commented "- name" bullets (HTML-commented lines inactive).
    names="$(grep -E '^[[:space:]]*-[[:space:]]+[^[:space:]]' "$pipeline" 2>/dev/null \
      | grep -v '<!--' \
      | sed -E 's/^[[:space:]]*-[[:space:]]+//; s/[[:space:]].*$//')"
    count="$(printf '%s\n' "$names" | grep -c '[^[:space:]]')"
  
    if [ "$count" = "0" ] || { [ "$count" = "1" ] && printf '%s' "$names" | grep -qx 'devils-advocate'; }; then
      echo default
    else
      echo custom
    fi
  }
  

• hooks/resolve-plans-dir.shGitHub ↗
  Read the script

  #!/usr/bin/env bash
  # HCF plans-directory resolution — where this project keeps its plan folders.
  #
  # Defaults to <project>/.claude/plans. A project may override it with an
  # optional, user-owned .claude/hcf.json:
  #
  #   { "plansDir": "docs/plans" }
  #
  # No skill creates or modifies that file. Its absence is the normal case.
  #
  # Two deliberate departures from a naive one-liner, both the same lesson this
  # repo keeps relearning (see issue #4 and the 2.1.1 fix):
  #
  #   1. No `jq`. A `jq ... || echo <default>` pipeline turns a missing jq — the
  #      norm on Debian minimal and Alpine — into a silent fallback: you set
  #      plansDir, you get .claude/plans, and nothing says why.
  #   2. A malformed plansDir is an error, not a fallback. Writing plans to a
  #      directory the project did not ask for is worse than refusing, and it
  #      matches how an invalid `phase` already aborts discovery.
  #
  # The project root comes from resolve-project-dir.sh, so the answer does not
  # depend on the working directory. Output is absolute for the same reason:
  # callers pass it to subagents whose cwd is not knowable from here.
  #
  # Usage:
  #   resolve-plans-dir.sh          # print the absolute plans directory
  #   . resolve-plans-dir.sh        # define hcf_resolve_plans_dir
  #
  # Exit codes:
  #   0  resolved; the absolute path is on stdout
  #   1  unresolvable project root, or an invalid plansDir value
  
  HCF_PLANS_DIR_DEFAULT=".claude/plans"
  
  _hcf_plans_script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
  if [ ! -f "$_hcf_plans_script_dir/resolve-project-dir.sh" ]; then
    printf 'resolve-plans-dir: error: resolve-project-dir.sh not found alongside this script\n' >&2
    return 1 2>/dev/null || exit 1
  fi
  # shellcheck source=hooks/resolve-project-dir.sh
  . "$_hcf_plans_script_dir/resolve-project-dir.sh"
  
  # Reads the plansDir value out of a flat JSON object without a JSON parser.
  # Deliberately narrow: one key, a string value, no escapes. Anything it cannot
  # read is reported by the caller as absent, which falls back to the default.
  #
  # Line-oriented, so it does not understand nesting: a plansDir buried inside
  # another object would be read as if top-level. hcf.json is a flat file the user
  # writes by hand and nesting this key means nothing, so that is a documented
  # limit rather than a reason to put a JSON parser in bash. Duplicate keys take
  # the last, and a padded value keeps its padding — both match what `jq` returns.
  hcf_read_plans_dir_key() {
    sed -n 's/.*"plansDir"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$1" 2>/dev/null | head -1
  }
  
  # Prints the absolute plans directory on stdout. Returns non-zero with a
  # message on stderr when the project root or the configured value is unusable.
  hcf_resolve_plans_dir() {
    local project status config value
  
    project="$(hcf_resolve_project_dir)"
    status=$?
    if [ "$status" -eq 2 ]; then
      printf 'resolve-plans-dir: error: CLAUDE_PROJECT_DIR is set to '\''%s'\'', which is not a directory\n' "${CLAUDE_PROJECT_DIR:-}" >&2
      return 1
    elif [ "$status" -ne 0 ]; then
      printf 'resolve-plans-dir: error: cannot determine the project root from '\''%s'\''\n' "$PWD" >&2
      printf 'resolve-plans-dir: error:   run from inside the project, or set CLAUDE_PROJECT_DIR to its path\n' >&2
      return 1
    fi
  
    config="$project/.claude/hcf.json"
    value=""
  
    if [ -f "$config" ]; then
      # Absent key and unreadable value are the same case on purpose: fall back
      # quietly. A present-but-empty value is a typo, and is reported below.
      if grep -q '"plansDir"' "$config" 2>/dev/null; then
        value="$(hcf_read_plans_dir_key "$config")"
        if [ -z "$value" ]; then
          printf 'resolve-plans-dir: error: '\''%s'\'' sets an empty plansDir\n' "$config" >&2
          printf 'resolve-plans-dir: error:   give it a relative path, or remove the key to use %s\n' "$HCF_PLANS_DIR_DEFAULT" >&2
          return 1
        fi
      fi
    fi
  
    if [ -z "$value" ]; then
      value="$HCF_PLANS_DIR_DEFAULT"
    fi
  
    # Containment: the plans directory belongs to the project. Escaping it would
    # scatter plan folders outside the repo they document.
    case "$value" in
      /*)
        printf 'resolve-plans-dir: error: plansDir '\''%s'\'' must be relative to the project root, not absolute\n' "$value" >&2
        printf 'resolve-plans-dir: error:   set it in %s\n' "$config" >&2
        return 1
        ;;
      ..|../*|*/..|*/../*)
        printf 'resolve-plans-dir: error: plansDir '\''%s'\'' must not contain a '\''..'\'' segment\n' "$value" >&2
        printf 'resolve-plans-dir: error:   set it in %s\n' "$config" >&2
        return 1
        ;;
    esac
  
    printf '%s\n' "$project/$value"
  }
  
  if [ "${BASH_SOURCE[0]}" = "$0" ]; then
    hcf_resolve_plans_dir || exit 1
  fi
  

• hooks/resolve-project-dir.shGitHub ↗

All 7 scripts are listed above. The source is inlined for 6 of them, starting with whatever hooks.json actually runs. See all of them in the repo.

Read the script before you install anything that runs on your machine. This is the one part of a plugin that acts without being asked.