timothymeadows/opencaw

Purpose and Operating Model

OpenCaw is a reusable, mountable baseline for AI-assisted repository work. It turns natural-language requests into governed planning, implementation, verification, memory, task tracking, and PR workflows. It is intended to be mounted in a host repository as .codex, .cursor, or .claude; this repository itself contains the shared baseline rather than an application runtime.

Primary entry points:

• AGENTS.md — agent startup, safety, planning, task, memory, and delivery policy.

• README.md — user-facing workflow and installation model.

• commands/resolve-opencaw-paths.sh — resolves host-project and mounted-baseline boundaries.

Repository Layering and Context

The central architectural boundary separates reusable OpenCaw capabilities from host-specific state. Shared roles, skills, templates, and commands remain in the mounted baseline; the host repository owns durable project context under .ai/.

Key paths:

• .ai/SYSTEM_MEMORY.md

• .ai/MEMORY.md

• .ai/REPO_MAP.md

Session control is memory-first: resolve project root, ensure the host .ai scaffold exists, load protected memory and contracts, query relevant tagged context, then plan with the narrowest safe scope. The resolver fails closed on ambiguous repository boundaries.

Conversational Planning and Delivery Modes

Natural-language interaction is the principal interface; roles, skills, and commands are optional precision controls. Work proceeds through an optional explicit discovery stage, then one delivery mode:

• Brainstorm: persistent, research-backed idea discovery; blocks delivery creation.

• Task: default single assignment; stops at human PR-readiness approval.

• Goal: explicit ordered multi-task flow; validated task PRs can be opened automatically, never merged automatically.

• Gauntlet: explicit adversarial build/critic workflow with progress PRs, human-controlled merges, integration review, and final promotion gate.

Core workflow implementations:

• commands/brainstorm-mode.sh

• commands/create-task-file.sh

• commands/create-goal-file.sh

• commands/create-gauntlet-file.sh

Capability Catalog: Roles, Skills, and Contracts

Roles provide specialist perspectives, skills provide reusable workflows, and architecture/style contracts constrain work to the host’s chosen technology and production model.

Key paths:

• .roles/ROLE_SKILL_MAP.json

• skills/INDEX.md

• .architecture/INDEX.md

• .styles/INDEX.md

Role-to-skill bindings are canonicalized in JSON. Skills include agent-facing metadata under their own directories and cover planning, QA, browser automation, .NET, security, database work, generative media, games, and Blender production. Architecture and style templates are selected into concise host-level ARCHITECTURE.md and STYLE.md contracts.

Deterministic Command Layer

commands/ is the executable control plane. Shell scripts perform deterministic state changes and validations; common libraries are centralized in commands/lib/.

Important paths:

• commands/validate-opencaw.sh

• commands/create-host-ai-scaffold.sh

• commands/pr-readiness-check.sh

• commands/lib/platform-common.sh

Commands are designed to be reviewable, platform-safe, and non-self-installing unless installation is explicitly requested. They control scaffolding, task/issue lifecycle, memory, validation, media pipelines, browser evidence, and PR evidence.

Verification, Evidence, and External Boundaries

Completion requires evidence proportional to risk: targeted and broader tests, logs, browser artifacts, or rendered outputs. OpenCaw provides validators and templates but host repositories retain ownership of actual application tests, credentials, generated runtime artifacts, and deployment infrastructure.

Relevant paths:

• assets/playwright/playwright.config.template.ts

• assets/playwright-cli/references/running-code.md

• commands/playwright-test.sh

• commands/security-scan.sh

Material runtimes include Bash (primary command runtime), PowerShell for Windows bootstrap, Node.js/CJS helpers, Python for read-only Blender inspection, .NET command wrappers, Playwright, and Blender 4.5 LTS workflows. GitHub is the key external service for issues, PRs, live PR verification, and human-controlled merges; optional media pipelines integrate cloud providers or local loopback ComfyUI, with explicit selection and no silent fallback.

Art, Media, and 3D Production Boundary

Visual direction is distinct from production method. A host style contract selects one primary pipeline: cloud generation, local ComfyUI, CSS/vector, authored Three.js models, or Blender scenes. Generated media is staged and requires provenance, validation, and human review before promotion.

Key paths:

• .styles/.pipelines/INDEX.md

• .styles/.pipelines/local/toolchain.json

• .styles/.pipelines/code/code-model-manifest.schema.json

• .styles/.pipelines/blender/PIPELINE.md

Blender authoring requires compatible live tooling; CLI inspection is intentionally read-only. Cloud/local tools, models, providers, and paid actions are never installed or invoked implicitly.