Hooks
Generated guardrails that keep repeated checks close to edits
Hooks keep routine feedback close to edits.
They catch formatting, linting, starter scope, and package-manager assumptions early, so the agent does not have to remember every hygiene step manually. They sit below the skill workflow: a hook can keep repeated checks moving, while requirements clarity, browser behavior, runtime evidence, docs ingest, and review judgment still belong to the relevant skills.
punks scaffold setup writes shared hook files under .agents/hooks/* and records managed output in .devpunks/scaffold-manifest.json. Hook behavior follows selected packs and detected repo facts.
Session-start scaffold hooks run dp check. The command is read-only: it detects CLI executable drift, scaffold baseline drift, managed-file drift, and pack drift, then summarizes changelog entries when available. If an operator accepts remediation, the hook guidance sends dp upgrade or dp update --write / dp update --yes to a subagent before project work continues.
The manifest makes hook drift visible. Baseline changes can be refreshed through punks update. Repo-local edits to generated hooks are reported as drift, with the manifest treated as the source of truth.
Current Hook Boundaries
- Hook commands infer the target repo package manager from
packageManagerfirst, then lockfiles. - Pack-owned Oxlint rules are applied to nearest package/app configs during setup, creating
oxlint.config.tswith Ultracite presets where needed. - Missing lint dev dependencies are added to the owning package manifest while preserving existing versions.
- Oxfmt/Oxlint hooks are emitted only when scanned manifests declare Oxfmt or Python is detected.
- Generated hooks let Oxlint resolve the nearest config for the edited file.
- Generated lint configs extend
ultracite/oxlint/core; framework packs add Ultracite framework presets and explicit overlays only when needed.
Alignment Rule
When an agent adopts or replaces lint and format tooling, it must update the whole workflow together: package scripts, Turborepo task definitions, CI, editor/docs references, and hooks. Partial adoption creates contradictory gates.
punks update refreshes managed hook files from .devpunks/scaffold-manifest.json. It restores missing managed files, reports stale managed files, and reports pack drift without normalizing mismatched local output as the new contract.
Done Signal
Hook-related work is complete when generated hook files match selected packs, command assumptions match the repo package manager, and any lint or format tool migration has no stale entrypoints left behind.