---
name: post-dev-workflow
description: "MANDATORY post-development workflow orchestrating validation, synchronization, and testing phases. Automatically invoked by AI agents after code changes. BLOCKING - work is incomplete without this."
version: "2.0.0"
author: "SublinkPro Team"
user-invocable: false
mandatory: true
enforcement-level: "blocking"
---

# 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

```bash
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

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

**Optional auto-fix**:
```bash
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

| Change Type | Must Also Update |
|---|---|
| Backend API endpoint changed | Frontend `webs/src/api/`, `skill-sublinkpro/reference/api.md` |
| Backend response structure changed | Frontend display components, state management |
| Frontend behavior changed | Verify backend supports new flow |
| Configuration option added/changed | Code + `docs/configuration.md` + `.zh-CN.md` + example configs + `skill-sublinkpro/reference/deploy.md` |
| User-facing feature added/changed | Code + `docs/features/*.md` + `.zh-CN.md` + `README.md` |

**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

| Change Type | Docs to Update |
|---|---|
| User-facing feature | `README.md` + `.zh-CN.md`, `docs/features/*.md` + `.zh-CN.md` |
| API endpoint | `skill-sublinkpro/reference/api.md` |
| Configuration | `docs/configuration.md` + `.zh-CN.md`, example configs |
| Deployment | `docs/installation.md` + `.zh-CN.md`, `skill-sublinkpro/reference/deploy.md` |
| Developer workflow | `docs/development.md` + `.zh-CN.md`, `CONTRIBUTING.md` + `.zh-CN.md` |
| Architecture | `AGENTS.md` |

**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

```bash
# 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

```bash
# 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

---

## Exit Criteria

✅ **Can declare work complete when**:
- All validation passes (Phase 1)
- Cross-layer sync verified (Phase 2)
- Documentation updated (Phase 3)
- Tests added/updated (Phase 4)
- Change summary prepared (Phase 5)
- **Pre-commit-check skill successfully completed (Phase 6)**
- All deliverables documented
- No unresolved validation failures
- No "will fix later" items
- **Changes staged and ready for user verification** (DO NOT auto-commit)

❌ **Cannot declare work complete when**:
- Validation commands fail
- Documentation out of sync with code
- Cross-layer changes not synchronized
- Tests missing or failing
- Change summary incomplete
- **Pre-commit-check not invoked or failed**

---

## For AI Agents: Automation Notes

This workflow should be **automatically triggered** after completing code development, without waiting for user prompt.

### Triggering Logic

```
IF code_change_complete:
    INVOKE .agents/skills/post-dev-workflow/SKILL.md
    RUN Phase 1 (validation)
    IF multi_layer_change:
        RUN Phase 2 (cross-layer sync)
    IF behavior_or_api_or_config_changed:
        RUN Phase 3 (documentation sync)
    IF key_logic_changed:
        RUN Phase 4 (test execution)
    RUN Phase 5 (change summary)
    🛑 RUN Phase 6 (pre-commit-check) - MANDATORY, NO EXCEPTIONS
    REPORT results to user
    IF all_phases_pass:
        STAGE changes (git add)
        PRESENT summary to user
        WAIT for user verification/testing
        DO NOT auto-commit
    ELSE:
        FIX failures and re-run
```

### Critical Rule: Phase 6 is Non-Negotiable

**Phase 6 (pre-commit-check) MUST be invoked before any git add/commit**, even if:
- Phase 1 validation already passed
- Changes seem minor
- User requests to skip checks
- You believe no additional validation is needed

This double-validation ensures:
1. No files changed after Phase 1
2. Documentation/test updates didn't introduce issues
3. Git staging is clean (no sensitive files)
4. Commit message is properly formatted
5. Compliance with AGENTS.md Section 0 requirements

### Reporting Format

After running this workflow, report to the user:

```
## Post-Development Workflow Complete

### Phase 1: Code Validation ✅
- Backend: gofmt ✅, golangci-lint ✅, go test ✅
- Frontend: yarn lint ✅, yarn build ✅

### Phase 2: Cross-Layer Sync ✅
- Backend API changed → Frontend updated ✅
- skill-sublinkpro/reference/api.md updated ✅

### Phase 3: Documentation Sync ✅
- docs/configuration.md + .zh-CN.md updated ✅
- Links verified ✅

### Phase 4: Test Execution ✅
- Added tests for new business logic ✅
- All tests passing ✅

### Phase 5: Change Summary ✅
- Commit message prepared ✅

### Phase 6: Pre-Commit Final Validation ✅
- All validations re-verified ✅
- Git staging clean (no sensitive files) ✅
- Only intended files staged ✅
- Ready for commit ✅

---

**Changes staged and ready for your verification.**

Suggested commit message:
```
feat(config): add database connection pooling option

Added new configuration options for database connection pooling:
- `DB_MAX_OPEN_CONNS`: Maximum open connections (default: 25)
- `DB_MAX_IDLE_CONNS`: Maximum idle connections (default: 5)
- `DB_CONN_MAX_LIFETIME`: Connection max lifetime (default: 5m)

Cross-layer sync:
- Updated backend config parsing
- Updated frontend config display
- Updated English and Chinese documentation

Validation:
- All tests passing
- golangci-lint clean
- Manual testing: connection pooling working as expected

Closes #123
```

**Next steps:**
1. Review the changes with `git diff --cached`
2. Perform manual testing if needed
3. Commit when ready: `git commit` (message already prepared above)
```

Or if failures occurred:

```
## Post-Development Workflow: Issues Found

### Phase 1: Code Validation ❌
- Frontend lint failed: 3 errors in AirportDialog.jsx

Fixing now...
```

Or if Phase 6 was skipped (THIS SHOULD NEVER HAPPEN):

```
## ❌ CRITICAL ERROR: Pre-Commit Validation Skipped

Phase 6 (pre-commit-check) was not invoked. This is a MANDATORY step.

Invoking pre-commit-check now...
```

---

## Anti-Patterns to Avoid

❌ **Skipping validation** because "it's a small change"
- Small changes still need lint/format/test

❌ **Updating only English docs** and forgetting Chinese versions
- Both languages must be updated together

❌ **Changing backend API without updating frontend**
- Cross-layer sync is mandatory

❌ **Declaring work "done" without running this workflow**
- This workflow IS part of "done"

❌ **Running validation but not fixing failures**
- All validation must pass before proceeding

❌ **Updating code without updating documentation**
- Documentation is part of the deliverable

❌ **Auto-committing without user verification**
- Stage changes and let user verify/test before committing

❌ **Committing without a proper change summary**
- Reviewers and future maintainers need context

---

## Related Skills

- `.agents/skills/pre-commit-check/SKILL.md` - Detailed pre-commit checklist (subset of this workflow)
- `.agents/skills/cross-layer-sync/SKILL.md` - Detailed cross-layer synchronization guide
- `.agents/skills/doc-sync-check/SKILL.md` - Detailed documentation sync guide
- `.agents/skills/theme-check/SKILL.md` - Theme-specific validation (when UI colors/surfaces changed)
- `.agents/skills/security-review/SKILL.md` - Security review checklist (for auth/sensitive data changes)
- `.agents/skills/performance-check/SKILL.md` - Performance review checklist (for optimization work)

---

## Reference Documentation

Detailed information extracted to separate files for maintainability:

- **`references/validation-commands.md`** - Complete validation command reference, troubleshooting, and quality standards
- **`references/cross-layer-sync-rules.md`** - Detailed cross-layer synchronization patterns, verification commands, and special cases
- **`references/documentation-sync-rules.md`** - Documentation synchronization requirements, templates, and bilingual standards
- **`references/commit-message-guide.md`** - Commit message format, examples, and best practices
- **`assets/commit-template.txt`** - Commit message template for git config

---

## For Human Contributors

This workflow is also useful for manual development:

1. After completing your code change, open this file
2. Go through each phase sequentially
3. Check off items as you complete them
4. Don't skip phases unless justified
5. Stage your changes with `git add`
6. Review staged changes with `git diff --cached`
7. Perform manual testing/verification as needed
8. Commit when satisfied: `git commit` (use the prepared message as template)

This ensures consistent quality across all contributions, whether from AI or humans.

**Note**: AI agents will stage changes and prepare commit messages, but will NOT auto-commit. This allows you to:
- Review the staged changes
- Perform manual testing
- Make additional adjustments if needed
- Commit only when you're satisfied with the changes