pre-push-gate

Pre-Push Quality Gate

Analyze the git diff against staging and generate a dynamic checklist of missing artifacts. Optionally dispatch agents to fix findings.

Arguments: "$ARGUMENTS"

• No arguments or empty: Full gate (Phase 0-3) + interactive fix prompt
• check: Read-only checklist only (no fix offered)
• fix: Fix all findings
• fix <category>: Fix only the named category (e.g. fix i18n, fix db)

---

Phase 0 — Standard Checks

Run standard quality checks first. Stop immediately on failure.

pnpm typecheck

On typecheck failure: report errors and STOP. Do not continue to Phase 1.

pnpm lint:fix
pnpm format:fix

After lint:fix and format:fix, check for auto-fixed files via git diff --name-only. Report which files were modified. Continue to Phase 1.

---

Phase 1 — Diff Analysis

Step 1: Fetch and diff

git fetch origin staging
git diff --name-only origin/staging...HEAD

Step 2: Categorize changed files

Match each changed file against the trigger matrix. A file can trigger multiple categories.

Category	ID	File Patterns
DB & Migrations	db	supabase/migrations/*.sql, schemas/20-corpus-health.sql, database.types.ts
i18n	i18n	public/locales/**/*.json; changed .tsx with new <Trans or t( calls
UI Completeness	ui	New .tsx in _components/; new page.tsx under (user)/
Server Actions	actions	*-actions.ts; files with 'use server' directive
Schemas & Validation	schemas	*.schema.ts
Services & Logic	services	_lib/**/*.ts (excl. tests), *-service.ts, *-loader.ts
E2E Impact	e2e	Changed pages under (user)/; changed _components/**/*.tsx; changed data-test attrs; deleted routes
Edge Functions	ef	supabase/functions/**/*.ts (excl. _shared/)

Skip categories with zero matching files. Report active categories:

Active categories: db, i18n, e2e (3/8)
Skipped: ui, actions, schemas, services, ef

For fix <category> arguments, validate the category ID and process only that category.

---

Phase 2 — Parallel Read-Only Checks

Execution Strategy

Detect whether TeamCreate is available.

Team Mode (TeamCreate available):

1. TeamCreate({ team_name: "pre-push-check", description: "Read-only pre-push quality gate checks" })
2. One TaskCreate per active category
3. One teammate per task via Agent with team_name and subagent_type: "feature-dev:code-explorer"
4. Consolidate after all teammates complete

Fallback Mode (no TeamCreate):

• Spawn agents via Agent with run_in_background: true, all subagent_type: "feature-dev:code-explorer"
• Consolidate after all complete

Agent Prompt Template

Read-only pre-push quality gate checker for a MakerKit (Next.js App Router + Supabase) project.

CATEGORY: {category_name}
CHANGED FILES IN THIS CATEGORY:
{file_list}

FULL DIFF CONTEXT (all changed files on this branch):
{all_changed_files}

INSTRUCTIONS:
1. Read `.claude/rules/` and `CLAUDE.md` for project conventions
2. Execute each check listed below against the changed files
3. For checks that look for "missing" artifacts, search the codebase to verify presence/absence

YOUR CHECKS:
{checks_for_this_category}

OUTPUT FORMAT — For each check, report exactly:
- check: {check description}
- status: PASS | FAIL | WARN
- details: {what was found or missing, with file paths}
- fix_keywords: {2-3 keywords for ToolSearch to find a fix agent, e.g. "database sql pgTAP"}

IMPORTANT: This is READ-ONLY. Do NOT modify any files.

Checks Reference

Load the detailed checks for each category from references/checks-per-category.md. Insert the relevant section as {checks_for_this_category} in the agent prompt.

---

Phase 2b — Agent Discovery

After all check agents complete, collect fix_keywords from each FAIL/WARN finding.

For each unique set of fix keywords:

ToolSearch(query: "{fix_keywords}", max_results: 3)

Map each finding to the best-matching agent/skill capable of writing code. Fallback: bmad-dev.

---

Phase 3 — Consolidated Checklist

Present results as tables per category:

# Pre-Push Gate — Checkliste

Branch: {branch_name} → staging
Geänderte Dateien: {count} | Aktive Kategorien: {active}/{total}

## {Category Name} ({pass_count}/{total_count})

| # | Status | Prüfung | Fix-Agent |
|---|--------|---------|-----------|
| 1 | ✅ | {check description} | — |
| 2 | ❌ | {check description + details} | {recommended agent/skill} |
| 3 | ⚠️ | {check description + details} | {recommended agent/skill} |

Rules:

• All-pass categories: one-line summary ## {Category} ({n}/{n}) ✅
• Skipped categories: list at bottom ## Übersprungen: {list}
• Sort categories by failure count (most first)

Footer:

**Ergebnis: {fail_count} ❌ · {warn_count} ⚠️ · {pass_count} ✅**

For check argument: show checklist and STOP.

Otherwise present options:

Optionen:
(1) Alles fixen — Agents für alle ❌ Items dispatchen
(2) Kategorie wählen — z.B. "fix i18n"
(3) Selbst fixen — Checkliste steht, du fixst manuell
(4) Detail zu einem Item — mehr Kontext anzeigen

Wait for user input before proceeding.

---

Phase 4 — Fix Dispatch (optional)

Runs only on user choice (option 1/2) or fix argument.

Step 1: Group findings by fix agent

Step 2: Detect file conflicts

When two findings modify the same file:

⚠️ Konflikt-Warnung: Items #{a} und #{b} betreffen beide {filename}
   → Empfehlung: sequenziell ausführen

Present conflicts to the Team Lead. They decide parallel vs sequential.

Step 3: Dispatch fix agents

Team Mode: TeamCreate → one task per agent group → one teammate per task. Fallback: Sequential or parallel Agent calls per Team Lead decision.

Each fix agent receives:

Fix agent for a forgeweb pre-push gate finding (MakerKit/Next.js/Supabase).

CONTEXT:
- Branch: {branch_name}
- Project rules: Read `.claude/rules/` and `CLAUDE.md`

FINDING:
{finding_description}

AFFECTED FILES:
{file_list}

INSTRUCTIONS:
- Follow existing artifacts in the same directory as templates
- Read existing tests/locale files/schemas for patterns
- Write the fixes
- Do NOT commit — the Team Lead reviews and commits

{additional_context_per_category}

Load additional fix context per category from references/checks-per-category.md (bottom section).

Step 4: Verification

After all fix agents complete:

1. Re-run Phase 0 (typecheck, lint, format)
2. Re-run Phase 2 checks for fixed categories
3. Present updated checklist
4. Ideal outcome: all ❌ → ✅

---

Category ID Reference

ID	Category
db	DB & Migrations
i18n	i18n
ui	UI Completeness
actions	Server Actions
schemas	Schemas & Validation
services	Services & Logic
e2e	E2E Impact
ef	Edge Functions

Additional Resources

• references/checks-per-category.md — Detailed check definitions per category and fix context