codex-genesis-harness 0.1.1 → 0.1.4

package/.codex/skills/genesis-api-sync/SKILL.md

@@ -0,0 +1,354 @@
+---
+name: api-sync-skill
+description: Automatic API contract synchronization. Detects API changes in implementation, updates API_CONTRACTS.md, regenerates test contracts, and maintains backward compatibility documentation. Use after API-related implementation or when contracts drift from actual code.
+---
+
+# API Sync Skill
+
+## Purpose
+
+Keep API contracts synchronized with actual implementation. Detect changes, update contracts, regenerate tests, and document breaking changes automatically.
+
+## When to use
+
+Use after API-related implementation when:
+- New endpoints added
+- Endpoint behavior changed
+- Request/response schemas modified
+- Error handling updated
+- Authentication/authorization changed
+- Deprecated endpoints need removal
+
+## When NOT to use
+
+Do not use for read-only API documentation or when contract-first design hasn't been completed yet.
+
+## Inputs required
+
+- Changed implementation files (API routes, controllers, handlers)
+- Current API_CONTRACTS.md file
+- Test suite location
+- Breaking change impact assessment
+
+## Outputs required
+
+- Updated API_CONTRACTS.md with all changes
+- Updated API test contracts
+- Test code reflecting new contracts
+- Migration guide for breaking changes (if applicable)
+- Backward compatibility documentation
+
+## Required tests
+
+- Contract validation tests (request/response schemas)
+- API integration tests updated
+- Backward compatibility tests (if versioning)
+- Error handling tests
+
+## Required fixtures
+
+- Updated endpoint fixtures
+- Request/response examples
+- Error scenario fixtures
+- Edge case payloads
+
+## Required contract updates
+
+- API_CONTRACTS.md (primary)
+- Versioning info (if breaking changes)
+- Deprecation notices (if applicable)
+- Migration guide (if breaking changes)
+
+## Required codebase map updates
+
+- `.codebase/API_CONTRACTS.md` - complete update
+- `.codebase/CURRENT_STATE.md` - note API changes
+- `.codebase/KNOWN_PROBLEMS.md` - document migration issues
+- `.codebase/EVOLUTION_PLAN.md` - next API phases
+
+## Token saving rules
+
+Extract schemas programmatically; don't paste entire files. Focus on deltas from previous contracts. Link to test fixtures rather than duplicating examples.
+
+## Acceptance criteria
+
+- API contracts match actual implementation
+- All endpoints documented with schemas
+- Breaking changes clearly marked
+- Test contracts generated and passing
+- Migration paths documented for breaking changes
+- No contract drift validation passing
+
+## Common mistakes
+
+- Skipping breaking change documentation
+- Not updating test contracts in parallel
+- Leaving old endpoints undocumented
+- Forgetting error response contracts
+- Not validating backward compatibility
+
+## Recovery workflow
+
+If contracts drift or sync fails:
+1. Read current API_CONTRACTS.md
+2. Extract actual endpoint schemas from implementation
+3. Identify changes and breaking status
+4. Update contracts with full changelog
+5. Regenerate test contracts
+6. Validate all tests pass
+7. Document migration guide if needed
+
+---
+
+## Workflow: API Change Detection & Sync
+
+### Step 1: Detect API Changes
+
+Identify which files contain API code:
+
+```
+Scan for:
+  ├─ src/api/**
+  ├─ src/**/route.ts, routes.ts
+  ├─ src/**/controller.ts
+  ├─ src/**/endpoint.ts
+  └─ src/**/handler.ts
+```
+
+For each file, extract:
+- HTTP method (GET, POST, PUT, DELETE, PATCH)
+- Route/path
+- Request schema (params, query, body)
+- Response schema (success, error)
+- Status codes
+- Authentication requirements
+- Rate limiting or other middleware
+
+### Step 2: Compare Against Current Contract
+
+```
+For each endpoint:
+  New? → Add to contract
+  Modified? → Mark change and version
+  Deleted? → Mark as deprecated
+  Unchanged? → Keep as-is
+```
+
+### Step 3: Generate Updated Contracts
+
+```json
+{
+  "endpoints": [
+    {
+      "id": "endpoint-id",
+      "method": "POST",
+      "path": "/api/v1/resource",
+      "description": "Create a new resource",
+      "version": "1.0",
+      "breaking_changes_from": [],
+      "request": {
+        "body": { /* schema */ },
+        "query": { /* schema */ },
+        "headers": { /* required headers */ }
+      },
+      "responses": {
+        "200": { /* success schema */ },
+        "400": { /* error schema */ },
+        "401": { /* auth error */ }
+      },
+      "auth_required": true,
+      "rate_limit": "100/hour"
+    }
+  ]
+}
+```
+
+### Step 4: Mark Breaking Changes
+
+If changes break existing clients:
+
+```markdown
+## Breaking Changes in v2.0
+
+### Changed: POST /api/v1/resource
+- Old: Returns `id`, `name`, `created_at`
+- New: Returns `resourceId`, `title`, `timestamp`
+- Impact: Clients expecting `id` field will break
+- Migration: Map `resourceId` → `id` in client code
+- Deadline: Migrate by [date], v1 endpoints removed [date]
+```
+
+### Step 5: Generate Test Contracts
+
+Automatically create test schemas:
+
+```javascript
+// tests/contracts/api.test.ts
+import { apiContracts } from '.codebase/API_CONTRACTS.md'
+
+describe('API Contracts', () => {
+  apiContracts.endpoints.forEach(endpoint => {
+    it(`${endpoint.method} ${endpoint.path}`, async () => {
+      const response = await request(endpoint.method, endpoint.path)
+      validateSchema(response, endpoint.responses)
+    })
+  })
+})
+```
+
+### Step 6: Document Migration Path
+
+If breaking changes exist:
+
+```markdown
+## Migration Guide
+
+### From v1.0 → v2.0
+
+#### Step 1: Update request payloads
+```
+// OLD
+POST /api/v1/resource
+{ "name": "Test" }
+
+// NEW
+POST /api/v2/resource
+{ "title": "Test" }
+```
+
+#### Step 2: Update response parsing
+```
+// OLD
+const id = data.id
+
+// NEW
+const id = data.resourceId
+```
+
+#### Step 3: Timeline
+- June 1: v2 available alongside v1
+- July 1: Clients should migrate
+- August 1: v1 endpoints deprecated
+- September 1: v1 endpoints removed
+```
+
+---
+
+## Usage in Workflow
+
+### During Feature Implementation
+
+```bash
+# 1. Implement API changes
+# 2. Write tests with new contract
+# 3. Run tests - should pass
+
+# 4. After tests pass, sync contracts:
+invoke api-sync-skill
+
+# Parameters:
+- changed_files: ["src/api/users.ts", "src/routes/auth.ts"]
+- contract_file: ".codebase/API_CONTRACTS.md"
+- breaking_changes: true/false
+- version_bump: "major/minor/patch"
+```
+
+### After Sync Completed
+
+```
+✓ API_CONTRACTS.md updated
+✓ Breaking changes documented
+✓ Test contracts generated
+✓ Migration guide created
+✓ All tests still passing
+
+→ Ready to merge
+```
+
+---
+
+## Skills Integration
+
+Works alongside:
+- **planning-skill**: Captures API requirements in plan
+- **api-contract-skill**: Defines contracts before implementation
+- **design-spec-skill**: Documents API design decisions
+- **docs-skill**: Updates README and API docs
+
+---
+
+## Common Patterns
+
+### Pattern: API Versioning
+
+```
+OLD (v1)
+GET /api/users
+
+NEW (v2)
+GET /api/v2/users
+
+Contract update:
+- Keep v1 endpoint
+- Mark as deprecated
+- Point to v2 docs
+- Set removal date
+```
+
+### Pattern: Endpoint Evolution
+
+```
+Phase 1: New parameter added
+POST /api/resource → POST /api/resource?newParam=true
+Contract: Mark parameter as optional
+
+Phase 2: Parameter required
+POST /api/resource?newParam=true
+Contract: Mark parameter as required
+
+Phase 3: Old behavior removed
+POST /api/resource → now requires newParam
+Contract: Break version, update contract
+
+Clients get: 2 quarters to migrate
+```
+
+### Pattern: Error Code Addition
+
+```
+OLD
+POST /api/payment
+Error: 400 Bad Request
+
+NEW
+POST /api/payment
+Errors:
+  - 400 Bad Request
+  - 402 Payment Required (NEW)
+  - 429 Too Many Requests (NEW)
+
+Contract: Document all codes with examples
+```
+
+---
+
+## Acceptance Checklist
+
+- [ ] All endpoints extracted from code
+- [ ] Request/response schemas defined
+- [ ] HTTP methods correct
+- [ ] Status codes complete
+- [ ] Auth requirements documented
+- [ ] Breaking changes identified and marked
+- [ ] Test contracts generated
+- [ ] All API tests passing
+- [ ] Migration guide created (if needed)
+- [ ] `.codebase/API_CONTRACTS.md` updated
+- [ ] Documentation updated
+- [ ] Version number incremented
+
+---
+
+**Last Updated**: 2026-05-30  
+**Maintained By**: Genesis Harness Team  
+**Version**: 1.0

package/.codex/skills/genesis-api-sync/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "API Sync Skill"
+  short_description: "Automatic API contract synchronization with implementation"
+  default_prompt: "Use $genesis-api-sync to synchronize API contracts with the current implementation and detect breaking changes."
+
+policy:
+  allow_implicit_invocation: true

package/.codex/skills/genesis-api-sync/checklists/api-sync-checklist.md

@@ -0,0 +1,101 @@
+# API Sync Checklist
+
+**Use this after implementing API changes to verify sync is complete.**
+
+## Pre-Sync Verification
+
+- [ ] Implementation matches planned contract
+- [ ] All tests passing
+- [ ] Code review approved
+- [ ] No TODOs or incomplete sections
+
+## Contract Detection
+
+- [ ] Run API endpoint scanner
+  ```bash
+  ./scripts/extract-api-contracts.sh
+  ```
+- [ ] Compare with current API_CONTRACTS.md
+- [ ] Identify new/modified/deprecated endpoints
+- [ ] Log all changes
+
+## Breaking Change Assessment
+
+For each changed endpoint:
+- [ ] Does it break existing client code?
+- [ ] Do request parameters change? (required fields added?)
+- [ ] Do response fields change? (removed or changed structure?)
+- [ ] Do error codes change?
+- [ ] Does authentication requirement change?
+
+**Result: List all breaking changes**
+
+## Contract Update
+
+- [ ] Add new endpoints to API_CONTRACTS.md
+- [ ] Update modified endpoints with version info
+- [ ] Mark deprecated endpoints with removal date
+- [ ] Document all breaking changes
+- [ ] Add migration guide if needed
+- [ ] Update version number in contract
+
+## Test Contract Generation
+
+- [ ] Generate request/response validation schemas
+- [ ] Create test fixtures for new endpoints
+- [ ] Update test fixtures for modified endpoints
+- [ ] Create deprecation warning tests
+- [ ] Add error handling tests
+- [ ] Add edge case tests
+
+## Test Execution
+
+- [ ] All API tests passing
+- [ ] Contract validation tests passing
+- [ ] Integration tests passing
+- [ ] Backward compatibility tests (if v2+)
+- [ ] Coverage report generated (target: 80%+)
+
+## Documentation Updates
+
+- [ ] API_CONTRACTS.md complete and accurate
+- [ ] Examples updated
+- [ ] Migration guide created (if breaking changes)
+- [ ] README API section updated
+- [ ] CHANGELOG.md entry added
+- [ ] Version bumped (major/minor/patch)
+
+## Codebase State Update
+
+- [ ] .codebase/CURRENT_STATE.md updated
+- [ ] .codebase/API_CONTRACTS.md verified matches
+- [ ] .codebase/DEPENDENCY_GRAPH.md checked (new deps?)
+- [ ] .codebase/KNOWN_PROBLEMS.md updated if issues found
+
+## Migration Path Documentation
+
+If breaking changes:
+- [ ] Old endpoints documented as deprecated
+- [ ] Removal timeline specified
+- [ ] Migration steps documented
+- [ ] Code examples provided for migration
+- [ ] Timeline communicated to stakeholders
+
+## Final Verification
+
+- [ ] All changes tracked in git
+- [ ] No uncommitted files
+- [ ] PR description written with contract changes
+- [ ] All checklists marked complete
+- [ ] Ready for code review
+
+## Sign-Off
+
+- [ ] **API Owner**: ☐ Approved
+- [ ] **Technical Lead**: ☐ Approved
+- [ ] **QA**: ☐ Tested
+
+---
+
+**Date Completed**: _YYYY-MM-DD_  
+**Completed By**: _Name_

package/.codex/skills/genesis-api-sync/examples/example.md

@@ -0,0 +1,68 @@
+# Example: Sync API Contracts After Adding Payment Endpoint
+
+## Scenario
+
+A developer adds a new `POST /api/v2/payments` endpoint and updates the `GET /api/v2/payments/:id` response to include a `receiptUrl` field. After implementation is complete, contracts need to be synced.
+
+## Trigger
+
+```
+invoke api-sync-skill
+# Parameters:
+# changed_files: ["src/api/handlers/paymentHandler.ts", "src/routes/payments.ts"]
+# contract_file: ".codebase/API_CONTRACTS.md"
+# breaking_changes: false
+# version_bump: "minor"
+```
+
+## Step 1: Change Detection
+
+```
+Scanning changed files...
+
+Endpoint extracted: POST /api/v2/payments
+  Method: POST
+  Path: /api/v2/payments
+  Auth required: true
+  Request body: { amount, currency, paymentMethodId }
+  Response 201: { id, status, amount, currency, createdAt }
+  Response 400: { error, details }
+  Response 402: { error: "Payment required" }
+  Status: NEW
+
+Endpoint modified: GET /api/v2/payments/:id
+  Added field: receiptUrl (optional, string)
+  Breaking: NO (new optional field)
+  Status: CHANGED
+```
+
+## Step 2: Contract Updated
+
+**`.codebase/API_CONTRACTS.md`** updated:
+- Added full specification for `POST /api/v2/payments`
+- Updated `GET /api/v2/payments/:id` with new `receiptUrl` field
+- Version bumped: `1.2.0 → 1.3.0`
+
+## Step 3: Test Contracts Generated
+
+```ts
+// tests/contracts/payments.test.ts (auto-generated)
+it('POST /api/v2/payments — creates payment', async () => {
+  const res = await request.post('/api/v2/payments').send({...});
+  expect(res.status).toBe(201);
+  expect(res.body).toHaveProperty('id');
+  expect(res.body).toHaveProperty('status');
+});
+```
+
+## Outcome
+
+```
+✓ API_CONTRACTS.md updated (v1.2.0 → v1.3.0)
+✓ 1 new endpoint documented
+✓ 1 endpoint updated (non-breaking)
+✓ Test contracts generated (3 new tests)
+✓ All API tests passing (12/12)
+✓ No breaking changes — no migration guide needed
+→ Ready to merge
+```