docs: expand Claude maintainer guidance

Author: renecannao

CONTRIBUTING.md

@@ -24,6 +24,10 @@ The following guidelines want to help and simplify the process of contributing t
 
 If you use Claude Code for maintenance work in this repo, read `docs/coding/claude-code-agent.md` first. It documents the repo-local `.claude/` skills, hook behavior, and required smoke tests.
 
+- The repo-local `.claude/` workflow is authoritative for Claude Code tasks in this repository.
+- Run `./test/claude-agent-tests.sh` when you edit `.claude/`, `docs/coding/claude-code-agent.md`, `scripts/install_claude_db_skills.sh`, or `tools/claude-skills/db-core-expertise/`.
+- If you update `tools/claude-skills/db-core-expertise/`, rerun `./scripts/install_claude_db_skills.sh` and `~/.claude/skills/db-core-expertise/scripts/smoke-test.sh` so the installed reusable skill stays in sync.
+
 ## Principles
 
 1. Contributions should follow the classic GitHub workflow, i.e. forking, cloning, then submitting a Pull Request (PR)

docs/coding/claude-code-agent.md

@@ -23,6 +23,13 @@ Run the project-local Claude asset smoke tests with:
 
 These tests validate the repo-local Claude files, hook behavior, and completion policy.
 
+## Troubleshooting
+
+- If Claude blocks before a shell command runs, the pre-tool hook likely denied a destructive git command. Use a non-destructive alternative instead of trying to bypass the hook.
+- If Claude blocks at completion time, read the reported missing verification or docs requirement, run the exact command it names, and include the required `Changed`, `Verification`, `Edge Cases`, and `Docs Updated` sections in the final response.
+- Verification history is stored in `.claude/state/verification-log.jsonl`. If the log becomes stale during local experimentation, delete `.claude/state/` and rerun the relevant verification commands.
+- If you change `tools/claude-skills/db-core-expertise/` or `scripts/install_claude_db_skills.sh`, rerun the installer and the installed smoke test so the user-level copy stays aligned with the repo.
+
 ## Expected maintainer flow
 
 1. Start non-trivial tasks with `/dbdeployer-maintainer`.
@@ -41,6 +48,21 @@ Install the reusable MySQL/PostgreSQL/ProxySQL reference skill with:
 
 The installed user-level skill is named `/db-core-expertise`. Use it when the task depends on DB semantics, packaging assumptions, replication edge cases, or live upstream verification.
 
+## Repo-local vs reusable
+
+- Update `.claude/`, `.claude/rules/`, `.claude/hooks/`, or this guide when the change is specific to `dbdeployer` workflow, completion policy, verification gates, or maintainer behavior inside this repo.
+- Update `tools/claude-skills/db-core-expertise/` when the change is generic DB knowledge that should remain reusable across repositories, such as MySQL/PostgreSQL/ProxySQL semantics, verification heuristics, or documentation style.
+- Keep repo-specific policy out of the reusable skill. If you change the reusable layer, rerun the installer with `./scripts/install_claude_db_skills.sh` and then run `~/.claude/skills/db-core-expertise/scripts/smoke-test.sh` so the installed copy matches the repo.
+
+## Task recipes
+
+- Provider or CLI behavior change:
+  Start with `/dbdeployer-maintainer`, use `/db-correctness-review` before finishing, run `go test ./...` or `./test/go-unit-tests.sh`, and update the relevant docs if user-visible behavior changed.
+- Docs-only or reference-only change:
+  Update the smallest truthful docs surface, use `/docs-reference-sync`, and avoid claiming behavior changes unless you also verified the underlying code path.
+- Claude workflow or reusable skill change:
+  Run `./test/claude-agent-tests.sh`. If the change touched `tools/claude-skills/db-core-expertise/` or the installer, rerun the installer and the installed smoke test before finishing.
+
 ## Completion requirements
 
 Final responses should include:

test/claude-agent-tests.sh

@@ -158,7 +158,17 @@ require_string .claude/skills/docs-reference-sync/SKILL.md README.md
 require_string .claude/skills/docs-reference-sync/SKILL.md CONTRIBUTING.md
 require_string docs/coding/claude-code-agent.md ./test/claude-agent-tests.sh
 require_string docs/coding/claude-code-agent.md ./scripts/install_claude_db_skills.sh
+require_string docs/coding/claude-code-agent.md 'Troubleshooting'
+require_string docs/coding/claude-code-agent.md 'verification-log.jsonl'
+require_string docs/coding/claude-code-agent.md 'Task recipes'
+require_string docs/coding/claude-code-agent.md 'Provider or CLI behavior change'
+require_string docs/coding/claude-code-agent.md 'Docs-only or reference-only change'
+require_string docs/coding/claude-code-agent.md 'Repo-local vs reusable'
+require_string docs/coding/claude-code-agent.md 'tools/claude-skills/db-core-expertise/'
+require_string docs/coding/claude-code-agent.md 'rerun the installer'
 require_string CONTRIBUTING.md docs/coding/claude-code-agent.md
+require_string CONTRIBUTING.md 'repo-local `.claude/` workflow'
+require_string CONTRIBUTING.md 'If you update `tools/claude-skills/db-core-expertise/`'
 require_string tools/claude-skills/db-core-expertise/SKILL.md db-core-expertise
 require_string tools/claude-skills/db-core-expertise/verification-playbook.md '`go test ./...` or `./test/go-unit-tests.sh`'
 require_string tools/claude-skills/db-core-expertise/verification-playbook.md 'sandbox-test'