claudeforge-cli 1.0.0

package/templates/claude/commands/review-pr.md.tpl

@@ -0,0 +1,43 @@
+---
+description: Review the current branch as a pull request — summarize changes, identify risks, and flag issues
+allowed-tools: Bash(git diff:*), Bash(git log:*), Bash(git branch:*), Bash(gh pr:*), Read, Grep
+---
+
+## Context
+
+- Branch diff against main: !`git diff main...HEAD`
+- Commits on this branch: !`git log main..HEAD --oneline`
+- Files changed: !`git diff main...HEAD --name-only`
+- Current branch: !`git branch --show-current`
+
+## Task
+
+Review this pull request as if you were a senior engineer on the team:
+
+### 1. Summary (2-3 sentences)
+What does this PR do? What problem does it solve?
+
+### 2. Changed Files
+Group the changed files by concern (e.g., "API layer", "tests", "config").
+
+### 3. Risk Areas
+Which files or logic changes require the most careful review? Why?
+
+### 4. Issues Found
+For each issue:
+```
+**[SEVERITY]** `file.ts:line`
+Issue: <what is wrong>
+Fix: <recommendation>
+```
+Severity: `CRITICAL` | `WARNING` | `SUGGESTION`
+
+### 5. Verdict
+One of:
+- `✓ LGTM` — ready to merge
+- `~ LGTM with suggestions` — merge after addressing suggestions
+- `✗ Request changes` — must address CRITICAL/WARNING items before merging
+
+## Notes
+- Check `CLAUDE.md` for project-specific conventions to enforce
+- If no issues are found, say so explicitly — don't invent nitpicks

package/templates/claude/commands/scaffold-structure.md.tpl

@@ -0,0 +1,308 @@
+---
+description: Create the actual project directory structure with real starter files based on your tech stack. Run this once after setup-project — it creates src/, tests/, and all the folders and boilerplate files your project needs to start coding immediately.
+allowed-tools: Read, Write, Bash(mkdir:*), Bash(ls:*), Bash(cat:*), Bash(find:*), Bash(npm install:*), Bash(pip install:*), Bash(go mod tidy:*), Bash(git status:*)
+---
+
+## Step 1 — Understand the Project
+
+Read the project context:
+
+- CLAUDE.md: !`cat CLAUDE.md 2>/dev/null || echo "(no CLAUDE.md — run /setup-project first)"`
+- Current structure: !`find . -not -path "*/.git/*" -not -path "*/node_modules/*" -not -path "*/__pycache__/*" -not -path "*/.claude/*" -not -path "*/memory/*" -type f | sort | head -40`
+- Tech stack: !`ls package.json requirements.txt pyproject.toml go.mod Cargo.toml pom.xml 2>/dev/null || echo "(none)"`
+- package.json: !`test -f package.json && cat package.json || echo "(none)"`
+
+**Focus area** (optional): $ARGUMENTS
+
+---
+
+## Step 2 — Create the Directory Structure
+
+Based on the tech stack detected above, create the appropriate project structure. Use the rules below.
+
+---
+
+### If Node.js / TypeScript (Next.js)
+
+```
+src/
+  app/                    # Next.js App Router
+    layout.tsx            # Root layout with metadata
+    page.tsx              # Home page
+    globals.css
+    (auth)/               # Auth route group
+      login/page.tsx
+      register/page.tsx
+  components/
+    ui/                   # Shadcn/Radix primitives
+    layout/               # Header, Footer, Sidebar
+    [feature]/            # Feature-specific components
+  hooks/                  # Custom React hooks (use*.ts)
+  lib/
+    utils.ts              # cn(), formatters, helpers
+    constants.ts          # App-wide constants
+    types.ts              # Shared TypeScript types
+  services/               # External API calls, SDKs
+  store/                  # State management (Zustand/Redux)
+tests/
+  unit/
+  integration/
+  e2e/
+public/
+```
+
+Starter files to create:
+- `src/lib/utils.ts` — cn() helper, common formatters
+- `src/lib/types.ts` — base types (ApiResponse<T>, PaginatedResponse<T>)
+- `src/lib/constants.ts` — APP_NAME, API_BASE_URL from env
+- `src/hooks/useAsync.ts` — generic async hook with loading/error state
+- `tests/unit/example.test.ts` — example test with vitest/jest setup
+
+---
+
+### If Node.js / Express or Fastify (API)
+
+```
+src/
+  index.ts                # Entry point — creates app, starts server
+  app.ts                  # App factory — registers routes, middleware
+  config/
+    index.ts              # Typed config from process.env
+    database.ts           # DB connection setup
+  routes/
+    index.ts              # Route registry
+    health.ts             # GET /health
+    [resource]/
+      index.ts            # Route definitions
+      controller.ts       # Request handlers
+      service.ts          # Business logic
+      schema.ts           # Zod/Joi validation schemas
+  middleware/
+    auth.ts               # JWT/session auth middleware
+    error.ts              # Global error handler
+    logger.ts             # Request logging
+  models/                 # DB models (Prisma/Mongoose/etc.)
+  types/
+    express.d.ts          # Augment Express Request type
+    index.ts              # Shared types
+tests/
+  unit/
+  integration/
+  fixtures/               # Test data factories
+```
+
+Starter files:
+- `src/config/index.ts` — typed config with validation
+- `src/middleware/error.ts` — global error handler
+- `src/routes/health.ts` — GET /health → { status: "ok", timestamp }
+- `src/types/index.ts` — ApiError, PaginationParams, ApiResponse<T>
+- `tests/fixtures/index.ts` — factory functions for test data
+
+---
+
+### If Python / FastAPI
+
+```
+src/
+  main.py                 # FastAPI app factory, lifespan handler
+  config.py               # Settings via pydantic-settings
+  database.py             # SQLAlchemy async engine + session
+  api/
+    __init__.py
+    router.py             # Aggregates all routers
+    deps.py               # Shared FastAPI dependencies (get_db, get_current_user)
+    v1/
+      __init__.py
+      health.py           # GET /health
+      [resource]/
+        __init__.py
+        router.py
+        schemas.py        # Pydantic request/response models
+        service.py        # Business logic
+  models/
+    __init__.py
+    base.py               # SQLAlchemy Base, TimestampMixin
+    [resource].py         # ORM models
+  core/
+    security.py           # Password hashing, JWT
+    exceptions.py         # Custom HTTP exceptions
+tests/
+  conftest.py             # pytest fixtures: test client, test db
+  unit/
+  integration/
+  factories/              # Test data factories (factory_boy)
+alembic/
+  versions/
+  env.py
+  alembic.ini
+```
+
+Starter files with real content:
+- `src/main.py` — FastAPI app with lifespan, CORS, exception handlers, router include
+- `src/config.py` — Pydantic Settings class with all env vars from .env.example
+- `src/database.py` — Async SQLAlchemy engine, AsyncSession, get_db dependency
+- `src/api/deps.py` — get_db, get_current_user dependencies
+- `src/api/v1/health.py` — GET /health endpoint
+- `src/models/base.py` — Base, TimestampMixin with created_at/updated_at
+- `src/core/exceptions.py` — AppError, NotFoundError, UnauthorizedError
+- `tests/conftest.py` — async test client, test database setup/teardown
+
+---
+
+### If Python / Django
+
+```
+[project_name]/
+  settings/
+    base.py               # Shared settings
+    development.py        # Dev overrides
+    production.py         # Prod overrides
+  urls.py
+  wsgi.py
+  asgi.py
+apps/
+  core/                   # Shared models, mixins, utilities
+    models.py             # TimestampModel abstract base
+    views.py
+    serializers.py
+  [app_name]/
+    models.py
+    views.py
+    serializers.py
+    urls.py
+    admin.py
+    tests/
+      test_models.py
+      test_views.py
+      test_serializers.py
+templates/
+static/
+tests/
+  conftest.py
+  factories/
+```
+
+---
+
+### If Go
+
+```
+cmd/
+  [appname]/
+    main.go               # Entry point — wires everything, starts server
+internal/
+  config/
+    config.go             # Viper/env config struct
+  server/
+    server.go             # HTTP server setup, middleware, route registration
+    routes.go             # All route definitions
+  handlers/
+    health.go             # GET /health handler
+    [resource].go
+  services/
+    [resource].go         # Business logic interfaces + implementations
+  repository/
+    [resource].go         # Database queries
+  models/
+    [resource].go         # Domain models
+  middleware/
+    auth.go
+    logger.go
+    recovery.go
+pkg/
+  errors/
+    errors.go             # Custom error types
+  logger/
+    logger.go             # Structured logger setup
+  database/
+    database.go           # DB connection, migration runner
+migrations/
+  000001_init.sql
+tests/
+  integration/
+  testutil/
+    testutil.go           # Test helpers, in-memory DB setup
+```
+
+Starter files:
+- `cmd/[appname]/main.go` — wires config → db → server → ListenAndServe
+- `internal/config/config.go` — typed config struct with env tags
+- `internal/server/server.go` — chi/gin/echo router setup
+- `internal/handlers/health.go` — GET /health → JSON response
+- `pkg/errors/errors.go` — AppError type with code + message
+- `tests/testutil/testutil.go` — SetupTestDB, LoadFixtures helpers
+
+---
+
+### If Rust
+
+```
+src/
+  main.rs                 # Entry point
+  lib.rs                  # Library root (re-exports)
+  config.rs               # Config from env vars
+  error.rs                # Error enum with thiserror
+  routes/
+    mod.rs
+    health.rs
+    [resource].rs
+  handlers/
+    mod.rs
+    [resource].rs
+  models/
+    mod.rs
+    [resource].rs
+  db/
+    mod.rs
+    connection.rs
+tests/
+  integration_test.rs
+  common/
+    mod.rs                # Test helpers
+```
+
+---
+
+## Step 3 — Write Starter Files with Real Content
+
+For whichever structure applies, create every file listed above with **meaningful starter code**:
+
+- Imports that will actually be used
+- Types/structs that match the project's domain
+- At least one working function (even if it's just a health check)
+- TODO comments where user-specific logic goes (not just empty files)
+- `pass` / empty bodies only when the pattern is clear from context
+
+**Critical**: Read `CLAUDE.md` before writing — use the exact naming conventions, import styles, and patterns described there.
+
+---
+
+## Step 4 — Install Dependencies
+
+After creating files, run the install command for the stack:
+
+- Node.js: `npm install` (if package.json was updated)
+- Python: `pip install -r requirements.txt` or `pip install -e ".[dev]"`
+- Go: `go mod tidy`
+- Rust: `cargo build` (just to validate, don't run full compile)
+
+---
+
+## Step 5 — Summary
+
+List every file and directory created. Group by layer:
+
+```
+Created:
+  Config & Entry Points    src/main.py, src/config.py, ...
+  API Layer                src/api/v1/health.py, ...
+  Data Layer               src/models/base.py, ...
+  Tests                    tests/conftest.py, ...
+  Infrastructure           alembic/, .env (from .env.example), ...
+
+Next steps:
+  1. Fill in the domain model in src/models/[resource].py
+  2. Create your first real endpoint in src/api/v1/[resource]/
+  3. Run the project: [command from CLAUDE.md]
+  4. Run the tests: [test command from CLAUDE.md]
+```

package/templates/claude/commands/setup-project.md.tpl

@@ -0,0 +1,253 @@
+---
+description: AI-fill the complete Claude Code project configuration. Run after `claudeforge project "description"` — or run it directly with your project description as the argument. Generates CLAUDE.md, settings, agents, commands, memory, and more.
+allowed-tools: Read, Write, Edit, MultiEdit, Bash(git status:*), Bash(git log:*), Bash(ls:*), Bash(find:*), Bash(cat:*), Bash(rm:*)
+---
+
+## Step 1 — Gather All Context
+
+Read the project setup context if it was prepared by the CLI:
+
+!`test -f SETUP_CONTEXT.md && cat SETUP_CONTEXT.md || echo "(no SETUP_CONTEXT.md — using argument and detected files)"`
+
+Detect the project's current state:
+
+- Root directory: !`ls -la`
+- Tech stack files: !`ls package.json requirements.txt pyproject.toml go.mod Cargo.toml pom.xml Gemfile composer.json tsconfig.json next.config.js vite.config.ts docker-compose.yml Dockerfile 2>/dev/null || echo "(none detected)"`
+- package.json: !`test -f package.json && cat package.json || echo "(none)"`
+- Python deps: !`test -f requirements.txt && cat requirements.txt || test -f pyproject.toml && cat pyproject.toml || echo "(none)"`
+- Go module: !`test -f go.mod && cat go.mod || echo "(none)"`
+- Existing CLAUDE.md: !`cat CLAUDE.md 2>/dev/null || echo "(not yet written)"`
+- Git history: !`git log --oneline -5 2>/dev/null || echo "(no commits yet)"`
+
+**My project**: $ARGUMENTS
+
+---
+
+## Step 2 — Fill Every Configuration File
+
+Using all context above, generate tailored content for each file. Be specific and opinionated — no placeholders, no generic examples. Every value should reflect the actual tech stack.
+
+### 2a. Rewrite `CLAUDE.md`
+
+Write a complete `CLAUDE.md` that includes:
+
+**Header**: Project name (infer from package.json/go.mod/directory name) and one-line description.
+
+**Commands table**: Real commands for this exact stack — not placeholders. Examples:
+- Python/FastAPI: `uvicorn src.main:app --reload`, `pytest`, `ruff check .`, `alembic upgrade head`
+- Node.js/Next.js: `npm run dev`, `npm test`, `npm run build`, `npx prisma migrate dev`
+- Go: `go run ./cmd/server`, `go test ./...`, `golangci-lint run`, `go build -o bin/app ./cmd/server`
+
+**Architecture**: Directory tree of what the project structure should look like once scaffolded.
+
+**Code Style**: Specific conventions — naming, imports, error handling, test patterns — for this stack.
+
+**Environment Variables**: Table with Name, Description, Required columns — matching `.env.example`.
+
+**Gotchas**: 3–5 non-obvious things about this stack (e.g., "FastAPI route order matters — more specific routes must be declared before generic ones").
+
+**Workflow**: How to use `/commit`, `/review-pr`, and project-specific agents.
+
+### 2b. Update `.claude/settings.json`
+
+Read the current file first, then merge in stack-appropriate additions:
+
+```
+Read: .claude/settings.json
+```
+
+Add to `permissions.allow` for the detected stack:
+- Python: `Bash(pytest:*)`, `Bash(ruff:*)`, `Bash(mypy:*)`, `Bash(alembic:*)`, `Bash(pip:*)`
+- Node.js: `Bash(npm run:*)`, `Bash(npx:*)`, `Bash(node:*)`
+- Go: `Bash(go test:*)`, `Bash(go build:*)`, `Bash(go run:*)`, `Bash(golangci-lint:*)`
+- Docker: `Bash(docker-compose:*)`, `Bash(docker build:*)`, `Bash(docker run:*)`
+
+Keep all existing keys (model, hooks, deny list).
+
+### 2c. Write `.env.example`
+
+Generate a real `.env.example` grouped by category. Each variable needs:
+- A comment explaining what it's for and where to get it
+- A realistic example value
+- A `(required)` or `(optional)` marker
+
+Include variables for: the app itself, any databases mentioned, any external APIs implied by the description, and any auth/session configuration.
+
+### 2d. Update `.mcp.json`
+
+Always keep `context7`. Add servers based on the stack:
+- PostgreSQL mentioned → `@modelcontextprotocol/server-postgres`
+- Web app with browser testing → `@playwright/mcp` or `@modelcontextprotocol/server-puppeteer`
+- GitHub integration → `@modelcontextprotocol/server-github`
+- File-heavy operations → `@modelcontextprotocol/server-filesystem`
+
+### 2e. Rewrite `memory/project_ai_workflow.md`
+
+Write a complete, project-specific workflow document:
+- Which agents to use and when (be explicit: "use `api-reviewer` whenever adding a new endpoint")
+- Which slash commands map to which tasks
+- MCP servers available and how to invoke them
+- Project-specific AI conventions (e.g., "always read `src/db/schema.py` before writing queries")
+- Any architectural decisions that Claude should know and respect
+
+### 2f. Create 2–4 Specialized Agents
+
+Create agent files in `.claude/agents/`. Choose agents appropriate to the project type:
+
+**For API/Backend projects:**
+- `api-reviewer.md` — Reviews new endpoints: checks REST conventions, input validation, auth, error responses, OpenAPI compliance
+- `db-reviewer.md` — Reviews database changes: checks query performance, migration safety, index coverage, N+1 risks
+
+**For Frontend projects:**
+- `component-reviewer.md` — Reviews UI components: checks accessibility, responsive design, prop types, performance (memo, useMemo)
+- `ux-checker.md` — Reviews user-facing copy, loading states, error states, empty states
+
+**For Data/ML projects:**
+- `data-validator.md` — Validates data pipelines: schema consistency, null handling, statistical reasonableness
+- `ml-reviewer.md` — Reviews model code: data leakage, correct train/val/test splits, metric definitions
+
+**For all projects:**
+- `security-auditor.md` — Deep security review: focuses on auth flows, input sanitization, secrets management, dependency CVEs
+
+Each agent must have:
+- Accurate `description` frontmatter (this determines when Claude invokes it automatically)
+- A detailed system prompt with a numbered checklist specific to the project
+- A clear output format
+
+### 2g. Create 2–4 Slash Commands
+
+Create command files in `.claude/commands/` specific to this workflow:
+
+**Common by stack:**
+- Python: `test.md` (runs pytest with coverage, explains failures), `migrate.md` (runs Alembic, validates schema)
+- Node.js: `test.md` (runs the test suite, explains failures), `typecheck.md` (runs tsc, explains type errors)
+- Any DB project: `seed.md` (seeds the database with realistic test data)
+- Any deployed project: `deploy.md` (pre-deploy checklist + deploy command + smoke test)
+
+Each command must use `!` dynamic context (e.g., `!git diff`, `!npm test 2>&1`) and have a clear `## Task` section.
+
+### 2h. Append `.gitignore` Tech-Stack Patterns
+
+Append a labeled section with patterns for this stack. Examples:
+- Python: `__pycache__/`, `*.pyc`, `.pytest_cache/`, `.mypy_cache/`, `.ruff_cache/`, `dist/`, `*.egg-info/`
+- Node.js: already covered by base template
+- Go: `bin/`, `*.exe`, `*.test`, `coverage.out`
+- Rust: `target/`
+
+---
+
+## Step 3 — Clean Up
+
+Delete the context file if it exists:
+
+```bash
+rm -f SETUP_CONTEXT.md
+```
+
+---
+
+## Step 4 — Document Every File Generated
+
+After all files are written, go back and add a documentation header to each one so users know what they're looking at and what to customize.
+
+For each file written, prepend (or add at an appropriate location):
+
+**CLAUDE.md** — add at the top after the title:
+```
+> **Setup status**: Generated by claudeforge. Update the Commands table with your actual
+> project commands after verifying them. Fill in the Gotchas section as you discover them.
+```
+
+**`.claude/settings.json`** — add a `_readme` key (JSON doesn't support comments, use this):
+```json
+"_readme": "Team-shared Claude Code settings. Personal overrides go in settings.local.json (gitignored). See .claude/README.md for the full reference."
+```
+
+**Each agent file** — after the frontmatter, add:
+```
+<!-- WHAT THIS IS: A Claude sub-agent that specializes in [specific task].
+     HOW TO INVOKE: Claude uses this automatically when the task matches the description.
+     HOW TO CUSTOMIZE: Edit the checklist items below to match your project's specific patterns.
+     THINGS TO ADD: Project-specific anti-patterns, naming conventions, architectural rules. -->
+```
+
+**Each command file** — after the frontmatter, add:
+```
+<!-- WHAT THIS IS: A slash command. Run it with /[name] in the Claude Code chat.
+     HOW IT WORKS: Claude reads the ## Context section (! lines run as shell commands)
+     then follows the ## Task instructions.
+     HOW TO CUSTOMIZE: Edit the ## Task section. Add more ! context lines if needed. -->
+```
+
+**memory/project_ai_workflow.md** — add at the top:
+```
+<!-- Update this file as your AI workflow evolves. Claude reads it every session.
+     The more specific you are, the less you'll need to re-explain things to Claude. -->
+```
+
+---
+
+## Step 5 — Write `SETUP_SUMMARY.md`
+
+Create a `SETUP_SUMMARY.md` in the project root:
+
+```markdown
+# Claude Code Setup Summary
+
+Generated by `/setup-project` on [today's date].
+
+## What Was Generated
+
+| File | What It Does | Key Things to Customize |
+|------|-------------|------------------------|
+| `CLAUDE.md` | Project context loaded every session | Update Commands table with real commands; add Gotchas as you discover them |
+| `.claude/settings.json` | Permissions + hooks for Claude Code | Add more allowed commands as you expand your workflow |
+| `.env.example` | Documents required env vars | Update with any new vars; never commit real values |
+| `.mcp.json` | MCP servers your team shares | Add connection strings to .env for any DB servers |
+| `memory/project_ai_workflow.md` | AI conventions for this project | Update as your workflow evolves; Claude reads this every session |
+| [agent files] | Specialized review agents | Customize checklists to add project-specific patterns |
+| [command files] | Slash commands for your workflow | Edit the ## Task section to match your exact needs |
+
+## Slash Commands Available
+
+Run these in the Claude Code chat window:
+
+| Command | When to Use |
+|---------|------------|
+| `/setup-project` | Re-run project setup with a new description |
+| `/commit` | After completing a task — creates a conventional commit |
+| `/review-pr` | Before opening a PR — structured diff review |
+| `/project-health` | Weekly — audits your setup and suggests improvements |
+| `/memory-sync` | End of session — persists what Claude learned today |
+| `/standup` | Morning — generates standup from yesterday's commits |
+| `/scaffold-structure` | Once — creates the src/, tests/, etc. directory structure |
+| [project commands] | See .claude/commands/ for project-specific commands |
+
+## Agents Available
+
+Claude uses these automatically based on what you're doing:
+
+| Agent | Invoked When |
+|-------|-------------|
+| `code-reviewer` | After writing code, before PR |
+| [project agents] | See .claude/agents/ for project-specific agents |
+
+## Next Steps
+
+1. **Verify commands** in `CLAUDE.md` — run each one and confirm they work
+2. **Create `.env`** from `.env.example` — fill in real values
+3. **Run `/scaffold-structure`** in Claude Code chat to create the project directory layout
+4. **Open Claude Code** in this directory and start building
+5. Delete this file once you've read it
+```
+
+---
+
+## Step 6 — Final Summary
+
+Print a clear summary of everything that was done:
+
+1. List every file written
+2. List every agent created with its trigger description
+3. List every slash command created with its use case
+4. State the exact next step: "Run `/scaffold-structure` in Claude Code to create your project's directory structure"

package/templates/claude/commands/standup.md.tpl

@@ -0,0 +1,34 @@
+---
+description: Generate a standup update from recent git commits, open issues, and current working state. Optionally pass a date range: /standup "last 3 days"
+allowed-tools: Bash(git log:*), Bash(git diff:*), Bash(git status:*), Bash(git branch:*), Bash(gh issue:*), Bash(gh pr:*)
+---
+
+## Context
+
+- Recent commits: !`git log --oneline --since="yesterday" --author="$(git config user.name)" 2>/dev/null || git log --oneline -10`
+- Current branch: !`git branch --show-current 2>/dev/null`
+- Working state: !`git status --short 2>/dev/null`
+- Open PRs (if gh available): !`gh pr list --author "@me" --state open 2>/dev/null || echo "(gh not available)"`
+
+**Date range**: $ARGUMENTS
+
+## Task
+
+Write a concise standup update with these three sections:
+
+### Yesterday / Since last standup
+Summarize what was actually done based on the git log. Group related commits into themes rather than listing every commit individually. Be specific about what changed.
+
+### Today / Next
+Based on the in-progress work (current branch, uncommitted changes, open PRs), describe what's planned next.
+
+### Blockers
+Only include this section if there are actual blockers visible (failing tests, unresolved merge conflicts, unclear requirements, etc.). Otherwise omit it.
+
+---
+
+**Format rules:**
+- Each section: 1–4 bullet points max
+- Plain language — no jargon, readable by anyone on the team
+- Skip the section headers if a section is empty
+- Total length: under 150 words

package/templates/claude/hooks/post-tool-use.sh.tpl

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# ─────────────────────────────────────────────────────────────────────────────
+# PostToolUse Hook
+# Runs after a tool has completed. Use this to inject reminders or context.
+#
+# Input:  JSON on stdin  — tool_name, tool_input, tool_response
+# Output: {"systemMessage": "..."} to inject a message into Claude's context,
+#         or empty output for no effect.
+#
+# Docs: https://docs.anthropic.com/en/docs/claude-code/hooks
+# ─────────────────────────────────────────────────────────────────────────────
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+json_get() {
+  python3 -c "
+import sys, json
+try:
+    d = json.loads(sys.stdin.read())
+    keys = '$1'.split('.')
+    v = d
+    for k in keys:
+        v = v[k] if isinstance(v, dict) else ''
+    print(v if v is not None else '')
+except:
+    print('')
+" <<< "$INPUT"
+}
+
+TOOL_NAME=$(json_get "tool_name")
+FILE_PATH=$(json_get "tool_input.path")
+
+# ── Reminder: run tests after editing test files ──────────────────────────────
+if [[ "$TOOL_NAME" == "Edit" || "$TOOL_NAME" == "Write" || "$TOOL_NAME" == "MultiEdit" ]]; then
+  if echo "$FILE_PATH" | grep -qiE '\.(test|spec)\.[jt]sx?$|_test\.go$|test_.*\.py$|.*_spec\.rb$'; then
+    echo '{"systemMessage":"Test file edited. Consider running the test suite to verify the changes work as expected."}'
+    exit 0
+  fi
+fi
+
+# ── Default: no effect ────────────────────────────────────────────────────────
+exit 0