cfsa-antigravity 1.0.0

package/template/.agent/skills/api-versioning/SKILL.md

@@ -0,0 +1,420 @@
+---
+name: api-versioning
+description: "Manage API versioning and evolution with URL/header/query strategies, deprecation workflows, breaking change classification, sunset headers, and consumer-driven contract testing. Use when designing versioning strategy, deprecating endpoints, or evolving API contracts."
+version: 1.0.0
+---
+
+# API Versioning & Evolution
+
+APIs are contracts with consumers. Breaking that contract destroys trust. This skill covers how to version, evolve, and deprecate APIs without breaking clients.
+
+## Versioning Strategies
+
+### Strategy Comparison
+
+| Strategy | Example | Pros | Cons |
+|----------|---------|------|------|
+| **URL path** | `/api/v2/models` | Obvious, cacheable, easy routing | URL represents resource not version; copies endpoints |
+| **Header** | `API-Version: 2` | Clean URLs, content negotiation | Hidden from browser, harder to test |
+| **Query param** | `/api/models?version=2` | Easy to test, no routing changes | Pollutes query string, cache key complexity |
+| **Accept header** | `Accept: application/vnd.api.v2+json` | Proper content negotiation | Verbose, often misunderstood |
+
+### Recommendation
+
+Use **URL path versioning** for public APIs (simplicity and discoverability). Use **header versioning** for internal/partner APIs (cleaner resource model).
+
+### URL Path Versioning
+
+```typescript
+// src/pages/api/v1/models/[id].ts
+export async function GET({ params }: APIContext) {
+  // V1 response shape
+  return new Response(JSON.stringify({
+    id: params.id,
+    name: model.name,
+    provider: model.provider,
+    // V1 had a flat pricing field
+    price_per_token: model.pricePerToken,
+  }));
+}
+
+// src/pages/api/v2/models/[id].ts
+export async function GET({ params }: APIContext) {
+  // V2 response shape (nested pricing)
+  return new Response(JSON.stringify({
+    id: params.id,
+    name: model.name,
+    provider: model.provider,
+    // V2 has structured pricing
+    pricing: {
+      input: model.inputPrice,
+      output: model.outputPrice,
+      currency: 'USD',
+      unit: 'per_million_tokens',
+    },
+  }));
+}
+```
+
+### Header Versioning
+
+```typescript
+// Version routing middleware
+function versionRouter(handlers: Record<string, Handler>): Handler {
+  return async (context) => {
+    const version = context.request.headers.get('API-Version')
+      ?? context.url.searchParams.get('version')
+      ?? DEFAULT_VERSION;
+
+    const handler = handlers[version];
+    if (!handler) {
+      return new Response(JSON.stringify({
+        type: 'https://api.example.com/problems/unsupported-version',
+        title: 'Unsupported API Version',
+        status: 400,
+        detail: `API version '${version}' is not supported. Supported versions: ${Object.keys(handlers).join(', ')}`,
+      }), { status: 400, headers: { 'Content-Type': 'application/problem+json' } });
+    }
+
+    const response = await handler(context);
+    response.headers.set('API-Version', version);
+    return response;
+  };
+}
+
+// Usage
+export const GET = versionRouter({
+  '1': handleV1,
+  '2': handleV2,
+});
+```
+
+---
+
+## Default Version Behavior
+
+When a client does not specify a version, the API must behave predictably.
+
+| Strategy | Behavior | When to Use |
+|----------|----------|-------------|
+| **Default to latest** | Unversioned requests get the newest version | Internal APIs with controlled consumers |
+| **Default to oldest supported** | Unversioned requests get V1 | Public APIs (avoid surprise breakage) |
+| **Require explicit version** | Return 400 if no version specified | Strict APIs where ambiguity is unacceptable |
+
+```typescript
+const DEFAULT_VERSION = '1'; // Conservative default for public APIs
+
+function resolveVersion(request: Request): string {
+  return request.headers.get('API-Version')
+    ?? request.url.searchParams.get('version')
+    ?? DEFAULT_VERSION;
+}
+```
+
+---
+
+## Breaking vs Non-Breaking Changes
+
+### Non-Breaking (Safe to Ship)
+
+| Change | Example | Why It Is Safe |
+|--------|---------|---------------|
+| Add optional field to response | `"avatar_url": "..."` added to user response | Clients ignore unknown fields |
+| Add optional query parameter | `?sort=name` now supported | Existing queries still work |
+| Add new endpoint | `POST /api/v1/webhooks` | Does not affect existing endpoints |
+| Widen accepted input types | Field accepts `string \| number` instead of just `string` | Existing valid inputs remain valid |
+| Add optional request field | `"metadata": {}` now accepted | Existing requests without it still work |
+| Relax validation | Max length changed from 100 to 200 | Previously valid inputs still valid |
+
+### Breaking (Requires New Version)
+
+| Change | Example | Why It Breaks |
+|--------|---------|---------------|
+| Remove field from response | `price_per_token` removed | Clients reading this field break |
+| Rename field | `price_per_token` renamed to `pricing` | Clients reading old name break |
+| Change field type | `price` from number to object | Parsing breaks |
+| Remove endpoint | `DELETE /api/v1/legacy` | Clients calling it get 404 |
+| Add required request field | `"region"` now required | Existing requests missing it fail |
+| Tighten validation | Max length changed from 200 to 100 | Previously valid inputs now rejected |
+| Change error response format | Different error shape | Client error handling breaks |
+| Change authentication scheme | Bearer token to API key | Auth headers break |
+
+---
+
+## Additive-Only API Policy
+
+The safest evolution strategy: never remove or rename, only add.
+
+```typescript
+// V1 response (original)
+interface ModelV1 {
+  id: string;
+  name: string;
+  price_per_token: number; // original flat field
+}
+
+// V1.1 response (additive evolution --- no new version needed)
+interface ModelV1_1 {
+  id: string;
+  name: string;
+  price_per_token: number; // KEPT for backward compatibility
+  pricing: {              // ADDED new structured field
+    input: number;
+    output: number;
+    currency: string;
+    unit: string;
+  };
+}
+// Clients reading price_per_token still work.
+// New clients use pricing object.
+// Remove price_per_token only in V2.
+```
+
+---
+
+## Sunset Headers and Deprecation Workflow
+
+### Sunset Header (RFC 8594)
+
+```typescript
+function addDeprecationHeaders(response: Response, sunsetDate: string, docUrl: string): Response {
+  response.headers.set('Deprecation', 'true');
+  response.headers.set('Sunset', sunsetDate); // HTTP date format
+  response.headers.set('Link', `<${docUrl}>; rel="sunset"`);
+  return response;
+}
+
+// Usage
+const response = await handleV1Request(context);
+addDeprecationHeaders(
+  response,
+  'Sat, 01 Mar 2026 00:00:00 GMT',
+  'https://docs.example.com/migration/v1-to-v2'
+);
+```
+
+### Deprecation Timeline
+
+| Phase | Duration | Actions |
+|-------|----------|---------|
+| **Announce** | T-6 months | Add `Deprecation: true` header, publish migration guide |
+| **Warn** | T-3 months | Add `Sunset` header with date, send email to consumers |
+| **Monitor** | T-1 month | Track usage, notify active consumers directly |
+| **Sunset** | T-0 | Return 410 Gone with migration link |
+| **Remove** | T+3 months | Remove code (keep tests to prevent regression) |
+
+### Sunset Response
+
+```typescript
+function sunsetResponse(migrationUrl: string): Response {
+  return new Response(JSON.stringify({
+    type: 'https://api.example.com/problems/gone',
+    title: 'API Version Removed',
+    status: 410,
+    detail: `This API version has been sunset. Please migrate to the latest version.`,
+    migrationGuide: migrationUrl,
+  }), {
+    status: 410,
+    headers: {
+      'Content-Type': 'application/problem+json',
+      'Link': `<${migrationUrl}>; rel="successor-version"`,
+    },
+  });
+}
+```
+
+---
+
+## Consumer-Driven Contract Testing
+
+Consumers define the contract they depend on. The provider runs these contracts in CI to ensure backward compatibility.
+
+```typescript
+// consumer-contracts/model-service.contract.test.ts
+import { describe, it, expect } from 'vitest';
+
+describe('Model API Contract (Consumer: Dashboard)', () => {
+  it('GET /api/v1/models/:id returns expected shape', async () => {
+    const response = await fetch(`${API_URL}/api/v1/models/gpt-4`);
+    const data = await response.json();
+
+    // Consumer only depends on these fields --- adding fields is fine
+    expect(data).toMatchObject({
+      id: expect.any(String),
+      name: expect.any(String),
+      provider: expect.any(String),
+    });
+
+    // These fields must exist with these types
+    expect(typeof data.id).toBe('string');
+    expect(typeof data.name).toBe('string');
+  });
+
+  it('returns 404 for unknown model', async () => {
+    const response = await fetch(`${API_URL}/api/v1/models/nonexistent`);
+    expect(response.status).toBe(404);
+  });
+});
+```
+
+**Provider CI pipeline runs all consumer contracts before deploy:**
+```yaml
+# .github/workflows/api-deploy.yml
+jobs:
+  contract-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Run consumer contracts
+        run: pnpm test:contracts
+      # Deploy only if contracts pass
+  deploy:
+    needs: contract-tests
+    # ...
+```
+
+---
+
+## Changelog Automation
+
+### Conventional Commits for API Changes
+
+```
+feat(api): add /api/v1/webhooks endpoint
+fix(api): correct pagination cursor encoding in /api/v1/models
+deprecate(api): mark /api/v1/legacy/search as deprecated
+breaking(api): remove price_per_token field from /api/v2/models response
+```
+
+### Generated Changelog
+
+```markdown
+## API Changelog
+
+### v2.3.0 (2026-02-15)
+
+#### Added
+- `GET /api/v1/webhooks` - List registered webhooks
+- `POST /api/v1/webhooks` - Register a new webhook
+
+#### Deprecated
+- `GET /api/v1/legacy/search` - Use `GET /api/v1/search` instead. Sunset: 2026-08-01.
+
+#### Fixed
+- Pagination cursor encoding now handles special characters correctly
+
+### v2.0.0 (2026-01-01)
+
+#### Breaking Changes
+- Removed `price_per_token` field from model responses. Use `pricing` object instead.
+- See [migration guide](https://docs.example.com/migration/v1-to-v2).
+```
+
+---
+
+## Migration Guides
+
+Every version bump must include a migration guide that covers:
+
+```markdown
+# Migrating from API v1 to v2
+
+## Timeline
+- **v1 deprecated:** January 1, 2026
+- **v1 sunset:** July 1, 2026
+- **v1 removed:** October 1, 2026
+
+## Breaking Changes
+
+### Model pricing field restructured
+
+**Before (v1):**
+```json
+{ "price_per_token": 0.00003 }
+```
+
+**After (v2):**
+```json
+{ "pricing": { "input": 0.00001, "output": 0.00003, "currency": "USD", "unit": "per_million_tokens" } }
+```
+
+**Migration steps:**
+1. Update your response type definitions
+2. Replace `model.price_per_token` with `model.pricing.output`
+3. Test with v2 endpoint
+4. Update API-Version header to `2`
+```
+
+---
+
+## Version Routing Middleware
+
+```typescript
+// src/middleware/api-version.ts
+type VersionedHandlers = Record<string, Handler>;
+
+export function createVersionedRoute(
+  handlers: VersionedHandlers,
+  options: {
+    defaultVersion?: string;
+    deprecated?: Record<string, { sunset: string; migrationUrl: string }>;
+  } = {}
+): Handler {
+  const { defaultVersion, deprecated = {} } = options;
+
+  return async (context) => {
+    const version = resolveVersion(context.request) ?? defaultVersion;
+
+    if (!version) {
+      return problemResponse({
+        type: 'https://api.example.com/problems/version-required',
+        title: 'API Version Required',
+        status: 400,
+        detail: 'Please specify an API version via the API-Version header.',
+      });
+    }
+
+    if (!(version in handlers)) {
+      return problemResponse({
+        type: 'https://api.example.com/problems/unsupported-version',
+        title: 'Unsupported API Version',
+        status: 400,
+        detail: `Version '${version}' is not supported.`,
+      });
+    }
+
+    const response = await handlers[version](context);
+    response.headers.set('API-Version', version);
+
+    // Add deprecation headers if applicable
+    if (version in deprecated) {
+      const { sunset, migrationUrl } = deprecated[version];
+      response.headers.set('Deprecation', 'true');
+      response.headers.set('Sunset', sunset);
+      response.headers.set('Link', `<${migrationUrl}>; rel="sunset"`);
+    }
+
+    return response;
+  };
+}
+```
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Correct Approach |
+|-------------|------------------|
+| Increment version for every change | Version only on breaking changes |
+| Remove old version without notice | Follow deprecation timeline (6+ months) |
+| Different versioning per endpoint | Consistent strategy across the entire API |
+| Version in the response body only | Use URL path or headers --- visible and consistent |
+| No default version behavior | Define and document the default |
+| Breaking change without migration guide | Every breaking change needs a guide |
+| No consumer notification | Email, changelog, and headers all used together |
+
+## References
+
+- [RFC 8594: Sunset Header](https://tools.ietf.org/html/rfc8594)
+- [Stripe API Versioning](https://stripe.com/docs/api/versioning)
+- [Microsoft REST API Guidelines: Versioning](https://github.com/microsoft/api-guidelines)
+- [Pact Contract Testing](https://docs.pact.io/)

package/template/.agent/skills/architecture-mapping/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: architecture-mapping
+description: Analyzes codebase structure, data flow, module relationships, and key patterns to generate and maintain a living architecture document (ARCHITECTURE.md).
+---
+
+# Architecture Mapping Skill
+
+You are an expert software architect acting as a cartographer for the codebase. Your job is to analyze the current state of a repository and produce a "living map" of its architecture.
+
+## Core Responsibilities
+
+When invoked, you must:
+
+1.  **Analyze structural layout at a granular level:** Identify exactly where specific functionality lives, listing out key files (e.g., `src/api/worker.ts`, specific domain schemas, core components). **Do not just list directories; list the critical files within them**.
+2.  **Trace data flow explicitly:** Determine how information moves through the system down to the exact environment bindings, database connections (e.g., SurrealDB KV bindings, Worker `Env` interfaces), and request interceptors.
+3.  **Map relationships & contracts:** Detail the actual Zod schemas and API routes present in the codebase. If an API worker exists, document its exposed routes, rate limiting, and exact CORS configurations.
+4.  **Extract key patterns:** Identify the architectural decisions and conventions in use, providing exact file references where these patterns are implemented (e.g., CFPA, React Islands).
+5.  **Generate/Update Document:** Write these highly granular findings into a structured `docs/ARCHITECTURE.md` file. Avoid generic boilerplate; if the project only has 3 files, document precisely what those 3 files do.
+
+## Execution Strategy
+
+Follow these strictly granular steps to perform an architecture mapping:
+
+### Step 1: Deep Codebase Reconnaissance
+- **Do not just list directories.** Use your file exploration tools (`list_dir`, `view_file_outline`, `grep_search`) to survey the repository, but immediately follow up by reading the *contents* of key files (`view_file`).
+- Identify exact entry points (`src/api/worker.ts`, `src/pages/index.astro`), configuration files (`astro.config.mjs`, `wrangler.toml`), and trace their imports.
+- Locate exact schemas (Zod or TypeScript interfaces) defining the data models.
+
+### Step 2: Component & Contract Analysis
+- Group files logically, but identify the specific files governing these components.
+- For each component, trace its exact Zod schemas, API routes, or React props.
+- Document exact environment variables and secrets expected by the code.
+
+### Step 3: Granular Dependency Tracing
+- Trace exactly how components interact (e.g., "The `login` Astro page fetches data directly from SurrealDB using the `surrealdb.js` client in `src/lib/db.ts`").
+- Explicitly catalog external integrations down to the binding name (e.g., "KVNamespace RATE_LIMITS").
+
+### Step 4: Pattern Extraction
+- Read the implementation details of representative files to prove use of architectural patterns.
+- If the project uses CFPA, locate the schema, the test, and the implementation file as proof.
+
+## 5. Document Generation
+Create or update `docs/ARCHITECTURE.md` using the following structure:
+
+```markdown
+# [Project Name] - Living Architecture Map
+
+**Last Updated:** [Current Date]
+**Purpose:** Deep, granular code context, environmental bindings, and exact architectural tracing.
+
+---
+
+## 1. Codebase Topography & Critical Files
+
+### Directory Tree
+(You MUST include a full, comprehensive file/folder tree of the `src/` directory and any other relevant project directories. Do not summarize this; show the actual files.)
+```text
+/
+├── src/
+│   ├── api/
+│   │   └── worker.ts
+│   └── ...
+```
+
+### Critical Files
+(Identify exactly where specific functionality lives, listing out key files defined in the tree above. Do not just list directories; explain what the critical files within them do.)
+
+## 2. Infrastructure & Explicit Data Flow
+(Determine how information moves through the system down to the exact environment bindings, database connections, and request interceptors.)
+
+## 3. Module Relationships & Contracts
+(Detail the actual Zod schemas and API routes present. Document exposed routes, rate limiting, and exact CORS configurations.)
+
+## 4. Key Patterns & Implementation Evidence
+(Identify architectural decisions, providing exact file references where these patterns are implemented.)
+```
+
+## Best Practices
+
+*   **Granularity is Mandatory:** Do not describe the system abstractly. Use exact file paths, exact schema names, and exact environment binding names.
+*   **Trace the Code:** Never guess architectural boundaries. Use `grep_search` and `view_file` to trace imports and confirm how modules interact before documenting them.
+*   **Be Explicit:** Avoid boilerplate. If an API has 3 endpoints, list the 3 endpoints and their exact Zod validation schemas.
+*   **Living Document:** If updating an *existing* `ARCHITECTURE.md`, do not simply append. Integrate new, granular findings holistically into the existing structure. Update the "Last Updated" date.
+
+## Domain Boundary Protocol
+
+### Purpose
+
+Run this protocol before proposing domain boundaries. Uses a domain inventory record to evaluate every candidate domain.
+
+### Domain Inventory Record Format
+
+For each candidate domain, build a record in the following format:
+
+```
+Domain: [name]
+Architecture description: [one-line summary from architecture design]
+Ideation sub-features:
+  1. [Actor] can [goal] → primary data: [entity/table]
+  2. [Actor] can [goal] → primary data: [entity/table]
+  ...
+Split trigger: [none | review | mandatory-split]
+```
+
+Read `docs/plans/ideation.md` and the architecture design to build each record.
+
+### Split Trigger Rules
+
+Apply all three rules to every domain:
+
+1. **80-line proxy** — If the `ideation.md` section for this domain exceeds ~80 lines of content (features, user stories, acceptance criteria combined), flag as `mandatory-split`.
+
+2. **3-table rule** — If the domain's sub-features touch ≥3 independent database tables with no shared queries, flag as `mandatory-split`.
+
+3. **No-shared-query test** — If two sub-feature groups within a domain could each be assigned to a different developer without coordination (no shared API endpoints, no shared data mutations), flag as `review`.
+
+### Domain Boundary Table Template
+
+| # | Domain | Features Included | Sub-feature Count | Complexity | Split Candidate? | Needs Deep Dive? |
+|---|--------|-------------------|-------------------|------------|-----------------|------------------|
+| 00 | Cross-cutting | Auth, API conventions, error handling | — | Medium | — | No |
+| 01 | [Domain] | [Features] | [N] | [Low/Med/High] | [Yes/No — reason] | [Yes/No] |
+
+### User Approval Protocol
+
+Present split candidates to the user before finalising the domain boundary table. For each candidate show:
+
+- Domain name
+- Sub-feature list
+- Proposed split boundary
+- Rationale
+
+User must approve or reject each split before the table is locked.
+
+### Shard Numbering Convention
+
+- `00-*` for cross-cutting concerns (may be multiple)
+- `01-*` through `NN-*` for feature domains ordered by dependency (dependencies first)
+
+## Sub-Feature Reconciliation Protocol
+
+### Purpose
+
+Run this protocol when beginning any architecture spec shard. `ideation.md` is the primary source of truth for sub-features — the architecture design is secondary context.
+
+### Sources to Read
+
+1. `docs/plans/ideation.md` — the section corresponding to this shard's domain
+2. The shard's `## Features` section
+3. `docs/plans/vision.md` Must Have features for this domain
+
+### Reconciliation Table
+
+| Sub-feature | ideation.md | Shard ## Features | Must Have? | Decision |
+|-------------|-------------|-------------------|------------|----------|
+| [name] | ✅ Listed | ✅ Listed | Yes/No | Keep |
+| [name] | ✅ Listed | ❌ Missing | Yes | **Add to shard immediately** |
+| [name] | ✅ Listed | ❌ Missing | No | Add to shard — ideation is authoritative |
+| [name] | ❌ Not listed | ✅ Listed | — | `[Architecture-only — not in ideation.md]` — keep but audit |
+
+### Mismatch Handling Rules
+
+1. If a sub-feature appears in `ideation.md` but not in the shard's `## Features` → **add it to the shard's `## Features` section immediately** before proceeding. Do not wait for user confirmation to add ideation-sourced sub-features.
+
+2. If a sub-feature appears in the shard's `## Features` but not in `ideation.md` → **keep it** but mark it with `[Architecture-only — not in ideation.md]` as an audit trail. These items need explicit user confirmation.
+
+### Scope Confirmation Presentation Format
+
+Present the reconciled scope to the user in the following format:
+
+> **Reconciled features for [Shard NN — Domain Name]:**
+>
+> [bullet list of all sub-features, with `[Architecture-only]` markers where applicable]
+>
+> **[N] sub-features added from ideation.md** that were missing from the shard skeleton.
+> **[M] sub-features marked `[Architecture-only]`** — not found in ideation.md, added during decomposition.
+>
+> "Does this feature list match your intent for this domain? Any sub-features to add, remove, or re-scope?"
+
+Wait for explicit user confirmation before proceeding. If the user modifies the list, update the shard file immediately.
+
+## Sub-Feature Complexity Split Protocol
+
+### Purpose
+
+Run this protocol after reconciliation when the confirmed sub-feature count is **≥ 10**. This threshold indicates the shard is too complex for a single spec pass and must be split before writing proceeds.
+
+### Counting Rule
+
+Count every bullet or named item under the confirmed feature list, excluding group headers. Use the same counting rule as `/decompose-architecture-validate` Step 12.
+
+### Split Proposal Format
+
+Present to the user:
+
+```
+Shard [NN] — [domain name] has [N] sub-features (threshold: ≥10 → mandatory split)
+
+Current sub-features:
+  1. [sub-feature]
+  2. [sub-feature]
+  ...
+
+Proposed split:
+  [NN]a — [new domain name] → file: docs/plans/ia/[NN]a-[domain].md
+    Sub-features: 1, 3, 5
+  [NN]b — [new domain name] → file: docs/plans/ia/[NN]b-[domain].md
+    Sub-features: 2, 4, 6
+
+Split rationale: [why these groups are independent]
+
+Does this split make sense, or would you prefer a different boundary?
+```
+
+### Approval Gate
+
+**Wait for explicit user approval of the split before proceeding.** Do NOT continue spec writing with an oversized shard.
+
+If the user approves: stop the current workflow and run `/decompose-architecture-validate` to formally register the new shards (it will re-run the Must Have coverage gate and update the decomposition plan). Then restart the spec workflow for each new shard individually.