From d9b2b8ffc87a613704f83f1612c155c15ac36f46 Mon Sep 17 00:00:00 2001 From: olekhondera Date: Sun, 15 Feb 2026 07:44:06 +0200 Subject: [PATCH] feat: add commit-docs-reminder hook to enforce checklist before commits Adds a PreToolUse Bash hook that reminds AI agents to verify status-update-checklist.md before running git commit. Also adds the corresponding constraint to RULES.md section 3. Co-Authored-By: Claude Opus 4.6 --- .claude/hooks/commit-docs-reminder.sh | 21 +++++++++++++++++++++ .claude/settings.json | 4 ++++ DOCS.md | 9 +++++++++ RULES.md | 21 +++++++++++---------- 4 files changed, 45 insertions(+), 10 deletions(-) create mode 100755 .claude/hooks/commit-docs-reminder.sh diff --git a/.claude/hooks/commit-docs-reminder.sh b/.claude/hooks/commit-docs-reminder.sh new file mode 100755 index 0000000..223d841 --- /dev/null +++ b/.claude/hooks/commit-docs-reminder.sh @@ -0,0 +1,21 @@ +#!/bin/bash +# Remind Claude to check status-update-checklist before committing +# Event: PreToolUse | Matcher: Bash +# Exit 0 = allow (non-blocking reminder) + +INPUT=$(cat) +COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty') + +if [ -z "$COMMAND" ]; then + exit 0 +fi + +# Only trigger on git commit commands (not git add, git status, etc.) +if echo "$COMMAND" | grep -qE 'git\s+commit'; then + echo "REMINDER: Before committing, verify that .claude/status-update-checklist.md was followed." >&2 + echo "If this commit changes project status, audit findings, or phase progress," >&2 + echo "you MUST synchronize: RULES.md, RECOMMENDATIONS.md, README.md, DOCS.md." >&2 + echo "If this is a code-only change with no status impact, proceed." >&2 +fi + +exit 0 diff --git a/.claude/settings.json b/.claude/settings.json index 41fe53a..59be2b0 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -16,6 +16,10 @@ { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/bash-firewall.sh" + }, + { + "type": "command", + "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/commit-docs-reminder.sh" } ] } diff --git a/DOCS.md b/DOCS.md index 17e3567..ebba155 100644 --- a/DOCS.md +++ b/DOCS.md @@ -5,6 +5,7 @@ Technical index for developers and AI agents. Use this as the entry point to all --- ## Documentation Languages + - Technical docs: English (`docs/` and subfolders). - Repository summary: `README.md` (English). New documents should be added in English unless noted. @@ -14,6 +15,7 @@ Technical index for developers and AI agents. Use this as the entry point to all ## Documentation Structure (root: `docs/`) ### 1) General Project Docs + - `docs/archetypes.md` — product archetypes and optional modules; pick what applies. - `docs/project-overview.md` — goals, target users, chosen archetype, key flows (pick relevant), non-functional requirements. - `docs/phases-plan.md` — Phase 0–4 plan with tasks across product, frontend, backend, infra, data/LLM. @@ -21,10 +23,12 @@ Technical index for developers and AI agents. Use this as the entry point to all - `docs/dev-setup.md` — local/CI setup once code exists. ### 1c) Architecture Decision Records (`/docs/adr`) + - `docs/adr/README.md` — how ADRs work. - `docs/adr/0000-template.md` — ADR template. ### 1b) LLM / AI System (`/docs/llm`) + - `docs/llm/prompting.md` — prompt structure, versioning, output schemas. - `docs/llm/evals.md` — evaluation strategy, datasets, regression gates. - `docs/llm/safety.md` — privacy, injection defenses, `reasoning_trace` policy. @@ -32,6 +36,7 @@ Technical index for developers and AI agents. Use this as the entry point to all - `docs/llm/rag-embeddings.md` — RAG/embeddings design and evaluation. ### 2) Frontend (`/docs/frontend`) + - `docs/frontend/overview.md` — frontend scope and key user journeys (depends on archetype/modules). - `docs/frontend/architecture.md` — **canonical, locked frontend decisions** (after Phase 1). - `docs/frontend/FRONTEND_ARCHITECTURE_PLAN.md` — working architecture notes; **archive/delete after Phase 1**. @@ -39,6 +44,7 @@ Technical index for developers and AI agents. Use this as the entry point to all - `docs/frontend/seo-performance.md` — performance and SEO recommendations. ### 3) Backend (`/docs/backend`) + - `docs/backend/overview.md` — backend scope (integrations, AI capability, optional pipelines/approvals/billing). - `docs/backend/architecture.md` — **canonical, locked backend decisions** (after Phase 1). - `docs/backend/api-design.md` — API resources and conventions (entities, rules, approvals, reports, billing, events). @@ -46,6 +52,7 @@ Technical index for developers and AI agents. Use this as the entry point to all - `docs/backend/payment-flow.md` — payment integration (provider-agnostic template; single source of truth for payment flows and webhooks). ### 4) Examples (`/docs/examples`) + - `docs/examples/RECOMMENDATIONS-example.md` — filled-in example of `RECOMMENDATIONS.md` for a compliance classifier (Archetype C). --- @@ -95,6 +102,7 @@ Technical index for developers and AI agents. Use this as the entry point to all - `.claude/hooks/bash-firewall.sh` — blocks destructive commands (`rm -rf /`, `git reset --hard`, etc.). - `.claude/hooks/post-edit-format.sh` — auto-formats files with Prettier after edits. - `.claude/hooks/audit-log.sh` — logs all Bash commands with timestamp to `audit.log`. +- `.claude/hooks/commit-docs-reminder.sh` — reminds to check `status-update-checklist.md` before `git commit`. - `.claude/settings.json` — hooks configuration (also: Notification, SessionStart compact context). ## GitHub Templates (`/.github`) @@ -107,6 +115,7 @@ Technical index for developers and AI agents. Use this as the entry point to all --- ## How to Use This Index + - **New to the project:** read `project-overview.md` and `phases-plan.md` first. - **Designing features:** use frontend/backend architecture docs plus API/security/payment flow specs. - **Expanding docs:** add new English `*.md` files under `docs/` and update this index with links. diff --git a/RULES.md b/RULES.md index fb7fed5..64cf893 100644 --- a/RULES.md +++ b/RULES.md @@ -31,8 +31,8 @@ conflict. 4. **Prefer minimal, surgical changes.** Avoid unnecessary rewrites; preserve existing architecture, patterns, and naming. 5. **Respect security and privacy.** - - Never include secrets, tokens, or API keys in code or output. - - Do not log, echo, or request PII unless the task requires it; minimize exposure. + - Never include secrets, tokens, or API keys in code or output. + - Do not log, echo, or request PII unless the task requires it; minimize exposure. 6. **Avoid destructive actions without consent.** Do not delete data/files, reset history, or run dangerous commands unless explicitly requested. 7. **Do not add dependencies lightly.** Introduce new packages/tools only with clear justification and after checking @@ -61,6 +61,7 @@ conflict. 2. **Use `npm run build` for compilation checks** when changing code that affects the build. Re‑run after meaningful changes. 3. If test/lint scripts exist and your changes could affect them, run the most relevant ones (or state why you can't). +4. **Before committing** — if changes affect project status, audit findings, or phase progress, read and follow `.claude/status-update-checklist.md` to synchronize all documentation files in one commit. --- @@ -68,10 +69,10 @@ conflict. - Agent profiles live in `agents/` and define role‑specific behavior (metadata + detailed instructions). - Before starting a task: - 1. Scan available profiles in `agents/`. - 2. Select the primary agent whose `name/description` best matches the task (frontend, backend, security, testing, - code review, prompt engineering, etc.). - 3. Apply that profile in addition to these core rules. + 1. Scan available profiles in `agents/`. + 2. Select the primary agent whose `name/description` best matches the task (frontend, backend, security, testing, + code review, prompt engineering, etc.). + 3. Apply that profile in addition to these core rules. - If a task spans domains, follow Section 5 for coordination. --- @@ -80,10 +81,10 @@ conflict. 1. Identify all relevant domains/agents. 2. Choose a primary agent based on the main intent: - - **Design/architecture** → architect‑type agent. - - **Implementation** → domain architect (frontend/backend). - - **Review/audit** → reviewer/security agent. - - **Prompt/workflow** → prompt‑engineer agent. + - **Design/architecture** → architect‑type agent. + - **Implementation** → domain architect (frontend/backend). + - **Review/audit** → reviewer/security agent. + - **Prompt/workflow** → prompt‑engineer agent. 3. Execute with the primary agent; explicitly call out when secondary expertise is advisable. 4. If the request mixes distinct phases (e.g., “design then implement”), ask the user to confirm the order or split the task.