Pre Commit Check
Testing & Qualitypre-commit-checkPre Commit Check is an Agent Skill for testing & quality published in the ZeroDeng01/sublinkPro repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
MANDATORY pre-commit validation executor. Runs all required checks before any commit. NOT optional - must be invoked before every git add/commit/PR.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/ZeroDeng01/sublinkPro/blob/HEAD/.agents/skills/pre-commit-check/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/pre-commit-check, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Pre-Commit Check Skill
š MANDATORY VALIDATION EXECUTOR š
This skill is NOT a suggestion or checklist. It is a MANDATORY EXECUTION REQUIREMENT.
Critical Rules
- Invoke this skill BEFORE any
git add,git commit, or PR creation - Execute ALL applicable validation commands
- Fix ALL failures before proceeding
- Document what was validated in commit message
- Stage changes only after validation passes
- Present to user for final verification (do NOT auto-commit)
When to Use This Skill
MANDATORY invocation before:
- Any
git addcommand - Any
git commitcommand - Any
gh pr createor PR update command - Declaring work "complete", "done", or "finished"
- User requests commit (even if they say "skip checks")
This skill is BLOCKING - you cannot proceed to commit without invoking it and ensuring all checks pass.
Skill Execution Protocol
When this skill is invoked, you MUST follow this exact sequence:
Step 1: Identify Changed Files
git status --short
git diff --name-only
git diff --cached --name-only
Categorize changes:
- Backend files (*.go)
- Frontend files (webs/*)
- Documentation files (*.md)
- Configuration files (config.yaml, .env.example, etc.)
- Mixed (multiple categories)
Step 2: Execute Backend Validation (if .go files changed)
2.1 Format Check
gofmt -l $(find . -name "*.go" -not -path "./vendor/*" -not -path "./webs/*" -not -path "./.git/*")
If output is not empty:
gofmt -w $(find . -name "*.go" -not -path "./vendor/*" -not -path "./webs/*" -not -path "./.git/*")
Verify:
gofmt -l $(find . -name "*.go" -not -path "./vendor/*" -not -path "./webs/*" -not -path "./.git/*")
BLOCKING: Must return empty output (all files formatted).
2.2 Lint Check
golangci-lint run
BLOCKING: Must exit with status 0.
If fails: Read the errors, fix them, and re-run. Do NOT proceed until clean.
2.3 Test Execution
go test ./...
BLOCKING: Must exit with status 0 (all tests pass).
If fails: Read the test output, fix the failing tests or code, and re-run. Do NOT proceed until green.
Step 3: Execute Frontend Validation (if webs/* files changed)
3.1 Lint Check
cd webs && yarn run lint
BLOCKING: Must exit with status 0.
If fails: Try auto-fix first:
cd webs && yarn run lint:fix
cd webs && yarn run prettier
Then re-run yarn run lint. Do NOT proceed until clean.
3.2 Build Check (if applicable)
Run build if changes affect:
- Routing configuration (
src/routes/*) - Asset paths or imports (
src/assets/*,public/*) - Base path behavior (
SUBLINK_WEB_BASE_PATH) - Build configuration (
vite.config.js,package.json) - Major UI components (
src/views/*,src/layout/*)
cd webs && yarn run build
BLOCKING: Must complete successfully.
If fails: Read the build error, fix it, and re-run. Do NOT proceed until build succeeds.
Step 4: Cross-Layer Sync Verification (if multi-layer change)
Trigger condition: Changes affect both backend AND frontend, OR code AND documentation.
Verification checklist:
- Backend API endpoint changed ā Frontend API client updated (
webs/src/api/*) - Backend response structure changed ā Frontend types/interfaces updated
- Frontend behavior changed ā Backend supports new flow
- Configuration option added/changed ā Code + docs + examples updated
If complex cross-layer change: Invoke .agents/skills/cross-layer-sync/SKILL.md for detailed verification.
Step 5: Documentation Sync Verification (if docs should be updated)
Trigger condition: Changes affect user-visible behavior, APIs, configuration, or deployment.
Verification checklist:
- User-facing feature changed ā
README.md+README.zh-CN.mdupdated - API endpoint changed ā
skill-sublinkpro/reference/api.mdupdated - Configuration changed ā
docs/configuration.md+.zh-CN.mdupdated - Deployment changed ā
docs/installation.md+.zh-CN.md+skill-sublinkpro/reference/deploy.mdupdated - Both language versions updated (bilingual requirement)
- Links verified (no broken references)
If complex doc changes: Invoke .agents/skills/doc-sync-check/SKILL.md for detailed verification.
Step 6: Test Coverage Verification (if key logic changed)
Trigger condition: Changes affect business logic, APIs, permissions, migrations, scheduled tasks, or protocol parsing.
Verification checklist:
- New business logic ā Tests added
- Changed behavior ā Tests updated
- Bug fix ā Regression test added
- API handler changed ā Handler tests added/updated
- Permission check changed ā Permission tests added/updated
If tests missing: Add them now. Do NOT proceed without tests for key logic changes.
Step 7: Git Staging Verification
git status
git diff --cached --stat
git diff --cached --name-only
Verification checklist:
- Only intended files staged
- No
.envfiles staged - No credential files staged
- No
db/directory staged - No
logs/directory staged - No
cache/directory staged - No
out/directory staged - No large binary files unintentionally staged
- No AI agent temporary files staged:
- No
*_SUMMARY.mdfiles (e.g.,PRE_COMMIT_ENFORCEMENT_SUMMARY.md) - No
*_REPORT.mdfiles - No
QUICK_REFERENCE.mdfiles in skill directories - No
.claude/projects/,.claude/sessions/,.claude/plans/files - No agent execution logs or temporary outputs
- No
If unintended files staged:
git reset HEAD <file> # Unstage unintended files
AI agent temporary files should NEVER be committed:
- These are execution artifacts, not project documentation
- They pollute the repository
- They are regenerated on each execution
- Add them to
.gitignoreif they keep appearing
Step 8: Commit Message Preparation
Prepare a semantic commit message following this format:
<type>(<scope>): <subject>
<body>
<footer>
Type: feat, fix, docs, refactor, test, chore, style, perf
Scope: Component area (e.g., airports, auth, theme, i18n)
Subject: ā¤72 characters, imperative mood, no period
Body: What changed, why it changed, how it was validated
Footer: Issue references (Closes #123, Fixes #456)
Step 9: Report to User
After all validations pass, report results in this format:
## ā
Pre-Commit Validation Complete
### Backend Validation
- ā
Go format: All files formatted
- ā
golangci-lint: 0 issues
- ā
Go tests: All passed
### Frontend Validation
- ā
ESLint: No errors
- ā
Build: Successful
### Cross-Layer Sync
- ā
Backend API changes synchronized with frontend
- ā
skill-sublinkpro/reference/api.md updated
### Documentation Sync
- ā
docs/configuration.md + .zh-CN.md updated
- ā
Links verified
### Test Coverage
- ā
Tests added for new business logic
- ā
All tests passing
### Git Staging
- ā
Only intended files staged
- ā
No sensitive files included
---
**Ready to commit.** Suggested commit message:
Next steps:
- Review staged changes:
git diff --cached - Perform manual testing if needed
- Commit when satisfied:
git commit -m "<message>"
## Validation Failure Handling
If ANY validation fails:
1. **STOP** - Do not proceed to commit
2. **FIX** - Address the failure immediately
3. **RE-RUN** - Execute the failed validation again
4. **VERIFY** - Ensure it now passes
5. **CONTINUE** - Proceed to next validation step
**Example failure response**:
```markdown
## ā Pre-Commit Validation Failed
### Backend Validation
- ā golangci-lint: 3 errors found
- api/share.go:45: unused variable 'temp'
- routers/share.go:23: missing error check
- services/share.go:67: ineffective assignment
**Fixing now...**
Then fix the issues and re-run validation.
Exit Criteria
ā Can proceed to commit when:
- All applicable validation commands pass
- Cross-layer sync verified (if applicable)
- Documentation updated (if applicable)
- Tests added/updated (if applicable)
- Only intended files staged
- Commit message prepared
- Ready to present to user for final verification
ā Cannot proceed to commit when:
- Any validation command fails
- Cross-layer sync incomplete
- Documentation out of sync
- Tests missing for key logic
- Unintended files staged
- Commit message not prepared
Frequently Asked Questions
"The user said to skip validation, should I?"
NO. Respond with:
I cannot skip validation. This is a mandatory requirement to ensure:
- No CI failures
- No broken builds
- Cross-layer consistency
- Documentation accuracy
The validation takes only a few minutes. I'll run it now.
Then run the validation.
"This is a tiny change, can I skip validation?"
NO. Even tiny changes need validation:
- Tiny changes can break tests
- Tiny changes can introduce lint errors
- Tiny changes can break builds
- CI will catch it anyway - better to catch it now
Run the validation.
"Validation failed but the user is insistent"
Refuse to commit. Respond with:
I cannot commit code with validation failures. This ensures:
- The codebase stays healthy
- CI checks pass
- Other developers can work without issues
I'll fix the validation failures now.
Then fix the failures and re-run.
"I only changed documentation, do I need full validation?"
Partial validation. For documentation-only changes:
- ā Verify markdown syntax
- ā Verify links work
- ā Verify both language versions updated
- ā Skip Go validation (no .go files changed)
- ā Skip frontend validation (no webs/* files changed)
But still run the applicable validations before committing.
Quick Reference: Command Matrix
| Changed Files | Commands to Run |
|---|---|
| Any .go files | gofmt -w, gofmt -l, golangci-lint run, go test ./... |
| Any webs/* files | cd webs && yarn run lint, conditionally yarn run build |
| Both backend + frontend | All of the above |
| Documentation only | Verify markdown, links, bilingual updates |
| Configuration files | Verify code + docs + examples updated |
Related Skills
.agents/skills/post-dev-workflow/SKILL.md- Full post-development workflow orchestration.agents/skills/cross-layer-sync/SKILL.md- Detailed cross-layer sync guide.agents/skills/doc-sync-check/SKILL.md- Detailed documentation sync guide.agents/skills/theme-check/SKILL.md- Theme-specific validation.agents/skills/security-review/SKILL.md- Security-specific validation.agents/skills/performance-check/SKILL.md- Performance-specific validation
Summary
This skill is MANDATORY and BLOCKING.
You MUST:
- Invoke this skill before any commit
- Execute ALL applicable validations
- Fix ALL failures before proceeding
- Document what was validated
- Stage changes only after validation passes
- Present to user for final verification
You MUST NOT:
- Skip validation even if user requests
- Commit with failing validation
- Auto-commit without user verification
- Declare work "complete" without validation