name	contract-synchronization
description	Playbook for managing API contract schemas, generating client code, and verifying backend/frontend synchronization.

API Contract & Multi-Project Synchronization Playbook

This playbook defines the standards and workflows for maintaining absolute contract compliance and synchronization between backend and frontend sub-projects in a monorepo workspace.

1. Shared Schema: The Single Source of Truth

To prevent API contract mismatch and runtime integration errors:

Define a Contract: Place a machine-readable API specification (e.g., openapi.yaml, schema.json, or shared Type Definitions) in a shared directory at the root of the workspace or in the backend's public docs directory (e.g., docs/openapi.yaml).
Never Define Types Manually: The frontend must not manually recreate request/response interfaces or endpoint routes. All API-related types, endpoints, and HTTP client bindings must be derived from the shared schema.

2. Automated Frontend Client Codegen

To synchronize changes instantly from Backend $\rightarrow$ Frontend:

Codegen Trigger: When backend API models are modified, run the client code generator (e.g. openapi-generator-cli, orval, or custom typescript generators) to regenerate types and fetching hooks inside the frontend directory (e.g. app/frontend/src/api/).
Check-in Policy: Generated client files MUST be checked into source control along with the API contract modification. The build pipeline will fail if the code generator produces unstaged changes.

3. Double-Sided Contract Verification

Validation must happen on both ends of the interface boundary:

A. Backend-Side Verification

Validate that the actual endpoints match the declared API specification.
Use schema-driven test runners (e.g., Schemathesis in Python, or openapi-validator in Node.js) to dynamically fuzz or test backend routes against the OpenAPI file:
```
schemathesis run docs/openapi.yaml --base-url http://localhost:8000/api
```

B. Frontend-Side Verification

Ensure the frontend build process strictly compiles against the generated TypeScript definitions.
Running npm run build or tsc --noEmit in the frontend directory serves as the final gate to verify that all API components, arguments, and data shapes match the backend payload.

4. Multi-Project Validation Gate

When validation is run, the agent must check all projects. The root validation script validate.py reads .agents/projects.json to automatically run tests in each sub-directory (e.g., app/backend and app/frontend), ensuring that changes in one module do not break the tests in the other.

Más de este repositorio

mismo repositorio

task-management

rafaelghif/antigravity-agents

Playbook for capturing design alignment from /grill-me, generating issue specifications, and managing task boards.

2026-07-112

skill-evolution

rafaelghif/antigravity-agents

Playbook instructing agents how to dynamically formulate, design, bootstrap, and register new workspace skills when facing skill gaps.

2026-07-092

conversational-agent

rafaelghif/antigravity-agents

Playbook for translating natural language requests about tasks, profiles, locking, and validation into CLI helper executions.

2026-07-022

database-evolution

rafaelghif/antigravity-agents

Playbook for writing safe database migrations, managing schema evolutions, executing reversible rollbacks, and avoiding table lock contention in enterprise environments.

2026-07-022

performance-optimization

rafaelghif/antigravity-agents

Guidelines for CPU profiling, identifying database query bottlenecks (N+1 queries), diagnosing memory leaks, and optimizing resource execution speeds.

2026-07-022

release-management

rafaelghif/antigravity-agents

Guidelines for containerization (Dockerfile best practices), release versioning, blue-green deployment, feature flag rollouts, and post-deployment smoke verification.

2026-07-022

name	contract-synchronization
description	Playbook for managing API contract schemas, generating client code, and verifying backend/frontend synchronization.

API Contract & Multi-Project Synchronization Playbook

This playbook defines the standards and workflows for maintaining absolute contract compliance and synchronization between backend and frontend sub-projects in a monorepo workspace.

1. Shared Schema: The Single Source of Truth

To prevent API contract mismatch and runtime integration errors:

Define a Contract: Place a machine-readable API specification (e.g., openapi.yaml, schema.json, or shared Type Definitions) in a shared directory at the root of the workspace or in the backend's public docs directory (e.g., docs/openapi.yaml).
Never Define Types Manually: The frontend must not manually recreate request/response interfaces or endpoint routes. All API-related types, endpoints, and HTTP client bindings must be derived from the shared schema.

2. Automated Frontend Client Codegen

To synchronize changes instantly from Backend $\rightarrow$ Frontend:

Codegen Trigger: When backend API models are modified, run the client code generator (e.g. openapi-generator-cli, orval, or custom typescript generators) to regenerate types and fetching hooks inside the frontend directory (e.g. app/frontend/src/api/).
Check-in Policy: Generated client files MUST be checked into source control along with the API contract modification. The build pipeline will fail if the code generator produces unstaged changes.

3. Double-Sided Contract Verification

Validation must happen on both ends of the interface boundary:

A. Backend-Side Verification

Validate that the actual endpoints match the declared API specification.
Use schema-driven test runners (e.g., Schemathesis in Python, or openapi-validator in Node.js) to dynamically fuzz or test backend routes against the OpenAPI file:
```
schemathesis run docs/openapi.yaml --base-url http://localhost:8000/api
```

B. Frontend-Side Verification

Ensure the frontend build process strictly compiles against the generated TypeScript definitions.
Running npm run build or tsc --noEmit in the frontend directory serves as the final gate to verify that all API components, arguments, and data shapes match the backend payload.