Skip to main content

​
Hooks

The SDD Plugin includes 4 automated hooks that run during your Claude Code sessions. These hooks enforce guardrails, inject context, and maintain pipeline state without manual intervention.
All hooks are configured in hooks/hooks.json and run automatically — no setup required.

​
H1: Session start pipeline injection

Trigger: At the start of every Claude Code session
Type: PreToolUse (SessionStart)
Timeout: 10 seconds
Script: scripts/sdd-session-start.sh

​
Purpose

Injects current pipeline status into the session context so Claude always knows:
  • Which stage you’re at
  • How many stages are complete (e.g., “3/7 done”)
  • Which stages are stale, running, or have errors
  • What the next recommended action is

​
Example output

SDD Pipeline [test-planner]: 3/7 done. Next: test-planner

SDD Pipeline [task-implementer]: 5/7 done. STALE: spec-auditor. Next: spec-auditor
If no pipeline-state.json exists, the hook reports a fresh pipeline and recommends running /sdd:setup.

​
H2: Upstream artifact immutability guard

Trigger: Before any Edit or Write operation
Type: PreToolUse (Edit, Write)
Timeout: 5 seconds
Script: scripts/sdd-upstream-guard.sh

​
Purpose

Enforces Article 4 of the SDD Constitution: downstream skills cannot modify upstream artifacts. This maintains traceability integrity by preventing, for example, task-implementer from editing requirements or specs.

​
Immutability rules

When a stage is running, these paths are prohibited:
Running stageProhibited paths
test-plannerrequirements/, spec/, audits/
plan-architectrequirements/, spec/, audits/, test/
task-generatorrequirements/, spec/, audits/, test/, plan/
task-implementerrequirements/, spec/, audits/, test/, plan/, task/
spec-auditorrequirements/ (spec/ is allowed in Fix mode)
specifications-engineerrequirements/

​
Exceptions

  • req-change skill: Can modify requirements/ and spec/ (lateral skill)
  • pipeline-state.json: Always allowed (infrastructure, not artifact)
  • No running stage: Permissive mode (allow all)
  • .claude/, changes/, feedback/: Always allowed
If a prohibited write is attempted, the hook returns a denial with a message explaining the Art. 4 violation.

​
H3: Context augmentation hook

Trigger: Before any Grep, Glob, Read, Edit, or Write operation
Type: PreToolUse (Grep, Glob, Read, Edit, Write)
Timeout: 5 seconds
Script: hooks/sdd-augment-hook.js

​
Purpose

Automatically injects SDD traceability context when you search, read, or edit files. This hook enriches file operations with information about which requirements, use cases, and tasks a file implements.

​
How it works

The hook matches files by:
  • File path — Checks codeRefs in the traceability graph
  • Artifact ID patterns — Regex matching for REQ-, UC-, TASK-* annotations
  • Symbols — Code intelligence (when available via /sdd:code-index)

​
Context injected

For each matched file, the hook adds:
  • Traceability chain (REQ → UC → WF → API → BDD → INV → ADR → TASK → CODE)
  • Coverage status (Complete, In Progress, Specified, Not Started)
  • Last commit SHA (if Git repository)
  • Callers/callees/processes (when code intelligence is available)

​
Silent failure

If the traceability graph doesn’t exist or the hook encounters an error, it silently returns no context. Tool calls are never blocked.
Run /sdd:dashboard first to generate the traceability graph that this hook reads.

​
H4: Pipeline state auto-updater

Trigger: After any successful Write operation
Type: PostToolUse (Write)
Timeout: 10 seconds
Async: true
Script: scripts/sdd-pipeline-state-updater.sh

​
Purpose

Automatically updates pipeline-state.json when artifacts are written to pipeline directories. This keeps the pipeline state synchronized without manual intervention.

​
Detection logic

When a file is written, the hook maps the path to a pipeline stage:
PathMaps to stage
requirements/*requirements-engineer
spec/*specifications-engineer
audits/*spec-auditor
test/*test-planner
plan/*plan-architect
task/*task-generator
src/, tests/task-implementer
feedback/*task-implementer

​
State transitions

The hook only transitions stages from pending or stale to running. It does not mark stages as done — that’s the skill’s responsibility.
If pipeline-state.json doesn’t exist, the hook initializes it with all stages set to pending.

​
Hook configuration

All hooks are defined in hooks/hooks.json. The configuration uses matchers to determine when hooks fire: 
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "SessionStart",
        "hooks": [{ "type": "command", "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/sdd-session-start.sh", "timeout": 10000 }]
      },
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/sdd-upstream-guard.sh", "timeout": 5000 }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [{ "type": "command", "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/sdd-pipeline-state-updater.sh", "timeout": 10000, "async": true }]
      }
    ]
  }
}
Hooks are stateless and idempotent — they can be run multiple times safely without side effects.

Agents

Learn about the 8 specialized agents

Guardrails

Overview of automated guardrails

Build docs developers (and LLMs) love

Get started for freeTalk to us