Project Context Maintainer Hook

A small, global Git hook installer that runs the project-context skill after meaningful commits. It generates/updates:

• docs/project_notes/operating_brief.md
• docs/project_notes/key_facts.md
• docs/project_notes/adrs.md
• docs/project_notes/bugs.md
• docs/project_notes/worklog.md
• AGENTS.md (and CLAUDE.md if present)

Notes are maintained automatically by a post-commit maintainer and auto-committed with a docs: message.

Files

• context-hook.ps1 — main entry point (install/uninstall/run/test)
• context-hook.cmd — convenience wrapper for Windows
• README.md — this file

Prerequisites

• git
• pwsh (PowerShell 7+) or Windows PowerShell
• codex CLI available on PATH (or set CODEX_BIN)
• project-context skill installed at C:\Users\Jordan\.codex\skills\project-context

Quick Start

From any repo root:

context-hook install

This will:

• create .githooks/
• generate .githooks/post-commit + .githooks/post-commit.ps1
• set core.hooksPath to .githooks

Commands

context-hook install
context-hook uninstall
context-hook run
context-hook test

• install generates the hook in the current repo
• uninstall removes the hook and unsets core.hooksPath (if it was .githooks)
• run runs the maintainer manually for the current repo
• test installs and validates the generated hook

Environment Variables

• CODEX_BIN — explicit path to codex.cmd
• CODE_HOME — Codex home directory (for skills/config)
• MAINTAINER_SKIP=1 — skip maintainer on this commit
• MAINTAINER_ASYNC=0 — force synchronous mode (default is async)
• MAINTAINER_HOOK_ECHO=1 — echo hook logs to stdout

Skip Rules

The hook skips when:

• commit subject contains [skip maintainer]
• subject is ...
• subject starts with docs: or notes:
• subject starts with chore:, ci:, style:, refactor:, test: (including scoped variants)
• subject indicates a release or version bump
• subject indicates dependabot/renovate
• merge commits
• changes only touch .githooks/
• changes only touch docs/project_notes/ and/or AGENTS.md/CLAUDE.md
• changes only touch lockfiles
• changes are only .md files outside docs/project_notes/

Auto-Commit Behavior

After the maintainer runs, it will stage only the seven note files and commit them with:

docs: update project notes

That commit is auto-skipped by the rules above.

Troubleshooting

• Logs are written to .git/maintainer-hook.log in the target repo.
• If Codex is not found, ensure codex.cmd is on PATH or set CODEX_BIN.
• If the hook appears stuck, delete .git/maintainer-hook.lock in the repo.

Notes

• This tool is Windows-first (PowerShell). The generated post-commit shim uses pwsh when available.
• The maintainer is conservative by default; it may choose to leave notes unchanged if changes are not significant.