augint-opencodex 0.2.0

Render local Codex and OpenCode repo config from .ai-codex.json

augint-opencodex

augint-opencodex is a Python tool that renders local Codex and OpenCode project configuration from a single tracked manifest, .ai-codex.json.

The first working slice is implemented here. It ships a real ai-codex CLI with:

• ai-codex sync to read .ai-codex.json and render .ai-opencodex.md, .codex/config.toml, opencode.json, and shared skills
• ai-codex doctor to inspect manifest resolution, generated files, local ignore setup, and staged generated artifacts
• a first-pass profile model with augint and gov
• local-only ignore handling through .git/info/exclude

Installation

For local dev:

uv sync --group dev

Once the package is published, the intended install flows are:

uvx --from augint-opencodex ai-codex sync
uv tool install augint-opencodex
ai-codex sync

Manifest

This tool expects a tracked .ai-codex.json file in the target repository. If it is missing when you run ai-codex sync, the command will prompt for a profile and create a minimal manifest before rendering. Pass --profile augint or --profile gov to skip the prompt (useful for scripts). --check still fails when the manifest is missing so CI does not silently initialize repos.

{
  "version": 1,
  "profile": "augint",
  "references": ["./ai-lls-lib"],
  "blocked_paths": [
    "**/secrets/**",
    "**/*.pem",
    "**/terraform.tfstate*"
  ],
  "content_policy": {
    "no_emojis": true,
    "no_ai_mentions": true
  },
  "shell_guardrails": {
    "ask": ["aws *", "terraform *", "kubectl *", "git push *"],
    "deny": ["aws iam create*", "aws iam put*"]
  },
  "patterns": {
    "org_python_library": true
  },
  "opencode": {
    "enabled": true
  }
}

The current schema lives in schemas/ai-codex.schema.json.

Commands

Render files into the current repository:

uv run ai-codex sync

Preview pending changes without writing:

uv run ai-codex sync --dry-run

Fail if the repo is out of sync:

uv run ai-codex sync --check

Inspect the current repo state:

uv run ai-codex doctor

Generated Files

The first slice writes:

• .ai-opencodex.md
• .codex/config.toml
• opencode.json
• .agents/skills/README.md
• .agents/skills/org-python-tooling/SKILL.md when patterns.org_python_library is enabled

Generated outputs are added to .git/info/exclude by default so target repositories do not need to commit them.

Dogfooding This Repo

This repository is set up to dogfood the generated instructions flow without a root AGENTS.md.

1. Keep .ai-codex.json tracked in the repo root.
2. Run uv run ai-codex sync to generate .ai-opencodex.md, .codex/config.toml, and the other local-only artifacts.
3. Start Codex with CODEX_HOME=$(pwd)/.codex codex so Codex uses the generated .codex/config.toml as its home config and discovers .ai-opencodex.md via project_doc_fallback_filenames.

Avoid creating a root AGENTS.md here. Codex checks AGENTS.md before fallback filenames in the same directory, so a root AGENTS.md would shadow .ai-opencodex.md and split Codex from the generated OpenCode instructions.

Organizational Python Standard

This project uses ai-lls-lib/ in the planning repo as the concrete reference for the organization-wide Python package and tooling standard:

• uv-first packaging and development workflow
• src/ layout and console scripts from [project.scripts]
• ruff, mypy, pytest, and pre-commit
• security and compliance checks in CI
• Conventional Commit and semantic-release-compatible versioning
• a stable Makefile task surface

Development

make install
make test
make format
make typecheck
make build