Post-Development Workflow

Post-Development Workflow Skill

🛑 MANDATORY AUTOMATED WORKFLOW 🛑

This workflow is REQUIRED after completing ANY code change, before declaring work "complete".

CRITICAL: This workflow is a PREREQUISITE for committing. Do NOT proceed to commit without completing this workflow successfully.

When to Use This Skill

ALWAYS use this skill when:

• Any code change is complete (backend, frontend, or both)
• Before declaring work "finished" or "done"
• Before preparing to commit changes
• Before creating or updating a pull request

This is NOT optional for AI agents. If an AI agent completes development without running this workflow, the work is incomplete.

Workflow Phases

This skill orchestrates multiple validation phases in sequence:

Development Complete
    ↓
1. Code Validation (lint, format, build)
    ↓
2. Cross-Layer Sync Check (if multi-layer change)
    ↓
3. Documentation Sync Check (if behavior/API/config changed)
    ↓
4. Test Execution (if key logic changed)
    ↓
5. Change Summary (prepare commit message and PR description)
    ↓
Stage Changes (git add)
    ↓
Present Summary to User
    ↓
User Verifies/Tests
    ↓
User Commits When Ready

Phase 1: Code Validation

Run validation commands for all changed layers.

Backend Changes

gofmt -w <changed-files>    # Format
golangci-lint run           # Lint
go test ./...               # Test

Required exit criteria:

• gofmt produces no further changes
• golangci-lint run exits with status 0
• Relevant go test passes

Frontend Changes

cd webs
yarn run lint               # Always required
yarn run build              # If routing/assets/build affected

Optional auto-fix:

yarn run lint:fix
yarn run prettier

Required exit criteria:

• yarn run lint exits with status 0
• yarn run build succeeds (if applicable)

When Phase 1 Fails

DO NOT proceed to Phase 2 until all validation passes. Fix issues first.

Detailed validation commands and troubleshooting: See references/validation-commands.md

Phase 2: Cross-Layer Synchronization Check

Trigger condition: Changes affect multiple layers (backend + frontend, code + docs, code + config)

Additional checks: For security-critical or performance-sensitive changes, invoke specialized skills:

• Security changes: Also invoke .agents/skills/security-review/SKILL.md
• Performance-critical changes: Also invoke .agents/skills/performance-check/SKILL.md

Quick Checklist

Required exit criteria:

• All impacted layers identified
• All impacted layers synchronized
• Verification commands run for each layer
• Documented which layers were checked

When to Skip Phase 2

Skip only if the change is truly isolated to one layer. Document the skip reason in your change summary.

Detailed cross-layer sync patterns and verification: See references/cross-layer-sync-rules.md

Phase 3: Documentation Synchronization Check

Trigger condition: Changes affect user-visible behavior, APIs, configuration, deployment, or developer workflows

Quick Checklist

Bilingual requirement:

• Both English (.md) and Chinese (.zh-CN.md) versions updated
• Language switch links work
• Content semantically equivalent

Required exit criteria:

• All affected documentation identified
• Both language versions updated
• Links verified (no broken references)
• Code examples accurate and tested
• Documentation map updated (skill-sublinkpro/reference/docs.md) if new docs added

When to Skip Phase 3

Skip only if:

• Pure internal refactoring (no user-visible changes)
• Bug fix that restores documented behavior (not new behavior)
• Test-only changes

Document the skip reason in your change summary.

Detailed documentation sync patterns and templates: See references/documentation-sync-rules.md

Phase 4: Test Execution

Trigger condition: Changes affect key business logic, APIs, permissions, configuration semantics, migrations, scheduled tasks, mihomo integrations, protocol parsing, or data transformations

What Needs Tests

Backend tests required when:

• Added or changed business logic in services/
• Added or changed API handler in api/
• Added or changed permission checks in middlewares/
• Added or changed database migration in models/db_migrate.go
• Added or changed scheduled task in services/scheduler/
• Added or changed protocol in node/protocol/
• Fixed a bug (add regression test)

Frontend tests:

• Added or changed utility functions in webs/src/utils/
• Added or changed complex components with business logic
• Added or changed API client functions in webs/src/api/
• Fixed a bug (add regression test)

Test Requirements

# Backend: run relevant tests
go test ./services/scheduler/...  # Example: if scheduler changed
go test ./...                     # Full suite if time permits

# Frontend: run tests with Vitest
cd webs
yarn test                         # Run all tests
yarn test --run                   # Run without watch mode

Test quality:

• Tests cover happy path, boundaries, and error cases
• Tests are isolated (no execution order dependency)
• Test names describe scenario and expected outcome
• Regression tests added for bug fixes

Required exit criteria:

• Relevant tests exist
• All tests pass
• Coverage is reasonable for the changed area

When to Skip Phase 4

Skip only if:

• Pure documentation changes
• Pure UI styling changes (no logic)
• Refactoring with existing test coverage

Document the skip reason in your change summary.

Phase 5: Change Summary

Prepare a comprehensive summary of what was done, why, and how it was validated.

Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

Type: feat, fix, docs, refactor, test, chore, style, perf

Scope: Component area (e.g., airports, auth, theme, i18n, scheduler)

Subject: Concise description (≤72 chars, imperative mood, no period)

Examples

feat(airports): add batch subscription update

Added batch update dialog with progress tracking.
Users can now select multiple airports and update them in parallel.

Closes #123

fix(auth): enhance SSE authentication error handling

SSE authentication failures now return proper i18n error messages.
Added retry logic for transient network errors.

Fixes #456

Change Summary Checklist

Document in your summary:

What changed:

• List files or areas modified
• Describe the change at a high level

Why:

• What problem this solves
• What feature this adds
• What behavior this fixes

How validated:

• Which layers were checked (backend, frontend, docs)
• Which validation commands were run (lint, test, build)
• Which cross-layer sync was performed
• Which documentation was updated
• Manual testing performed (if applicable)

Breaking changes (if any):

• What breaks
• Migration path for users
• Configuration changes required

Detailed commit message guide and templates: See references/commit-message-guide.md and assets/commit-template.txt

Phase 6: Pre-Commit Final Validation (MANDATORY)

🛑 CRITICAL: This phase is MANDATORY before any git commit 🛑

After completing Phases 1-5, you MUST invoke the pre-commit-check skill to perform final validation before committing.

Why This Phase is Required

Even though Phase 1 runs validation, you MUST re-run pre-commit-check because:

• Files may have been modified since Phase 1
• Additional changes may have been made during documentation/test updates
• This ensures absolute consistency before commit
• This is a hard requirement per AGENTS.md Section 0

Execution

# Before proceeding to git add/commit, invoke:
.claude/skills/pre-commit-check/SKILL.md

The pre-commit-check skill will:

1. Verify all changed files
2. Re-run format/lint/test commands
3. Verify git staging (no sensitive files, no runtime data)
4. Prepare final commit message
5. Stage changes for user verification

BLOCKING: You cannot proceed to commit without successfully completing pre-commit-check.

Delivery Checklist

Before declaring work "complete", verify:

• Phase 1: All validation commands pass (lint, format, build, test)
• Phase 2: Cross-layer sync verified (or skip reason documented)
• Phase 3: Documentation updated (or skip reason documented)
• Phase 4: Tests added/updated (or skip reason documented)
• Phase 5: Change summary prepared
• Phase 6: Pre-commit-check skill invoked and passed (MANDATORY)
• Git staging: Only intended files staged (no secrets, no runtime data)
• Bilingual: Both English and Chinese docs updated (if docs changed)
• No shortcuts: No skipped validation, no "will fix later" items
• User verification: Changes staged and ready for user manual testing/verification