myace: Instructions file for Codex

MyACE — AI Agent Maintenance Guidelines

This document defines the rules and conventions for AI coding agents (Claude Code, OpenCode, Codex, etc.) maintaining the MyACE codebase. It is the single source of truth for agent-facing rules and gotchas — CLAUDE.md imports this file (via Claude Code's @AGENTS.md memory-import syntax) and adds only genuinely Claude-Code-specific notes on top, so don't duplicate content there.

What this is

MyACE ("My Agentic Coding Environment") makes AI agent configurations (rules, skills, agent definitions, workflows, model configs) portable across frameworks (OpenCode, Claude Code, Cursor, and others). It stores everything as a Canonical Intermediate Representation (IR) — Markdown with YAML frontmatter — and translates that IR into target-framework-specific files via adapters. See docs/architecture.md for the full picture.

Three components:

• backend/ — FastAPI + SQLModel API (Postgres in prod, SQLite for tests) that stores collections/artifacts/profiles and compiles profiles into target files.
• frontend/ — React + Vite + TailwindCSS SPA (served by nginx in prod, proxies /api/* to the backend).
• cli/ — Python Typer CLI (myace) that pulls compiled profiles from the server and can scan local config directories to import them.

Commands

Backend (from backend/)

pip install -e ".[dev]"          # install with dev deps
pytest                           # run all tests
pytest tests/test_adapters.py    # run one test file
pytest tests/test_adapters.py::test_name -v   # run a single test
ruff check .                     # lint
mypy app                         # type check (strict mode)
alembic revision --autogenerate -m "description"   # new migration
alembic upgrade head              # apply migrations

Tests use SQLite (aiosqlite) via tests/conftest.py, not Postgres — no running DB needed to run the suite. The db_session fixture spins up a fresh in-memory SQLite engine per test and overrides the get_session FastAPI dependency to point at it (app.dependency_overrides[get_session]); any test that exercises an authenticated route should depend on async_client (which itself depends on db_session), not construct its own client. Requires greenlet installed (a runtime dependency of SQLAlchemy's async engine, listed explicitly in pyproject.toml since it isn't pulled in automatically by sqlmodel/asyncpg).