smart-debugger

A disciplined AI development quality workflow for Claude Code and Codex.

It gives your AI coding agent three things it usually lacks: a routing playbook (what to do for a bug vs a feature vs a release), a quality gate (one command that runs Test + Lint + Type-check + Build), and enforcement — a Claude Code Stop hook that refuses to let the agent say "done" until the gate actually passes against the current code. No more "should be working now" without proof.

Claude-first by design: the project scaffold writes a self-contained CLAUDE.md and does not create AGENTS.md. Codex and Gemini pick the same rules up when their skills directory is symlinked to Claude's (see Codex / Gemini).

---

What's inside

Part	What it does
Global skills	Installed once into ~/.claude/skills (+ Codex). Available in every project.
quality-project scaffold	Additively merges the full quality workflow into any project folder (CLAUDE.md + Stop hook + quality gate + docs).
Quality gate	scripts/quality_gate.py — runs your project's real Test/Lint/Type-check/Build and records pass/fail.
Stop hook	.claude/hooks/quality_stop_gate.py — blocks task completion until the gate passes for the current code fingerprint.

Skills

Skill	Where	Purpose
quality-project	first-party	Scaffold the quality workflow into a project (CLAUDE.md only).
qa	first-party	Risk-based quality review of a feature or change.
handover	first-party	Production-readiness / handover assessment.
codex-debug → $debug	first-party (Codex only)	Systematic debugging for Codex. Claude uses its bundled /debug.
senior-qa	upstream	Generate unit/integration/E2E tests (React/Next.js), coverage analysis.
ship-gate	upstream	Pre-production audit; intercepts deploy commands until critical items pass.
pr-review-expert	upstream	Review PRs / diffs for security, correctness, blast radius.
runbook-generator	upstream	Generate deploy / incident / rollback runbooks.
ux-researcher-designer	upstream	Personas, journey maps, usability review.
playwright-pro	upstream plugin	Optional Claude plugin (--install-playwright-plugin).

Upstream skills are fetched at install time from alirezarezvani/claude-skills (see SOURCES.md and THIRD_PARTY_NOTICE.md).

---

Requirements

• bash, python3, git
• curl or wget (to fetch upstream skills)
• Claude Code and/or Codex CLI
• macOS / Linux / WSL

---

Install the global skills

git clone https://github.com/TimeNuthathaam/smart-debugger.git
cd smart-debugger
bash install-global-skills.sh                      # installs into ~/.claude/skills and ~/.agents/skills
# optional Playwright plugin for Claude:
bash install-global-skills.sh --install-playwright-plugin

Existing skills of the same name are backed up to <name>.backup-<timestamp>, never deleted. Restart any open Claude Code / Codex session so it reloads skills.

After install:

Claude Code:  /qa  /handover  /quality-project  /ship-gate  /senior-qa  /pr-review-expert  /runbook-generator  /ux-researcher-designer
Codex:        $debug  $qa  $handover  $quality-project ...

---

Scaffold a project

From inside Claude/Codex, invoke the quality-project skill (e.g. /quality-project ~/code/my-app), or run the script directly:

bash skills/quality-project/scaffold.sh ~/code/my-app --git

• Safe for non-empty projects: existing files are never overwritten or deleted.
• Existing .claude/settings.json and .quality/config.json gain only missing values.
• Existing .gitignore gains only missing lines.
• Existing CLAUDE.md and AGENTS.md are preserved exactly. AGENTS.md is never created.
• Re-running the scaffold is idempotent. There is no overwrite or --force mode.
• --git initialises Git only when .git is absent and preserves an existing repository.

It writes into the target project:

CLAUDE.md                         # self-contained engineering workflow (NO AGENTS.md)
.claude/settings.json             # wires the Stop hook
.claude/hooks/quality_stop_gate.py
scripts/quality_gate.py           # the quality gate
.quality/config.json              # which checks the gate runs
docs/quality/                     # Test Matrix, UAT, Handover, Release Report templates
.github/                          # PR template + bug report template
.gitignore

---

How the Stop hook works (the point of this repo)

CLAUDE.md is advice — the agent may or may not follow it. A hook is enforcement — Claude Code runs it automatically. This repo wires a Stop hook that fires when the agent tries to end its turn:

1. It computes a fingerprint of the current repository state.
2. It checks the last recorded quality_gate.py result.
3. If the gate hasn't passed for the current fingerprint, it blocks completion and tells the agent to run the gate, fix failures, and verify again.

Run the gate yourself any time:

python3 scripts/quality_gate.py          # run all detected/configured checks
python3 scripts/quality_gate.py --list   # show what it would run

If the gate finds no checks and strict mode is on, add your real commands to .quality/config.json instead of bypassing the gate:

{
  "strict": true,
  "commands": ["npm test", "npm run lint", "npm run typecheck", "npm run build"]
}

---

The workflow it enforces

Requirement
   → read acceptance criteria + real code path
   → implement + tests
   → bug? reproduce → root cause → regression test → minimal fix
   → QA: edge cases / permissions / user-error
   → UI: Playwright + UX review
   → PR review + ship-gate
   → quality gate: Test / Lint / Type-check / Build
   → runbook + UAT + release report
   → Definition of Done (or: still blocked)

Full detail lives in the scaffolded CLAUDE.md.

---

Codex / Gemini

The scaffold writes CLAUDE.md only. Codex reads AGENTS.md and Gemini reads GEMINI.md — if you want them to share Claude's rules and skills, symlink their skills directories to Claude's, and (per project) symlink AGENTS.md/GEMINI.md → CLAUDE.md:

ln -s ~/.claude/skills ~/.agents/skills     # Codex sees the same skills
ln -s ~/.claude/skills ~/.gemini/skills     # Gemini sees the same skills
# per project, if desired:
ln -s CLAUDE.md AGENTS.md

install-global-skills.sh already installs into both ~/.claude/skills and ~/.agents/skills, and puts $debug in the Codex directory only.

---

Repo layout

smart-debugger/
├── README.md
├── LICENSE                      # MIT
├── SOURCES.md                   # upstream attribution
├── THIRD_PARTY_NOTICE.md
├── manifest.json
├── install-global-skills.sh     # install skills into Claude + Codex
└── skills/
    ├── quality-project/         # the scaffold skill (self-contained)
    │   ├── SKILL.md
    │   ├── scaffold.sh
    │   └── template/            # CLAUDE.md-only project template
    ├── qa/SKILL.md
    ├── handover/SKILL.md
    └── codex-debug/SKILL.md     # installs as Codex $debug

---

Notes

• python3 is used everywhere (the hook, the gate, the CLAUDE.md instructions). If your system only has python, symlink it or adjust .claude/settings.json.
• The Stop hook only affects the project it's scaffolded into — it does not change your global Claude Code behaviour.
• Nothing here commits secrets. The scaffolded .gitignore excludes local env files, and the workflow explicitly forbids committing secrets, tokens, or personal data.

License

MIT — see LICENSE. Upstream skills belong to their authors; see SOURCES.md.