OpenCaw

OpenCaw.Summary.mp4

OpenCaw is an open source framework library for AI-assisted development that standardizes instructions, skills, commands, and architecture guidance for tools such as Cursor, Codex, and Claude.

It provides a structured system that allows teams to:

• Standardize AI agent behavior across repositories
• Reuse architecture frameworks and coding standards
• Define reusable commands and skills
• Offload memory and learning fragments into project-local storage
• Maintain consistent enterprise-ready development workflows

OpenCaw is designed so it can be installed into an existing repository as a submodule or cloned tool directory (such as .codex, .cursor, or .claude) while keeping project-specific artifacts separate from the shared instruction system.

---

Table of Contents

• Install
• Examples
• Contributing
• Architecture Frameworks
• Roles
• Role-Skill Bindings
• Skills
• Commands
• Skills & Commands Guide
• Validation
• Task Management
• AI Memory System
• License

---

Install

Fork OpenCaw First (Required)

Before installing OpenCaw in your project, you must first fork the repository.

This ensures:

• you control updates
• you can modify roles, skills, or commands
• upstream updates can be merged safely
• any enterprise security policies are satisfied

Fork the repository

Visit:

https://github.com/TimothyMeadows/OpenCaw

Click Fork and create a fork under your GitHub account or organization.

Example fork location:

https://github.com/<your-org>/OpenCaw

After forking, use your fork URL in all installation commands instead of the upstream repository.

OpenCaw can be installed in an existing repository in two primary ways.

Option 1 — Git Submodule (Recommended)

Submodules allow the instruction system to be updated centrally while individual projects control the version they use.

Example installation as .codex or .cursor or .claude:

git submodule add https://github.com/<your-org>/OpenCaw .codex
git submodule update --init --recursive

or

git submodule add https://github.com/<your-org>/OpenCaw .cursor

or

git submodule add https://github.com/<your-org>/OpenCaw .claude

Update at anytime:

git submodule update --remote

---

Option 2 — Clone (Independent Copy)

If a repository needs a customized version of OpenCaw, it can be cloned instead.

git clone https://github.com/<your-org>/OpenCaw .codex

or

git clone https://github.com/<your-org>/OpenCaw .cursor

or

git clone https://github.com/<your-org>/OpenCaw .claude

This allows you to modify instructions without affecting the upstream repository.

Examples

OpenCaw should auto load in most sessions once the host bootstrap is present in root AGENTS.md. If needed, you can still force activation by saying:

Read AGENTS.md instructions

These are some examples in how to use OpenCaw after it's been installed, and activated.

use role security-engineer + sre and review this repository for vulnerabilities and recommend fixes

use role qa-engineer and generate full test coverage for the current feature including edge cases

use role devops-automator and create a CI/CD pipeline as a github action for gcp with build, test, and deploy stages for this repository

use role fullstack-engineer and build a calculator app with a simple UI, basic arithmetic operations, tests, task tracking, architecture generation if missing, and final verification

work on #123 and implement the fix with tests and verification evidence

What happens?

OpenCaw deterministically resolves your prompt into:

1. Roles activated -> sets perspective and priorities
2. Skills selected -> plans and reasons about the work
3. Tasks + issues created/updated -> .ai/tasks/TODO.md + .ai/tasks/<task>/TASK.md + .ai/tasks/OPEN_ISSUES.md
4. Architecture ensured -> generates ARCHITECTURE.md if missing
5. Commands executed -> builds, tests, scans, or deploys
6. Verification performed -> tests/logs prove correctness
7. Memory updated -> .ai/ captures reusable lessons

To be more specific it will:

1. activate the fullstack-engineer role
2. check whether ARCHITECTURE.md exists
3. if missing, ask which architecture templates apply
4. generate ARCHITECTURE.md
5. update .ai/tasks/TODO.md with an ordered checklist
6. create or import a task file such as:
   • .ai/tasks/create-calculator-app/TASK.md
7. create/link a matching GitHub issue, or import an existing one from a prompt like Work on #123, and add the URL to .ai/tasks/OPEN_ISSUES.md
8. apply appropriate skills such as:
   • create-task-file
   • manage-task-issues
   • generate-architecture
   • solution-build
   • test-dotnet
9. use appropriate commands based on the stack, such as:
   • ./commands/dotnet-restore.sh
   • ./commands/dotnet-build.sh
   • ./commands/dotnet-test.sh
   • ./commands/comment-issue-test-results.sh for QA evidence
10. implement the application
11. associate any PR with the task issue (Closes #<issue-number>)
12. run validation and verification before completion
13. post QA/Playwright verification evidence as an issue comment (results + screenshots/artifacts)
14. update memory files if durable lessons are discovered

This is the intended OpenCaw experience:

• The user gives one high-level prompt
• OpenCaw resolves the role
• OpenCaw selects the right skills
• OpenCaw uses the right commands
• OpenCaw creates task structure and verification flow
• OpenCaw completes the work in a governed, repeatable way

The detailed example below shows the same work broken down step by step for users who want to see the full workflow explicitly.

Contributing

Contributions to OpenCaw are welcome.

Typical workflow:

1. Fork the repository
2. Create a feature branch
3. Implement your improvement
4. Submit a pull request

Example:

git clone https://github.com/<your-org>/OpenCaw
cd OpenCaw
git checkout -b feature/add-architecture-framework

After making changes:

git add .
git commit -m "Add new architecture framework"
git push origin feature/add-architecture-framework

Then open a pull request against the main repository.

When contributing:

• Keep architecture frameworks enterprise-ready
• Maintain clear documentation
• Follow existing file structure and conventions

---

Architecture Frameworks

OpenCaw supports multi-architecture repositories.

Frameworks are located in:

.architecture/

These frameworks allow AI agents to generate a unified ARCHITECTURE.md file for a repository by combining multiple architecture standards.

By default, generation is read-reference based so ARCHITECTURE.md stays concise and contains directives such as Read \.//.architecture/DOTNET.md` instructions`. Use inline generation only when full embedded content is explicitly required.

Example supported frameworks include:

• DOTNET
• DOTNET_ASPIRE
• NODE
• MAUI
• EMBEDDED_FIRMWARE
• PYTHON
• NEXTJS
• SPA
• REACT
• ANGULAR
• VUE
• AZURE
• SIGNALR_WEBSOCKETS
• MSSQL
• MYSQL
• POSTGRESDB
• SQLITE
• COSMOSDB
• AZURE_STORAGE_TABLES
• DATABRICKS
• TERRAFORM
• KUBERNETES
• HELM
• MICROSERVICES
• EVENT_DRIVEN
• SOLIDITY
• GITHUB_ACTIONS
• AZURE_DEVOPS

Language/tool alignment guidance is documented in:

.architecture/LANGUAGE_SUPPORT.md

Agents will ask which architectures apply if ARCHITECTURE.md does not exist and generate it automatically.

---

Roles

OpenCaw includes a library of engineering roles in:

.roles/

Each role is stored as:

.roles/<domain>/<role-name>/ROLE.md

Current engineering catalog:

.roles/computer-science/<role-name>/ROLE.md

To browse available roles, categories, and aliases, see:

.roles/INDEX.md

Role activation

To activate a role, the user can request a matching role name or a common alias.

Role references may be:

• unqualified role name, for example backend-architect
• alias from .roles/INDEX.md, for example security
• domain-qualified role id, for example computer-science/backend-architect

Examples:

• use role backend-architect
• use role security
• act as sre

Resolution behavior:

• If an unqualified role name or alias maps to exactly one role across all domains, activate it directly.
• If an unqualified role name or alias maps to multiple roles across domains, prompt the user to choose a domain-qualified role before continuing.
• If both an exact role-name match and alias match exist, exact role-name match wins.
• If no matching role exists, continue with baseline behavior.

Deterministic helper command:

./commands/resolve-role.sh "<role-name|alias|domain/role-name>"

Multi-role composition

OpenCaw also supports combining roles in one session.

Examples:

• use role backend-architect + security-engineer
• use roles frontend-developer + qa-engineer

When multiple roles are requested:

• the first role acts as the primary perspective by default
• later roles add specialist constraints, review lenses, or guidance
• stricter or safer guidance should win when roles conflict, unless the user says otherwise

---

Role-Skill Bindings

OpenCaw includes default bindings between common engineering roles, reusable skills, and preferred commands.

See:

.roles/ROLE_SKILL_MAP.md
.roles/ROLE_SKILL_MAP.json

These mappings allow role casting to do more than change tone or perspective.

When a role is activated, OpenCaw should:

• prioritize the skills associated with that role
• prefer commands associated with that role
• apply shared skills such as planning, debugging, review, refactoring, and verification
• bias reasoning toward the role's domain expertise
• resolve bindings by checking <domain>/<role> first, then fallback to <role> for backward compatibility

Examples:

• backend-architect → architecture review, service boundaries, dependency audits
• frontend-developer → components, feature modules, rendering, accessibility
• fullstack-engineer → end-to-end feature delivery, API/UI integration, full-flow verification
• security-engineer → threat modeling, security audits, dependency vulnerability review
• sre → incident analysis, resilience design, performance review

Multi-role sessions should merge bindings in the same order as the requested roles.

---

Skills

Skills provide reusable instructions for AI agents to perform structured tasks.

Example skill locations:

skills/
skills/generate-architecture/
skills/create-task-file/
skills/test-dotnet/

Skills should:

• Define clear intent
• Provide deterministic instructions
• Avoid hidden behavior

---

Commands

Commands provide reusable CLI workflows for automation tasks.

Examples include:

commands/generate-architecture.sh
commands/create-task-file.sh
commands/dotnet-restore.sh
commands/dotnet-build.sh
commands/dotnet-test.sh
commands/security-scan.sh
commands/clean-context.sh

Commands should remain:

• deterministic
• platform-safe
• clearly documented

---

Validation

OpenCaw includes built-in validation commands for its role, skill, and command schemas.

Available commands:

commands/validate-roles.sh
commands/validate-skills.sh
commands/validate-commands.sh
commands/validate-opencaw.sh

Recommended usage:

./commands/validate-opencaw.sh

Or run individual checks:

./commands/validate-roles.sh
./commands/validate-skills.sh
./commands/validate-commands.sh

These validators check:

• .roles/SCHEMA.md compliance
• skills/SCHEMA.md compliance
• commands/SCHEMA.md compliance
• naming conventions
• required metadata and sections
• executable shell command requirements

---

Task Management

OpenCaw supports structured task tracking using the .ai/tasks directory.

.ai/tasks/
.ai/tasks/TODO.md
.ai/tasks/<task-name>/TASK.md
.ai/tasks/OPEN_ISSUES.md

Rules:

• TODO.md contains the ordered list of tasks
• Each task folder contains a detailed TASK.md
• Each substantial task is backed by one GitHub issue
• Existing GitHub issues can be imported directly with ./commands/import-task-from-issue.sh "<issue-ref>" where <issue-ref> can be #123, 123, or a full issue URL
• Track only open issue URLs (one per line) in OPEN_ISSUES.md
• Sync and remove closed issue URLs from .ai/tasks tracking
• Agents update progress as tasks are completed
• PRs for task-backed work should include issue linkage (for example Closes #123)
• QA/Playwright runs should post result comments to the linked issue, including screenshot/artifact references

---

AI Memory System

AI learning artifacts are stored outside the tool directory to prevent pollution of the shared instruction system.

Example:

.ai/
.ai/MEMORY.md
.ai/RULES.md
.ai/DEBUG.md

These files allow agents to:

• record lessons learned
• prevent repeated mistakes
• store debugging knowledge

---

License

OpenCaw is released under the MIT License.

See the LICENSE file for full details.

Skills & Commands Guide

OpenCaw separates thinking from execution using:

• Skills → reusable reasoning patterns (WHAT to do)
• Commands → deterministic scripts (HOW to do it)

---

Skills

Skills live in:

./skills/<skill-name>/SKILL.md

They are automatically used by the agent when relevant or when a role is active.

How to use skills

You can explicitly invoke a skill:

use skill create-task-file
use skill manage-task-issues
use skill clean-context

Or combine them:

use skill create-task-file + manage-task-issues + test-dotnet

Common Skills

Skill	Purpose
create-task-file	Create a task file and link a matching issue
manage-task-issues	Sync and prune open issue tracking
clean-context	Compact context after substantial work
solution-build	Build the .NET solution
test-dotnet	Run .NET tests for verification
install-database-cli-tools	Install or preview database CLI tooling setup
database-cli-query	Run database connect/query workflows by engine

Role-Driven Skills

When using roles:

use role backend-architect

Skills are automatically prioritized:

• task tracking
• verification workflows
• role-specific command selection

---

Commands

Commands live in:

./commands/*.sh

They are executable scripts used for repeatable workflows.

How to use commands

Run directly:

./commands/validate-opencaw.sh

Or invoke via agent:

run command validate-opencaw
run command dotnet-build

---

Common Commands

Command	Purpose
validate-opencaw.sh	Validate entire OpenCaw setup
dotnet-restore.sh	Restore .NET dependencies
dotnet-build.sh	Build .NET project
dotnet-test.sh	Run tests
create-task-file.sh	Create a task file and optionally link/create an issue
create-task-issue.sh	Create/link a GitHub issue for a task and track its URL
import-task-from-issue.sh	Import a task from an existing GitHub issue number/URL and link tracking files
sync-task-issues.sh	Remove closed issue URLs from active .ai/tasks tracking
link-pr-to-task-issue.sh	Add issue-closing linkage to PR body
comment-issue-test-results.sh	Post QA/Playwright results and screenshot references to issue
clean-context.sh	Compress context and refresh high-signal summaries
security-scan.sh	Run security checks
install-database-cli-tools.sh	Print or execute database CLI install commands
database-cli-query.sh	Execute engine-specific database query/connect commands

---

Skill + Command Workflow

Example:

use role code-migrator
use skill dependency-audit-dotnet

Then:

./commands/dotnet-build.sh
./commands/dotnet-test.sh

---

Best Practices

• Use skills first to plan and reason
• Use commands second to execute
• Combine roles + skills for precision
• Always verify with commands before completion

---

Mental Model

Layer	Responsibility
Role	Perspective
Skill	Thinking
Command	Execution

---