Language / Język: English · Polski

Coding Higher Mind — PG (PROMPT-GUARD) for Claude Code

Version v1.8.0 — last updated 2026-10-14. 15 public releases since 1.0.0 (2026-09-12). Every system needs time to mature: this one is young, changes fast and is honest about its limits (known limits).

Quality gates, reviewer agents, routines and an anti-hallucination protocol for Claude Code and Claude Desktop — enforced by events, not by willpower.

The name comes from the author’s other long project, a free guidebook on practical spirituality (kamiljan.com): practice over belief. A rule you intend to follow is a belief. A gate that fires on an event is a practice. This repository is the practice — the “higher mind” that sits above every coding session and refuses to let a good intention be the only safeguard.

PG is the working system behind one person’s software company: ~40 production repositories (SaaS for workshops, a marketplace, shops, rental systems, client sites) written almost entirely by AI coding agents, with a human owning the spec, the review and the deploy. It grew out of one audit finding: every rule written as prose was broken at scale (0 architecture decision records in 6 of 7 repos, changelog 105 commits behind, code review invoked in 2.5 % of sessions, 79 % of commits pushed straight to main). So the rules moved from prose into hooks, git gates, CI and reviewer agents with fresh context — and every gate got a test that proves it blocks its own case.

This repository is that system, exported and sanitized so you can install it on your own machine in five minutes. A long-form description with diagrams lives at kamiljan.com/claude.

Language note. PG was written in Polish, its author’s working language. What you interact with is bilingual: the prompt protocol injected into every session has a full English version (PG_LANG=en, set automatically by the installer from your machine locale, override with --lang=en|pl), every git-gate and command-guard block message carries an English BLOCKED: … line with the escape hatch, and the installer, this README and docs/ are English. The doctrine documents and reviewer rubrics are still Polish — the model reads them fine; translate in place if your team needs to, pull requests welcome.

---

What you get

Counted, not estimated: 409 files (export of 2026-10-14); the rest as counted for 1.4.0 (2026-10-05): ~45 800 lines, 43 tools, 15 test suites, 11 hooks, 3 git hooks, 9 reviewer agents, 170 scars, 26 template files, 18 skills, 7 Claude Code routines + 7 desktop routines.

---

Just the skills (1 minute)

18 working skills (architecture trade-offs, multi-department review, debugging, agent loops, frontend patterns, writing) as a Claude Code plugin. No hooks, no settings changes:

claude plugin marketplace add kamiljan11/coding-higher-mind
claude plugin install higher-mind-skills@coding-higher-mind

Inside a session the same works as /plugin marketplace add kamiljan11/coding-higher-mind. Skills run as /higher-mind-skills:, and Claude also picks them up by their descriptions. One skill only: copy skills// into ~/.claude/skills/. The full list with one-line summaries is in skills.json and on kamiljan.com/claude.

Install the whole system (5 minutes)

Requirements: Node ≥ 20, git, Claude Code. Optional: Python 3 + ruff + pyright (Python repos), gitleaks (CI runs it anyway), PostgreSQL client tools (backup drill).

git clone https://github.com/kamiljan11/coding-higher-mind.git
cd coding-higher-mind
node install.mjs --dry-run     # shows the plan, touches nothing
node install.mjs               # copies into ~/.claude, merges hooks into settings.json, appends the PG block to CLAUDE.md
node install.mjs --yes         # ...and sets `git config --global core.hooksPath ~/.claude/git-hooks`

What the installer promises (read install.mjs, it is about 210 lines):

• Never overwrites a file you changed unless --force (then a backup goes to ~/.claude/_pg-backup-/); differing package versions are written next to yours as *.pg-new.
• settings.json: merges the hooks key — your other hooks and keys stay; paths are absolute for your machine.
• CLAUDE.md: appends the PG block between /; re-running replaces only that block.
• Git hooks are opt-in (--yes); without it you get the per-repo command instead.
• Ends with node ~/.claude/bin/pg-selftest.js — green output is the proof. Open a new Claude Code session; the first non-trivial prompt shows [PROMPT-GUARD].

Uninstall: node uninstall.mjs (removes hook registrations and the CLAUDE.md block; prints the rm command for the files — deleting is your call).

Windows works through Git Bash (hooks are sh), macOS and Linux natively. Only ~/.claude is supported as the install root, because Claude Code reads it from there.

---

The life of a change

prompt ──▶ prompt-guard.js (protocol) ──▶ edit ──▶ post-edit-check.js (lint/types) ──▶ git commit ──▶ pre-commit
(secrets · base-check · dup-literals · dep-exists · commented-code · todo-ledger · pii-inventory · sql-lint · workflow-lint · ruff/pyright)
──▶ git push ──▶ pre-push (no direct main · diff-size · module-boundaries · foreign-branch warning)
──▶ PR ──▶ CI from templates/ (quality · mutation on changed files · gitleaks · optional Claude review)
──▶ bin/mas_merge_prs.py (merge only when checks ran on the CURRENT merge-ref) ──▶ bin/wait_prod_multi.py (200 from the real production domain)
session end ──▶ stop-gate.js: tier from the diff; T2+ = reviewer departments (skill pg-review) or the session does not close

Any red result stops the change right there. Every escape hatch is a named env var (ALLOW_MAIN=1, ALLOW_LARGE_DIFF=1, ALLOW_BOUNDARIES=1, …). Since 1.2.0 the agent cannot set it on its own: the command guard lets it through only after you typed allow ALLOW_X as the whole chat message. The decision is logged to ~/.claude/logs/gates.jsonl and surfaces in the weekly guard-health audit.

---

Three ideas the whole thing rests on

1. Gates, not prose. A rule the agent can forget is not a rule. Everything that matters fires on an event (prompt, edit, command, stop, commit, push, CI) and has a test proving it blocks its own case. Rules that only exist in a document are checked by bin/pg-rule-coverage.js — a rule without a gate fails the audit.
2. Scar → gate. pg/cases.md holds 170 real failures from the fleet (RLS gate on the wrong state, a fallback that silently changed the seller on an invoice, green CI on a stale merge-ref that broke main, a hook that read stdin twice and never ran, …). Every checklist item and every gate cites the scar it came from — the Google SRE rule. Postmortems end with a new gate or a new scar, never with “be more careful”.
3. Proof, not prose. “Done” means a command, an exit code and an observed state. Reports end with VERIFIED (evidence cited) / UNVERIFIED (what is missing) / FAILED (what happened). This matters most where agents are known to overstate success (75.8 % of agent “successes” in one benchmark were claims without evidence) and to fold under pushback. See docs/VERIFIED-PROTOCOL.md — it is the single most useful thing to paste into any Claude Cowork or scheduled-task prompt.

---

Risk tiers (computed from the diff, never from the prompt)

Per-repo overrides live in the repo’s CLAUDE.md: pg.tier_floor: T2, pg.phase: prototype|poc|mvp|production (a prototype is capped at T1 — proportionality; promoting to production requires a production-readiness review), pg.qa_url: (makes the QA department mandatory on T3 with UI).

---

Map of the repository

---

Make it yours

Everything that was specific to the author’s machine was removed or made configurable — see docs/CUSTOMIZE.md. The short list:

• ~/.claude/CLAUDE.md — write your own rules above the PG block; the block itself is replaced on update.
• MAS_MEMORY_DIR — folder of markdown notes injected at session start by hooks/session-context.js (default ~/.claude/memory; missing files are skipped).
• GITHUB_OWNER + a token in the environment — for the fleet tools (bin/mas_*.py). Use a secret manager that injects env vars (infisical run --, op run --, doppler run --); PG blocks secrets typed into a command line.
• Per repo: pg.tier_floor, pg.phase, the module-boundary block in docs/ARCHITECTURE.md, the QA matrix in docs/CRITICAL-PATHS.md, docs/PRIVACY.md.
• Reviewer rubrics in agents/*.md — add your own scars to pg/cases.md and reference their rule_id from the rubric.

---

Honest limits

• Auto-merge rests on a probabilistic proof: one LLM reviewer in CI (open to prompt injection from the diff, no k-of-n) plus a local review; an agent with push rights can change the workflow in an abandoned PR and read the secret. Read pg/known-limits.md before switching it on; the kill switch is one file.
• Built and proven at SME scale (dozens of repos, one owner, tens of thousands of lines), not at hyperscale.
• Messages are in Polish today.
• Reviewer agents cost tokens (T2 ≈ 4×, T3 ≈ 8–10× the cost of one diff review); zero-token gates run first so agents never see red lint.
• Some gates depend on the repo having what they check (a tsconfig.json, a docs/ARCHITECTURE.md block, a CRITICAL-PATHS.md); without it they skip and log the skip.
• The system was written with AI agents under the same gates it describes. It is not finished; it is engineered against its own failure modes, in the open.

Credits

The stack layers and the 131 base tools in skills/architecture-advisor/assets/stack-picker.html follow Arjay McCandless’s public Stack Picker (arjaythedev.com/stack-picker); tool names belong to their owners, the descriptions and market options are this project’s.

License

MIT — © 2026 Kamil Jan. Sources of the research behind the rules are cited inline in prompt-protocol.md, pg/*.md and hooks/prompt-guard.js.

Polska wersja tego README: README.pl.md.