Metadata-Version: 2.3
Name: augint-opencodex
Version: 0.0.0
Summary: Render local Codex and OpenCode repo config from .ai-codex.json
Author: Augmenting Integrations
Requires-Dist: click>=8.1.0
Requires-Dist: pydantic>=2.11.0
Requires-Python: >=3.13
Description-Content-Type: text/markdown

# 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 development:

```bash
uv sync --group dev
```

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

```bash
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.

```json
{
  "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`](schemas/ai-codex.schema.json).

## Commands

Render files into the current repository:

```bash
uv run ai-codex sync
```

Preview pending changes without writing:

```bash
uv run ai-codex sync --dry-run
```

Fail if the repo is out of sync:

```bash
uv run ai-codex sync --check
```

Inspect the current repo state:

```bash
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

```bash
make install
make test
make format
make typecheck
make build
```
