| name | cross-layer-sync |
| description | Cross-layer synchronization guide for backend, frontend, and documentation changes. Invoked by post-dev-workflow when changes affect multiple layers. Not for direct user invocation. |
| version | 1.0.0 |
| author | SublinkPro Team |
| user-invocable | false |
Cross-Layer Synchronization Check Skill
Checklist for ensuring all impacted layers are updated together when changes affect multiple parts of the application.
When to use this skill
Use this skill when changes affect:
- API contracts, routes, request/response structures
- Frontend-backend data flow
- Configuration semantics
- Documentation that reflects runtime behavior
- User-facing text or error messages
- Deployment or build processes
Core Principle
Changes must be atomic across layers: When a change affects multiple layers (backend, frontend, docs, skill API reference), all impacted layers must be updated in the same PR/commit.
Prerequisites
Before running this checklist:
- Identify which layers your change touches
- Read AGENTS.md section 9 "Cross-layer synchronization"
- Review CONTRIBUTING.md for cross-layer sync requirements
Backend → Frontend Sync Checklist
When backend changes affect:
API contracts
Fields
Permissions
Response structures
Task results or notifications
Skill API (if /api/v1/* or /c/* changed)
Frontend → Backend Sync Checklist
When frontend changes affect:
API dependencies
Field semantics
Page flows
i18n keys
Configuration → All Layers Sync Checklist
When configuration changes affect:
Environment variables
Default values
Config precedence
Documentation Sync Checklist
When behavior changes require doc updates:
User-facing features
Developer workflows
Configuration or deployment
API contracts
Documentation map
Bilingual consistency
Verification Checklist
Code verification
Manual verification
When one layer doesn't need changes
If you've checked an impacted layer and confirmed it truly doesn't need changes, document this in your change summary:
Example: "Checked frontend API layer (webs/src/api/subscriptions.js) - no changes needed because new backend field is optional and frontend uses default behavior."
Common Cross-Layer Change Patterns
Adding a new API endpoint
- Backend: Add route, handler, validation
- Frontend: Add API client function (
webs/src/api/)
- Frontend: Add UI component/view (
webs/src/views/)
- i18n: Add translations for UI text
- Docs: Update
skill-sublinkpro/reference/api.md
- Tests: Add backend handler tests
Changing a data model field
- Backend: Update model, migration, validation
- Backend: Update API handlers
- Frontend: Update API calls
- Frontend: Update display components
- Frontend: Update forms/inputs
- Docs: Update feature documentation
Modifying configuration behavior
- Backend: Update config parsing
- Backend: Update runtime behavior
- Docs: Update
docs/configuration.md + .zh-CN.md
- Docs: Update example configs
- Docs: Update
skill-sublinkpro/reference/deploy.md
- Tests: Add config validation tests
Delivery Requirements
Before marking complete, the change summary must include:
- Layers changed: List which layers were modified
- Layers checked: List which layers were inspected but didn't need changes
- Justification: For unchanged layers, briefly explain why no sync was needed
- Verification: List which validation commands were run
Anti-patterns to avoid
- ❌ Changing backend API without updating frontend
- ❌ Changing frontend behavior without verifying backend support
- ❌ Updating code without updating documentation
- ❌ Updating only English docs without Chinese versions
- ❌ Claiming "no sync needed" without actually checking
Exit criteria
✅ Can exit when:
- All impacted layers are synchronized
- Verification commands pass
- Documentation is updated (both languages)
- Change summary documents what was checked
❌ Cannot exit when:
- Code changed but docs still describe old behavior
- Backend changed but frontend still uses old contract
- Frontend changed but backend compatibility not verified
- One language docs updated but not the other
