codex-genesis-harness 0.1.0 → 0.1.1

package/.codebase/API_CONTRACTS.md

@@ -0,0 +1,12 @@
+# API Contracts
+
+Contracts live under `contracts/`.
+
+Required convention:
+
+- `request.json`: accepted input shape.
+- `response.json`: successful output shape.
+- `schema.json`: validation schema.
+- `example.json`: realistic example.
+- `error.json`: failure response shape when applicable.
+

package/.codebase/ARCHITECTURE.md

@@ -0,0 +1,6 @@
+# Architecture
+
+This repository packages a Codex harness skill system. The npm package installs skills from `.codex/skills/`, command wrappers from `bin/`, and validation scripts from `scripts/`.
+
+Core boundary: skills define agent workflows; scripts validate and install them; repository memory under `.codebase/` compresses current knowledge for future sessions.
+

package/.codebase/CURRENT_STATE.md

@@ -0,0 +1,6 @@
+# Current State
+
+Current objective: evolve `codex-genesis-harness` into a reusable Genesis skill set for test-first, contract-first, memory-aware Codex workflows.
+
+Start every task by reading this file, `MODULE_INDEX.md`, and `TEST_MATRIX.md`, then inspect only relevant files.
+

package/.codebase/DEPENDENCY_GRAPH.md

@@ -0,0 +1,14 @@
+# Dependency Graph
+
+```mermaid
+flowchart TD
+  npm["npm package"] --> cli["bin/genesis-harness.js"]
+  npm --> skills[".codex/skills"]
+  cli --> verify["scripts/verify.sh"]
+  cli --> install["scripts/install.sh"]
+  verify --> memory[".codebase"]
+  verify --> contracts["contracts"]
+  verify --> fixtures["fixtures"]
+  verify --> tests["tests and playwright"]
+```
+

package/.codebase/DOMAIN_MODELS.md

@@ -0,0 +1,8 @@
+# Domain Models
+
+- Skill: a folder with `SKILL.md`, `agents/openai.yaml`, and optional templates, examples, checklists, scripts, references, or assets.
+- Contract: versioned input/output/error/schema examples for APIs, agents, events, and UI surfaces.
+- Fixture: reproducible input plus expected output and validation notes.
+- Memory file: compressed repository knowledge updated after meaningful changes.
+- Run log: observability record for autonomous modifications.
+

package/.codebase/EVOLUTION_PLAN.md

@@ -0,0 +1,35 @@
+# Evolution Plan
+
+## Current Weaknesses Identified
+
+- The repo started with a small skill set and limited harness-wide specialization.
+- Repository memory was absent, so future sessions had to rediscover structure.
+- Contracts, fixtures, Playwright templates, and observability templates were not first-class package artifacts.
+- Verification did not enforce memory, contracts, fixtures, or skill protocol consistency.
+- Installer scripts knew only the initial Genesis skills.
+
+## Target Architecture
+
+- Skills are modular under `.codex/skills/`.
+- Memory is compressed under `.codebase/` and `.codebase/context/`.
+- Contracts live under `contracts/`.
+- Fixtures live under `fixtures/`.
+- Harness tests live under `tests/` and `playwright/`.
+- Autonomous run evidence lives under `observability/`.
+
+## Implementation Sequence
+
+1. Add failing verification for required harness artifacts.
+2. Create memory, contracts, fixtures, tests, Playwright, and observability templates.
+3. Add modular skills with `SKILL.md`, `templates/`, `examples/`, and `checklists/`.
+4. Update installer and package metadata to include all artifacts.
+5. Update AGENTS and README as maps, not manuals.
+6. Run verify, evals, skill validation, CLI smoke tests, and package dry-run.
+
+## Next Hardening Pass
+
+- Add machine-readable schema validation for contract JSON.
+- Add snapshot tests for package tarball file lists.
+- Add a release checklist that blocks publish when ignored generated files are tracked.
+- Add forward-testing prompts for each skill against realistic downstream repositories.
+

package/.codebase/KNOWN_PROBLEMS.md

@@ -0,0 +1,6 @@
+# Known Problems
+
+- `.npm-cache/` was previously committed by mistake; it is now ignored but may still exist in history.
+- The current package provides templates and verification scaffolds, not application-specific generated tests.
+- Downstream projects must fill concrete endpoint, UI, provider, and persistence details.
+

package/.codebase/MODULE_INDEX.md

@@ -0,0 +1,13 @@
+# Module Index
+
+- `.codex/skills/`: packaged Codex skills.
+- `bin/genesis-harness.js`: npm CLI for install, verify, uninstall, and path output.
+- `scripts/verify.sh`: structural and smoke verification.
+- `scripts/run-evals.sh`: package-level regression checks.
+- `.codebase/`: compressed repository memory.
+- `contracts/`: API, agent, event, and UI contract templates.
+- `fixtures/`: reusable test and validation fixtures.
+- `tests/`: harness test architecture templates.
+- `playwright/`: UI smoke, e2e, and visual harness templates.
+- `observability/`: autonomous run and decision logging templates.
+

package/.codebase/PIPELINE_FLOW.md

@@ -0,0 +1,14 @@
+# Pipeline Flow
+
+```mermaid
+flowchart LR
+  state["Read .codebase state"] --> test["Create failing test"]
+  test --> fixture["Create fixture and expected output"]
+  fixture --> impl["Implement minimum change"]
+  impl --> verify["Run verification"]
+  verify --> contracts["Update contracts"]
+  contracts --> memory["Update .codebase memory"]
+  memory --> docs["Update docs"]
+  docs --> summary["Write change summary"]
+```
+

package/.codebase/TEST_MATRIX.md

@@ -0,0 +1,11 @@
+# Test Matrix
+
+Required checks:
+
+- `scripts/verify.sh`: repository harness structure, skill metadata, contracts, fixtures, and harness smoke test.
+- `scripts/run-evals.sh`: install/verify/uninstall regression checks.
+- `npm run pack:check`: package contents dry-run.
+- Skill validation: run `quick_validate.py` for changed skills when available.
+
+Feature rule: add or update fixtures and expected output before implementation.
+

package/.codebase/UI_ROUTES.md

@@ -0,0 +1,4 @@
+# UI Routes
+
+This package has no runtime UI routes. UI harness templates live under `playwright/` for downstream projects using Genesis skills.
+

package/.codebase/context/backend-summary.md

@@ -0,0 +1,4 @@
+# Backend Summary
+
+No backend service is implemented in this package. Backend guidance is represented by contracts, fixtures, and test templates for downstream repositories.
+

package/.codebase/context/frontend-summary.md

@@ -0,0 +1,4 @@
+# Frontend Summary
+
+No frontend app is implemented here. Frontend workflows are provided through `genesis-new-design`, `genesis-upgrade-design`, design-spec, and Playwright templates.
+

package/.codebase/context/pipeline-summary.md

@@ -0,0 +1,4 @@
+# Pipeline Summary
+
+The harness pipeline is test-first and contract-first: memory read, failing test, fixture, implementation, verification, contracts, memory, docs, summary.
+

package/.codebase/context/providers-summary.md

@@ -0,0 +1,4 @@
+# Providers Summary
+
+AI providers are represented by contracts and fixtures. Provider-specific code should be tested through mock providers, retry tests, invalid JSON recovery tests, and persistence checks.
+

package/.codebase/context/render-summary.md

@@ -0,0 +1,4 @@
+# Render Summary
+
+Render workflows are represented by fixtures under `fixtures/render/` and contracts for render agents. Downstream render implementations must validate input, output, and failure artifacts.
+

package/.codebase/context/tests-summary.md

@@ -0,0 +1,4 @@
+# Tests Summary
+
+Use `scripts/verify.sh`, `scripts/run-evals.sh`, skill validation, contract tests, integration tests, unit tests, and Playwright smoke/e2e/visual templates.
+

package/.codex/skills/ai-provider-skill/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: ai-provider-skill
+description: Define reliable AI provider harnesses with mock providers, schemas, retries, invalid JSON recovery, persistence tests, and provider contracts. Use for LLM, image, voice, subtitle, render, and pipeline provider work.
+---
+
+# AI Provider Skill
+
+## Purpose
+Make AI provider behavior deterministic under tests and recoverable under failures.
+
+## When to use
+Use before adding or changing AI providers, provider adapters, retry logic, schema parsing, or persistence.
+
+## When NOT to use
+Do not use for purely static documentation changes.
+
+## Inputs required
+Provider name, request shape, expected response, error modes, retry policy, and persistence target.
+
+## Outputs required
+Provider contract, mock provider fixture, schema validation, retry test, invalid JSON recovery test, and persistence test.
+
+## Required tests
+Mock success, provider error, retry, invalid JSON recovery, and persistence tests.
+
+## Required fixtures
+Create provider fixtures under `fixtures/agents`, `fixtures/images`, `fixtures/tts`, or related directories.
+
+## Required contract updates
+Update `contracts/agents/` or provider-specific contracts.
+
+## Required codebase map updates
+Update providers summary, pipeline flow, and test matrix.
+
+## Token saving rules
+Read provider summary and contract before provider code.
+
+## Acceptance criteria
+Provider output is schema-validated and failure recovery is tested.
+
+## Common mistakes
+Trusting raw model JSON, skipping retry tests, and using live provider calls in normal tests.
+
+## Recovery workflow
+If provider output is invalid, capture fixture, add parser recovery test, then patch parser or contract.
+

package/.codex/skills/ai-provider-skill/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "AI Provider Skill"
+  short_description: "Harden AI provider contracts and tests"
+  default_prompt: "Use $ai-provider-skill to define provider contracts, fixtures, and recovery tests."
+policy:
+  allow_implicit_invocation: true
+

package/.codex/skills/ai-provider-skill/checklists/checklist.md

@@ -0,0 +1,9 @@
+# AI Provider Checklist
+
+- [ ] Mock provider.
+- [ ] Fixture input.
+- [ ] Expected JSON output.
+- [ ] Schema validation.
+- [ ] Retry and invalid JSON tests.
+- [ ] Persistence test.
+

package/.codex/skills/ai-provider-skill/examples/example.md

@@ -0,0 +1,4 @@
+# Example
+
+Mock image generation provider output, validate schema, retry transient failure, and persist artifact metadata.
+

package/.codex/skills/ai-provider-skill/templates/provider-contract-template.md

@@ -0,0 +1,9 @@
+# Provider Contract Template
+
+## Request
+## Response
+## Validation
+## Retry Policy
+## Persistence
+## Failure Modes
+

package/.codex/skills/api-contract-skill/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: api-contract-skill
+description: Create and verify API contracts before endpoint implementation. Use for API routes, service interfaces, validation rules, error shapes, snapshots, and endpoint tests.
+---
+
+# API Contract Skill
+
+## Purpose
+Ensure API behavior is defined by contracts, fixtures, and tests before code.
+
+## When to use
+Use before adding or changing endpoints, request schemas, response schemas, auth, errors, or persistence behavior.
+
+## When NOT to use
+Do not use for UI-only changes that do not touch API behavior.
+
+## Inputs required
+Endpoint path, method, auth, request body, success response, error cases, and persistence effects.
+
+## Outputs required
+Contract folder, fixture, success test, validation error test, not found test, and schema validation.
+
+## Required tests
+Create contract, integration, and unit tests as appropriate.
+
+## Required fixtures
+Create API fixtures for success and failure cases.
+
+## Required contract updates
+Update `contracts/api/` with request, response, schema, example, and error JSON.
+
+## Required codebase map updates
+Update `.codebase/API_CONTRACTS.md` and `TEST_MATRIX.md`.
+
+## Token saving rules
+Load endpoint contract before source files. Open only route and validator modules named by the contract.
+
+## Acceptance criteria
+Contract tests fail before implementation and pass after the minimum endpoint change.
+
+## Common mistakes
+Implementing validation before schema, changing error shape without a contract, and testing only success.
+
+## Recovery workflow
+If endpoint behavior is ambiguous, freeze implementation and create the missing contract first.
+

package/.codex/skills/api-contract-skill/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "API Contract Skill"
+  short_description: "Define API contracts before endpoints"
+  default_prompt: "Use $api-contract-skill to create endpoint contracts and tests before implementation."
+policy:
+  allow_implicit_invocation: true
+

package/.codex/skills/api-contract-skill/checklists/checklist.md

@@ -0,0 +1,8 @@
+# API Contract Checklist
+
+- [ ] Request schema exists.
+- [ ] Response schema exists.
+- [ ] Error schema exists.
+- [ ] Fixture exists.
+- [ ] Contract test fails first.
+

package/.codex/skills/api-contract-skill/examples/example.md

@@ -0,0 +1,4 @@
+# Example
+
+Before adding `POST /api/jobs`, create request, response, schema, example, error, and contract tests.
+

package/.codex/skills/api-contract-skill/templates/api-contract-template.md

@@ -0,0 +1,4 @@
+# API Contract Template
+
+Use `contracts/api/endpoint-template/` and replace path, method, schema, examples, and errors.
+

package/.codex/skills/architecture-skill/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: architecture-skill
+description: Guide Codex through architecture analysis, boundary decisions, dependency direction, module ownership, and architecture documentation. Use before structural changes, new subsystems, cross-module work, or when architecture memory must be updated.
+---
+
+# Architecture Skill
+
+## Purpose
+Maintain architecture as a verifiable contract between modules, tests, docs, and repository memory.
+
+## When to use
+Use before subsystem changes, dependency changes, major refactors, new services, or architecture decisions.
+
+## When NOT to use
+Do not use for copy-only edits or isolated single-file fixes with no boundary impact.
+
+## Inputs required
+Read `.codebase/CURRENT_STATE.md`, `.codebase/MODULE_INDEX.md`, `.codebase/TEST_MATRIX.md`, then inspect relevant architecture files only.
+
+## Outputs required
+Architecture decision, impacted modules, dependency changes, diagrams when useful, and `.codebase/ARCHITECTURE.md` updates.
+
+## Required tests
+Add or update tests proving module boundaries and dependency behavior.
+
+## Required fixtures
+Create fixtures for new boundary inputs, outputs, and failure modes.
+
+## Required contract updates
+Update contracts when public behavior or module interfaces change.
+
+## Required codebase map updates
+Update `ARCHITECTURE.md`, `MODULE_INDEX.md`, and `DEPENDENCY_GRAPH.md`.
+
+## Token saving rules
+Read maps first, then only modules named by the maps. Prefer diagrams and checklists over repeated prose.
+
+## Acceptance criteria
+Boundaries are explicit, tests pass, contracts match implementation, and memory is current.
+
+## Common mistakes
+Changing dependency direction silently, documenting intent without tests, and scanning the whole repo before reading memory.
+
+## Recovery workflow
+If architecture drift is found, stop feature work, create a failing boundary test, update the contract, then repair the smallest module slice.
+

package/.codex/skills/architecture-skill/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Architecture Skill"
+  short_description: "Plan and verify architecture boundaries"
+  default_prompt: "Use $architecture-skill to evaluate architecture impact and update repository memory."
+policy:
+  allow_implicit_invocation: true
+

package/.codex/skills/architecture-skill/checklists/checklist.md

@@ -0,0 +1,8 @@
+# Architecture Checklist
+
+- [ ] Read current state, module index, and test matrix.
+- [ ] Identify boundary impacted.
+- [ ] Add failing boundary test.
+- [ ] Update contracts.
+- [ ] Update `.codebase` memory.
+

package/.codex/skills/architecture-skill/examples/example.md

@@ -0,0 +1,4 @@
+# Example
+
+Use before splitting a provider module into separate API and persistence boundaries.
+

package/.codex/skills/architecture-skill/templates/architecture-decision-template.md

@@ -0,0 +1,14 @@
+# Architecture Decision Template
+
+## Decision
+
+## Context
+
+## Constraints
+
+## Contracts Changed
+
+## Tests Added
+
+## Memory Updates
+

package/.codex/skills/codebase-map-skill/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: codebase-map-skill
+description: Maintain repository memory and compressed codebase maps for token-efficient Codex operation. Use when files move, modules change, contracts change, tests change, or repository summaries need updating.
+---
+
+# Codebase Map Skill
+
+## Purpose
+Keep `.codebase/` accurate so future agents read summaries before source.
+
+## When to use
+Use after meaningful code, contract, test, route, provider, pipeline, or architecture changes.
+
+## When NOT to use
+Do not use for changes that do not affect repository understanding.
+
+## Inputs required
+Changed files, verification results, contracts touched, and current `.codebase` files.
+
+## Outputs required
+Updated module index, current state, test matrix, dependency graph, and context summaries.
+
+## Required tests
+Run `scripts/verify.sh` after memory updates.
+
+## Required fixtures
+Update fixture index when fixtures change.
+
+## Required contract updates
+Reflect changed contracts in `.codebase/API_CONTRACTS.md`.
+
+## Required codebase map updates
+Update all impacted `.codebase` files.
+
+## Token saving rules
+Summaries must be short, link to source locations, and avoid duplicating full manuals.
+
+## Acceptance criteria
+Future agents can orient by reading `CURRENT_STATE.md`, `MODULE_INDEX.md`, and `TEST_MATRIX.md`.
+
+## Common mistakes
+Letting memory drift, overloading summaries with full docs, and forgetting test matrix changes.
+
+## Recovery workflow
+If memory conflicts with code, trust verified code, update memory, and add a known problem entry.
+

package/.codex/skills/codebase-map-skill/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Codebase Map Skill"
+  short_description: "Maintain compressed repository memory"
+  default_prompt: "Use $codebase-map-skill to update repository memory after this change."
+policy:
+  allow_implicit_invocation: true
+

package/.codex/skills/codebase-map-skill/checklists/checklist.md

@@ -0,0 +1,7 @@
+# Codebase Map Checklist
+
+- [ ] Current state updated.
+- [ ] Module index updated.
+- [ ] Test matrix updated.
+- [ ] Context summaries still concise.
+

package/.codex/skills/codebase-map-skill/examples/example.md

@@ -0,0 +1,4 @@
+# Example
+
+After adding a new contract test folder, update `TEST_MATRIX.md` and `MODULE_INDEX.md`.
+

package/.codex/skills/codebase-map-skill/templates/map-update-template.md

@@ -0,0 +1,8 @@
+# Codebase Map Update
+
+## Changed Files
+## Impacted Modules
+## Tests
+## Contracts
+## Memory Files Updated
+

package/.codex/skills/design-spec-skill/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: design-spec-skill
+description: Define UI design specs, route contracts, visual states, accessibility expectations, and UI/API synchronization before frontend implementation. Use for new screens, redesigns, visual QA, or UI contract updates.
+---
+
+# Design Spec Skill
+
+## Purpose
+Make UI behavior and visual expectations contract-first before implementation.
+
+## When to use
+Use before creating or changing screens, dashboards, forms, flows, or visual states.
+
+## When NOT to use
+Do not use for backend-only changes with no UI effect.
+
+## Inputs required
+UI route, audience, state list, API dependencies, fixtures, and visual references if available.
+
+## Outputs required
+UI contract, Playwright fixture, acceptance states, and visual regression expectations.
+
+## Required tests
+Create load, interaction, validation, API sync, and visual regression tests where applicable.
+
+## Required fixtures
+Create UI fixtures for default, loading, empty, error, and success states.
+
+## Required contract updates
+Update `contracts/ui/` for changed routes or states.
+
+## Required codebase map updates
+Update `.codebase/UI_ROUTES.md` and frontend summary.
+
+## Token saving rules
+Use state tables and route maps instead of long visual prose.
+
+## Acceptance criteria
+The UI can be implemented and tested without guessing states or API behavior.
+
+## Common mistakes
+Designing only the happy path, skipping empty/error states, and omitting API synchronization.
+
+## Recovery workflow
+If implementation diverges from spec, update the failing UI test first, then repair contract or UI.
+

package/.codex/skills/design-spec-skill/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Design Spec Skill"
+  short_description: "Create UI design and route contracts"
+  default_prompt: "Use $design-spec-skill to define UI states and tests before implementation."
+policy:
+  allow_implicit_invocation: true
+

package/.codex/skills/design-spec-skill/checklists/checklist.md

@@ -0,0 +1,7 @@
+# Design Spec Checklist
+
+- [ ] UI contract exists.
+- [ ] Fixture exists.
+- [ ] Playwright tests listed.
+- [ ] API sync asserted.
+

package/.codex/skills/design-spec-skill/examples/example.md

@@ -0,0 +1,4 @@
+# Example
+
+Define dashboard loading, empty, error, success, filter, and keyboard focus states before changing components.
+

package/.codex/skills/design-spec-skill/templates/design-spec-template.md

@@ -0,0 +1,9 @@
+# Design Spec Template
+
+## Route
+## Audience
+## States
+## API Dependencies
+## Accessibility
+## Visual Checks
+

package/.codex/skills/docs-skill/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: docs-skill
+description: Keep Codex harness docs synchronized with skills, contracts, tests, memory, and release behavior. Use after any workflow, public interface, install, verification, or package behavior change.
+---
+
+# Docs Skill
+
+## Purpose
+Keep docs short, accurate, and linked to source-of-truth artifacts.
+
+## When to use
+Use after changing skills, CLI behavior, contracts, fixtures, tests, repository memory, or publish flow.
+
+## When NOT to use
+Do not use to duplicate full architecture manuals in `AGENTS.md`.
+
+## Inputs required
+Changed files, public behavior, verification results, and affected users.
+
+## Outputs required
+Updated README, AGENTS map, codebase memory, changelog-style summary, and changed docs list.
+
+## Required tests
+Run docs-related verification and package dry-run when docs affect packaging or install instructions.
+
+## Required fixtures
+Update templates/examples when docs describe reusable workflows.
+
+## Required contract updates
+Update contracts when docs describe new interface behavior.
+
+## Required codebase map updates
+Update `.codebase/CURRENT_STATE.md`, `MODULE_INDEX.md`, or summaries as needed.
+
+## Token saving rules
+Keep docs concise. Link to templates and contracts instead of repeating them.
+
+## Acceptance criteria
+Docs match behavior and do not duplicate large internal manuals.
+
+## Common mistakes
+Letting AGENTS.md grow too large, documenting unverified behavior, and missing install docs.
+
+## Recovery workflow
+If docs drift, add verify assertions or checklist items that catch the drift next time.
+

package/.codex/skills/docs-skill/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Docs Skill"
+  short_description: "Synchronize harness documentation"
+  default_prompt: "Use $docs-skill to update concise docs and repository memory after changes."
+policy:
+  allow_implicit_invocation: true
+