augint-opencodex 0.0.0__tar.gz

augint_opencodex-0.0.0/PKG-INFO

@@ -0,0 +1,149 @@
+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
+```

augint_opencodex-0.0.0/README.md

@@ -0,0 +1,139 @@
+# 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
+```

augint_opencodex-0.0.0/pyproject.toml

@@ -0,0 +1,110 @@
+[project]
+name = "augint-opencodex"
+version = "0.0.0"
+description = "Render local Codex and OpenCode repo config from .ai-codex.json"
+authors = [{ name = "Augmenting Integrations" }]
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "click>=8.1.0",
+    "pydantic>=2.11.0",
+]
+
+[project.scripts]
+ai-codex = "augint_opencodex.cli.__main__:main"
+ai-opencodex = "augint_opencodex.cli.__main__:main"
+ai-opencode = "augint_opencodex.cli.__main__:main"
+
+[build-system]
+requires = ["uv_build>=0.9"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "B", "C4", "UP", "DTZ"]
+ignore = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["augint_opencodex"]
+
+[tool.mypy]
+python_version = "3.13"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+
+[[tool.mypy.overrides]]
+module = "augint_opencodex.cli.*"
+disallow_untyped_defs = false
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = "-ra -q --strict-markers"
+
+[tool.coverage.run]
+source = ["src"]
+omit = ["*/tests/*", "*/test_*.py"]
+
+[tool.semantic_release]
+assets = ["uv.lock"]
+commit_message = "chore(release): augint-opencodex {version}\n\nAutomatically generated by python-semantic-release [skip ci]"
+commit_parser = "angular"
+logging_use_named_masks = false
+major_on_zero = false
+allow_zero_version = true
+no_git_verify = false
+tag_format = "augint-opencodex-v{version}"
+version_toml = ["pyproject.toml:project.version"]
+version_variables = ["src/augint_opencodex/__init__.py:__version__"]
+build_command = "uv lock && uv build"
+
+[tool.semantic_release.branches.main]
+match = "main"
+prerelease = false
+
+[tool.semantic_release.changelog]
+mode = "update"
+changelog_file = "CHANGELOG.md"
+exclude_commit_patterns = [
+    '''chore(?:\([^)]*?\))?: .+''',
+    '''ci(?:\([^)]*?\))?: .+''',
+    '''refactor(?:\([^)]*?\))?: .+''',
+    '''style(?:\([^)]*?\))?: .+''',
+    '''test(?:\([^)]*?\))?: .+''',
+    '''build\((?!deps\): .+)''',
+    '''Initial [Cc]ommit.*''',
+]
+
+[tool.semantic_release.remote]
+name = "origin"
+type = "github"
+ignore_token_for_push = false
+insecure = false
+
+[tool.semantic_release.remote.token]
+env = "GH_TOKEN"
+
+[tool.semantic_release.publish]
+dist_glob_patterns = ["dist/*"]
+upload_to_vcs_release = true
+
+[dependency-groups]
+dev = [
+    "augint-github>=1.12.0",
+    "augint-shell>=0.72.0",
+    "augint-tools>=4.10.0",
+    "bandit>=1.8.0",
+    "mypy>=1.16.0",
+    "pip-audit>=2.9.0",
+    "pip-licenses>=5.0.0",
+    "pre-commit>=4.2.0",
+    "pytest>=8.3.0",
+    "pytest-cov>=6.0.0",
+    "pytest-html>=4.1.0",
+    "python-semantic-release>=10.4.0",
+    "ruff>=0.11.0",
+]

augint_opencodex-0.0.0/src/augint_opencodex/__init__.py

@@ -0,0 +1,3 @@
+"""augint-opencodex package."""
+
+__version__ = "0.0.0"

augint_opencodex-0.0.0/src/augint_opencodex/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI package for augint-opencodex."""

augint_opencodex-0.0.0/src/augint_opencodex/cli/__main__.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import sys
+
+import click
+
+from augint_opencodex import __version__
+from augint_opencodex.cli.commands import doctor, sync
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="ai-codex")
+def cli() -> None:
+    """Render local Codex and OpenCode repo config from `.ai-codex.json`."""
+
+
+cli.add_command(sync.sync_command)
+cli.add_command(doctor.doctor_command)
+
+
+def main() -> None:
+    """Run the `ai-codex` CLI."""
+
+    try:
+        cli()
+    except click.ClickException as exc:
+        exc.show()
+        sys.exit(exc.exit_code)
+    except Exception as exc:  # pragma: no cover - defensive CLI boundary
+        click.echo(f"Error: {exc}", err=True)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

augint_opencodex-0.0.0/src/augint_opencodex/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI commands."""

augint_opencodex-0.0.0/src/augint_opencodex/cli/commands/doctor.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from augint_opencodex.diagnostics import inspect_project
+
+
+@click.command(name="doctor")
+@click.option(
+    "--project-root",
+    type=click.Path(file_okay=False, path_type=Path),
+    default=Path("."),
+    show_default=True,
+    help="Repository root to inspect.",
+)
+@click.option(
+    "--manifest",
+    type=click.Path(dir_okay=False, path_type=Path),
+    help="Explicit manifest path. Defaults to PROJECT_ROOT/.ai-codex.json.",
+)
+def doctor_command(project_root: Path, manifest: Path | None) -> None:
+    """Inspect manifest resolution and generated file state."""
+
+    report = inspect_project(project_root, manifest_path=manifest)
+    click.echo(f"Project root: {report.policy.project_root}")
+    click.echo(f"Manifest: {report.policy.manifest_path}")
+    click.echo(f"Profile: {report.policy.profile_name}")
+
+    for expected_file in report.expected_files:
+        status = "ok" if expected_file not in report.missing_files else "missing"
+        click.echo(f"{status}: {expected_file.as_posix()}")
+
+    for stale_file in report.stale_files:
+        click.echo(f"stale: {stale_file.as_posix()}")
+
+    if not report.exclude_update.available:
+        click.echo("git exclude: unavailable")
+    elif report.exclude_update.needs_update:
+        click.echo("git exclude: missing ai-codex block")
+    else:
+        click.echo("git exclude: ok")
+
+    if report.root_agents_present:
+        click.echo(
+            "warning: root AGENTS.md is present and will shadow .ai-opencodex.md for Codex discovery"
+        )
+
+    if report.staged_generated_files:
+        for staged_file in report.staged_generated_files:
+            click.echo(f"warning: staged generated file {staged_file.as_posix()}")
+    else:
+        click.echo("staged generated files: none")
+
+    if report.missing_files or report.stale_files:
+        click.echo("Run `ai-codex sync` to reconcile missing or stale generated files.")

augint_opencodex-0.0.0/src/augint_opencodex/cli/commands/sync.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+import click
+
+from augint_opencodex.sync_engine import SyncReport, sync_project
+
+
+@click.command(name="sync")
+@click.option(
+    "--project-root",
+    type=click.Path(file_okay=False, path_type=Path),
+    default=Path("."),
+    show_default=True,
+    help="Repository root to sync.",
+)
+@click.option(
+    "--manifest",
+    type=click.Path(dir_okay=False, path_type=Path),
+    help="Explicit manifest path. Defaults to PROJECT_ROOT/.ai-codex.json.",
+)
+@click.option("--dry-run", is_flag=True, help="Preview changes without writing files.")
+@click.option("--check", is_flag=True, help="Exit non-zero when generated files are out of sync.")
+def sync_command(
+    project_root: Path,
+    manifest: Path | None,
+    dry_run: bool,
+    check: bool,
+) -> None:
+    """Render project-local Codex and OpenCode files."""
+
+    if dry_run and check:
+        raise click.ClickException("`--dry-run` and `--check` cannot be used together.")
+
+    mode: Literal["write", "dry-run", "check"] = (
+        "check" if check else "dry-run" if dry_run else "write"
+    )
+    report = sync_project(project_root, manifest_path=manifest, mode=mode)
+    _print_report(report)
+
+    if check and report.needs_changes:
+        raise click.ClickException("Generated files are out of sync. Run `ai-codex sync`.")
+
+
+def _print_report(report: SyncReport) -> None:
+    root = report.policy.project_root
+    click.echo(f"Project root: {root}")
+    click.echo(f"Manifest: {report.policy.manifest_path}")
+    click.echo(f"Profile: {report.policy.profile_name}")
+
+    if report.changed_files:
+        verb = {
+            "write": "wrote",
+            "dry-run": "would write",
+            "check": "needs update",
+        }[report.mode]
+        for path in report.changed_files:
+            click.echo(f"{verb}: {_display_path(path)}")
+    else:
+        click.echo("Generated files are already in sync.")
+
+    if report.stale_files:
+        verb = {
+            "write": "removed",
+            "dry-run": "would remove",
+            "check": "needs removal",
+        }[report.mode]
+        for path in report.stale_files:
+            click.echo(f"{verb}: {_display_path(path)}")
+
+    if report.unchanged_files:
+        click.echo(f"unchanged: {len(report.unchanged_files)} file(s)")
+
+    exclude_update = report.exclude_update
+    if not exclude_update.available:
+        click.echo("git exclude: skipped (no .git/info directory found)")
+    elif exclude_update.updated:
+        click.echo(f"git exclude: updated {_display_path(exclude_update.path, root)}")
+    elif exclude_update.needs_update:
+        click.echo(f"git exclude: would update {_display_path(exclude_update.path, root)}")
+    else:
+        click.echo("git exclude: already current")
+
+
+def _display_path(path: Path | None, base: Path | None = None) -> str:
+    if path is None:
+        return "<missing>"
+    if base is None:
+        return path.as_posix()
+    try:
+        return path.relative_to(base).as_posix()
+    except ValueError:
+        return path.as_posix()

augint_opencodex-0.0.0/src/augint_opencodex/diagnostics.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from augint_opencodex.ignore import ExcludeUpdate, ensure_git_exclude
+from augint_opencodex.manifest import load_manifest
+from augint_opencodex.profiles import ResolvedPolicy, resolve_policy
+from augint_opencodex.renderer import managed_file_paths, render_project
+
+
+@dataclass(frozen=True)
+class DoctorReport:
+    """Diagnostics for a target repository."""
+
+    policy: ResolvedPolicy
+    expected_files: tuple[Path, ...]
+    missing_files: tuple[Path, ...]
+    stale_files: tuple[Path, ...]
+    exclude_update: ExcludeUpdate
+    staged_generated_files: tuple[Path, ...]
+    root_agents_present: bool
+
+
+def inspect_project(project_root: Path, manifest_path: Path | None = None) -> DoctorReport:
+    """Inspect the current project and report sync-related state."""
+
+    resolved_root = project_root.resolve()
+    resolved_manifest_path = _resolve_manifest_path(resolved_root, manifest_path)
+    manifest = load_manifest(resolved_manifest_path)
+    policy = resolve_policy(manifest, resolved_root, resolved_manifest_path)
+    rendered_files = render_project(policy)
+    expected_files = tuple(rendered_file.path for rendered_file in rendered_files)
+    missing_files = tuple(
+        rendered_file.path
+        for rendered_file in rendered_files
+        if not (resolved_root / rendered_file.path).exists()
+    )
+    stale_files = tuple(
+        managed_path
+        for managed_path in managed_file_paths()
+        if managed_path not in expected_files and (resolved_root / managed_path).exists()
+    )
+    exclude_update = ensure_git_exclude(resolved_root, write=False)
+    staged_generated_files = _find_staged_generated_files(resolved_root, managed_file_paths())
+    root_agents_present = (resolved_root / "AGENTS.md").exists()
+
+    return DoctorReport(
+        policy=policy,
+        expected_files=expected_files,
+        missing_files=missing_files,
+        stale_files=stale_files,
+        exclude_update=exclude_update,
+        staged_generated_files=staged_generated_files,
+        root_agents_present=root_agents_present,
+    )
+
+
+def _resolve_manifest_path(project_root: Path, manifest_path: Path | None) -> Path:
+    if manifest_path is not None:
+        return manifest_path.resolve()
+    return (project_root / ".ai-codex.json").resolve()
+
+
+def _find_staged_generated_files(
+    project_root: Path, expected_files: tuple[Path, ...]
+) -> tuple[Path, ...]:
+    if not (project_root / ".git").exists():
+        return ()
+
+    command = [
+        "git",
+        "-C",
+        str(project_root),
+        "diff",
+        "--cached",
+        "--name-only",
+        "--",
+        *(path.as_posix() for path in expected_files),
+    ]
+    result = subprocess.run(
+        command,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode not in (0, 1):
+        return ()
+
+    staged_files = [line.strip() for line in result.stdout.splitlines() if line.strip()]
+    return tuple(Path(staged_file) for staged_file in staged_files)

augint_opencodex-0.0.0/src/augint_opencodex/ignore.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+GENERATED_IGNORE_PATTERNS = (
+    "/.ai-opencodex.md",
+    "/.ai-codex.md",
+    "/.codex/",
+    "/opencode.json",
+    "/.opencode/",
+    "/.agents/skills/",
+)
+BLOCK_START = "# BEGIN ai-codex generated"
+BLOCK_END = "# END ai-codex generated"
+
+
+@dataclass(frozen=True)
+class ExcludeUpdate:
+    """The state of `.git/info/exclude` for generated files."""
+
+    path: Path | None
+    available: bool
+    needs_update: bool
+    updated: bool
+
+
+def ensure_git_exclude(project_root: Path, *, write: bool) -> ExcludeUpdate:
+    """Add or refresh the generated ignore block in `.git/info/exclude`."""
+
+    exclude_path = project_root / ".git" / "info" / "exclude"
+    if not exclude_path.parent.exists():
+        return ExcludeUpdate(
+            path=exclude_path,
+            available=False,
+            needs_update=False,
+            updated=False,
+        )
+
+    existing = exclude_path.read_text(encoding="utf-8") if exclude_path.exists() else ""
+    desired = _merge_block(existing)
+    needs_update = desired != existing
+
+    if write and needs_update:
+        exclude_path.parent.mkdir(parents=True, exist_ok=True)
+        exclude_path.write_text(desired, encoding="utf-8")
+
+    return ExcludeUpdate(
+        path=exclude_path,
+        available=True,
+        needs_update=needs_update,
+        updated=write and needs_update,
+    )
+
+
+def _merge_block(existing: str) -> str:
+    generated_block = "\n".join(
+        (
+            BLOCK_START,
+            *GENERATED_IGNORE_PATTERNS,
+            BLOCK_END,
+        )
+    )
+
+    if BLOCK_START in existing and BLOCK_END in existing:
+        start = existing.index(BLOCK_START)
+        end = existing.index(BLOCK_END, start) + len(BLOCK_END)
+        updated = existing[:start].rstrip("\n")
+        suffix = existing[end:].lstrip("\n")
+        pieces = [part for part in (updated, generated_block, suffix) if part]
+        return "\n\n".join(pieces) + "\n"
+
+    stripped_existing = existing.strip("\n")
+    pieces = [part for part in (stripped_existing, generated_block) if part]
+    return "\n\n".join(pieces) + "\n"

augint_opencodex-0.0.0/src/augint_opencodex/manifest.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+
+class ManifestError(ValueError):
+    """Raised when `.ai-codex.json` cannot be loaded or validated."""
+
+
+class ContentPolicy(BaseModel):
+    """Output-style constraints applied by the generated profile."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    no_emojis: bool = True
+    no_ai_mentions: bool = True
+
+
+class ShellGuardrails(BaseModel):
+    """Shell command patterns that should prompt or be denied."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    ask: list[str] = Field(default_factory=list)
+    deny: list[str] = Field(default_factory=list)
+
+
+class PatternFlags(BaseModel):
+    """Named organizational patterns that can influence generated output."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    org_python_library: bool = False
+
+
+class OpenCodeConfig(BaseModel):
+    """Compatibility settings for OpenCode generation."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    enabled: bool = True
+
+
+class Manifest(BaseModel):
+    """Tracked repo manifest used to render local agent config."""
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    schema_uri: str | None = Field(default=None, alias="$schema")
+    version: Literal[1]
+    profile: Literal["augint", "gov"]
+    references: list[str] = Field(default_factory=list)
+    blocked_paths: list[str] = Field(default_factory=list)
+    content_policy: ContentPolicy = Field(default_factory=ContentPolicy)
+    shell_guardrails: ShellGuardrails = Field(default_factory=ShellGuardrails)
+    patterns: PatternFlags = Field(default_factory=PatternFlags)
+    opencode: OpenCodeConfig = Field(default_factory=OpenCodeConfig)
+
+
+def load_manifest(path: Path) -> Manifest:
+    """Load and validate a manifest file from disk."""
+
+    resolved_path = path.resolve()
+    if not resolved_path.exists():
+        raise ManifestError(f"Manifest not found: {resolved_path}")
+
+    try:
+        payload = json.loads(resolved_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ManifestError(f"Manifest is not valid JSON: {resolved_path}") from exc
+    except OSError as exc:
+        raise ManifestError(f"Unable to read manifest: {resolved_path}") from exc
+
+    try:
+        return Manifest.model_validate(payload)
+    except ValidationError as exc:
+        raise ManifestError(f"Manifest validation failed for {resolved_path}: {exc}") from exc

augint_opencodex-0.0.0/src/augint_opencodex/profiles.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from augint_opencodex.manifest import Manifest
+
+
+@dataclass(frozen=True)
+class ProfileDefinition:
+    """Resolved defaults for a named profile before manifest overrides."""
+
+    name: str
+    summary: str
+    instruction_bullets: tuple[str, ...]
+    blocked_paths: tuple[str, ...]
+    ask_patterns: tuple[str, ...]
+    deny_patterns: tuple[str, ...]
+    approval_policy: str = "on-request"
+    sandbox_mode: str = "workspace-write"
+    web_search: str = "live"
+
+
+@dataclass(frozen=True)
+class ResolvedPolicy:
+    """Effective policy after layering baseline, profile, and manifest settings."""
+
+    project_root: Path
+    manifest_path: Path
+    profile_name: str
+    profile_summary: str
+    references: tuple[str, ...]
+    blocked_paths: tuple[str, ...]
+    ask_patterns: tuple[str, ...]
+    deny_patterns: tuple[str, ...]
+    no_emojis: bool
+    no_ai_mentions: bool
+    org_python_library: bool
+    opencode_enabled: bool
+    codex_approval_policy: str
+    codex_sandbox_mode: str
+    codex_web_search: str
+    instruction_bullets: tuple[str, ...]
+
+
+BASELINE_INSTRUCTION_BULLETS = (
+    "Use `.ai-codex.json` as the tracked source of truth for local agent configuration.",
+    "Use `.ai-opencodex.md` as the generated repo instruction file.",
+    "Avoid a root `AGENTS.md` in the repository root because it shadows fallback instruction filenames for Codex discovery.",
+    "Treat `.codex/config.toml`, `opencode.json`, and `.agents/skills/` as generated local artifacts.",
+    "Re-run `ai-codex sync` after manifest changes instead of editing generated files by hand.",
+)
+
+
+PROFILE_DEFINITIONS: dict[str, ProfileDefinition] = {
+    "augint": ProfileDefinition(
+        name="augint",
+        summary="Standard Augmenting Integrations work profile with live web access and local agent guidance.",
+        instruction_bullets=(
+            "Prefer practical, minimal changes that preserve the existing repository's patterns.",
+            "Treat shell guardrails as real approval prompts for risky operational commands.",
+        ),
+        blocked_paths=(
+            "**/secrets/**",
+            "**/*.pem",
+            "**/terraform.tfstate*",
+        ),
+        ask_patterns=(
+            "aws *",
+            "terraform *",
+            "kubectl *",
+            "git push *",
+        ),
+        deny_patterns=(),
+    ),
+    "gov": ProfileDefinition(
+        name="gov",
+        summary="Stricter overlay for compliance-sensitive repositories with broader defaults and more conservative command handling.",
+        instruction_bullets=(
+            "Use the same working model as `augint`, but be more conservative with compliance-sensitive changes.",
+            "Escalate or slow down when commands or outputs could affect regulated systems or sensitive data.",
+        ),
+        blocked_paths=(
+            "**/secrets/**",
+            "**/*.pem",
+            "**/*.key",
+            "**/*.p12",
+            "**/terraform.tfstate*",
+            "**/.aws/**",
+        ),
+        ask_patterns=(
+            "aws *",
+            "terraform *",
+            "kubectl *",
+            "git push *",
+            "az *",
+            "gcloud *",
+            "gh secret *",
+        ),
+        deny_patterns=(
+            "aws iam create*",
+            "aws iam put*",
+            "terraform destroy *",
+        ),
+    ),
+}
+
+
+def resolve_policy(manifest: Manifest, project_root: Path, manifest_path: Path) -> ResolvedPolicy:
+    """Merge baseline policy, profile defaults, and manifest settings."""
+
+    profile = PROFILE_DEFINITIONS[manifest.profile]
+    return ResolvedPolicy(
+        project_root=project_root.resolve(),
+        manifest_path=manifest_path.resolve(),
+        profile_name=profile.name,
+        profile_summary=profile.summary,
+        references=_dedupe(manifest.references),
+        blocked_paths=_dedupe(profile.blocked_paths + tuple(manifest.blocked_paths)),
+        ask_patterns=_dedupe(profile.ask_patterns + tuple(manifest.shell_guardrails.ask)),
+        deny_patterns=_dedupe(profile.deny_patterns + tuple(manifest.shell_guardrails.deny)),
+        no_emojis=manifest.content_policy.no_emojis,
+        no_ai_mentions=manifest.content_policy.no_ai_mentions,
+        org_python_library=manifest.patterns.org_python_library,
+        opencode_enabled=manifest.opencode.enabled,
+        codex_approval_policy=profile.approval_policy,
+        codex_sandbox_mode=profile.sandbox_mode,
+        codex_web_search=profile.web_search,
+        instruction_bullets=BASELINE_INSTRUCTION_BULLETS + profile.instruction_bullets,
+    )
+
+
+def _dedupe(values: tuple[str, ...] | list[str]) -> tuple[str, ...]:
+    seen: set[str] = set()
+    ordered: list[str] = []
+    for value in values:
+        if value not in seen:
+            ordered.append(value)
+            seen.add(value)
+    return tuple(ordered)

augint_opencodex-0.0.0/src/augint_opencodex/renderer.py

@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from augint_opencodex.profiles import ResolvedPolicy
+
+INSTRUCTION_FILE = Path(".ai-opencodex.md")
+LEGACY_INSTRUCTION_FILE = Path(".ai-codex.md")
+
+MANAGED_FILE_PATHS = (
+    Path(".codex/config.toml"),
+    INSTRUCTION_FILE,
+    Path("opencode.json"),
+    Path(".agents/skills/README.md"),
+    Path(".agents/skills/org-python-tooling/SKILL.md"),
+    LEGACY_INSTRUCTION_FILE,
+)
+
+
+@dataclass(frozen=True)
+class RenderedFile:
+    """A generated file and the content that should be written to it."""
+
+    path: Path
+    content: str
+
+
+def render_project(policy: ResolvedPolicy) -> tuple[RenderedFile, ...]:
+    """Render all files for the first working slice."""
+
+    files = [
+        RenderedFile(Path(".codex/config.toml"), _render_codex_config(policy)),
+        RenderedFile(INSTRUCTION_FILE, _render_ai_opencodex_markdown(policy)),
+        RenderedFile(Path(".agents/skills/README.md"), _render_skills_readme()),
+    ]
+
+    if policy.opencode_enabled:
+        files.append(RenderedFile(Path("opencode.json"), _render_opencode_json(policy)))
+
+    if policy.org_python_library:
+        files.append(
+            RenderedFile(
+                Path(".agents/skills/org-python-tooling/SKILL.md"),
+                _render_org_python_tooling_skill(),
+            )
+        )
+
+    return tuple(files)
+
+
+def managed_file_paths() -> tuple[Path, ...]:
+    """Return all paths managed by the first working slice."""
+
+    return MANAGED_FILE_PATHS
+
+
+def _render_codex_config(policy: ResolvedPolicy) -> str:
+    return (
+        "# Generated by ai-codex from .ai-codex.json.\n"
+        "# Do not edit by hand; re-run `ai-codex sync` after manifest changes.\n"
+        "# Run `CODEX_HOME=$(pwd)/.codex codex` to use this generated config as Codex home config.\n"
+        f'web_search = "{policy.codex_web_search}"\n'
+        f'approval_policy = "{policy.codex_approval_policy}"\n'
+        f'sandbox_mode = "{policy.codex_sandbox_mode}"\n'
+        'model_instructions_file = "../.ai-opencodex.md"\n'
+        'project_doc_fallback_filenames = [".ai-opencodex.md"]\n'
+    )
+
+
+def _render_ai_opencodex_markdown(policy: ResolvedPolicy) -> str:
+    lines = [
+        "# AI OpenCodex Project Instructions",
+        "",
+        "This file is generated from `.ai-codex.json` by `ai-codex sync`.",
+        "This repository uses `.ai-opencodex.md` as its generated repo-local instructions file.",
+        "Avoid a root `AGENTS.md` here because Codex gives `AGENTS.md` precedence over fallback filenames in the same directory.",
+        "Edit the manifest and re-run the tool instead of editing this file directly.",
+        "",
+        "## Working Contract",
+    ]
+    lines.extend(f"- {bullet}" for bullet in policy.instruction_bullets)
+    lines.extend(
+        [
+            "",
+            "## Active Profile",
+            f"- Profile: `{policy.profile_name}`",
+            f"- Summary: {policy.profile_summary}",
+            "",
+            "## References",
+        ]
+    )
+
+    if policy.references:
+        lines.extend(f"- `{reference}`" for reference in policy.references)
+    else:
+        lines.append("- No explicit reference repositories were configured.")
+
+    lines.extend(
+        [
+            "",
+            "## Content Policy",
+            (
+                "- Do not use emojis in documentation or generated text unless explicitly requested."
+                if policy.no_emojis
+                else "- Emoji use is allowed."
+            ),
+            (
+                "- Do not mention AI in commit messages, code comments, or generated code unless explicitly requested."
+                if policy.no_ai_mentions
+                else "- AI mentions are allowed when they improve clarity."
+            ),
+            "",
+            "## Blocked Paths",
+        ]
+    )
+
+    lines.extend(f"- `{blocked_path}`" for blocked_path in policy.blocked_paths)
+    lines.extend(
+        [
+            "- These are instruction-level safeguards here; use stronger runtime controls when a path must be truly inaccessible.",
+            "",
+            "## Shell Guardrails",
+        ]
+    )
+
+    if policy.ask_patterns:
+        lines.extend(f"- Ask before running `{pattern}`" for pattern in policy.ask_patterns)
+    if policy.deny_patterns:
+        lines.extend(f"- Deny `{pattern}`" for pattern in policy.deny_patterns)
+    if not policy.ask_patterns and not policy.deny_patterns:
+        lines.append("- No additional shell guardrails were configured.")
+
+    if policy.org_python_library:
+        lines.extend(
+            [
+                "",
+                "## Organizational Python Tooling Standard",
+                "- Use a `uv`-first workflow for dependency management, locking, and builds.",
+                "- Keep Python packages in `src/` and expose CLIs through `[project.scripts]`.",
+                "- Preserve `ruff`, `mypy`, `pytest`, coverage, and `pre-commit` as standard tooling.",
+                "- Keep Conventional Commit discipline and semantic-release-compatible versioning in place.",
+                "- Maintain code-quality, security, compliance, and build-validation jobs in CI.",
+                "- Keep a stable task surface such as `install`, `test`, `format`, `typecheck`, `security`, and `build`.",
+            ]
+        )
+
+    if not policy.opencode_enabled:
+        lines.extend(
+            [
+                "",
+                "## OpenCode",
+                "- OpenCode output is disabled by `opencode.enabled = false` in the manifest.",
+            ]
+        )
+
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _render_opencode_json(policy: ResolvedPolicy) -> str:
+    instructions = [
+        "Read .ai-opencodex.md before making changes.",
+        "Treat .ai-opencodex.md and .codex/config.toml as the canonical local project policy.",
+        "This repository intentionally avoids a root AGENTS.md so Codex and OpenCode follow the same generated instructions artifact.",
+        "Use .agents/skills/ when shared reusable skills are available.",
+    ]
+    if policy.blocked_paths:
+        instructions.append(
+            "Avoid blocked paths called out in .ai-opencodex.md unless the user explicitly changes policy."
+        )
+
+    opencode = {
+        "$schema": "https://opencode.ai/config.json",
+        "instructions": instructions,
+        "permission": {
+            "read": "allow",
+            "edit": "allow",
+            "glob": "allow",
+            "grep": "allow",
+            "list": "allow",
+            "bash": "ask" if policy.profile_name == "gov" else "allow",
+            "skill": "allow",
+            "webfetch": "allow",
+            "websearch": "allow",
+            "external_directory": "ask",
+            "doom_loop": "ask",
+        },
+    }
+    return json.dumps(opencode, indent=2) + "\n"
+
+
+def _render_skills_readme() -> str:
+    return (
+        "# Shared Skills Directory\n\n"
+        "This directory is generated by `ai-codex sync` for reusable repo-local skills.\n"
+        "Update `.ai-codex.json` and re-run the tool instead of editing generated files by hand.\n"
+    )
+
+
+def _render_org_python_tooling_skill() -> str:
+    return (
+        "# Org Python Tooling Standard\n\n"
+        "Use this skill when working in a repository that follows the organizational Python library or tool standard.\n\n"
+        "## Standard\n\n"
+        "- Use `uv` for dependency management, locking, testing, and builds.\n"
+        "- Keep a `src/` package layout and expose entry points through `[project.scripts]`.\n"
+        "- Preserve `ruff`, `mypy`, `pytest`, coverage thresholds, and `pre-commit`.\n"
+        "- Maintain Conventional Commit discipline and semantic-release-compatible versioning.\n"
+        "- Keep security and compliance checks in CI, including dependency and license scanning.\n"
+        "- Prefer a stable Makefile task surface over ad hoc project-specific commands.\n"
+    )

augint_opencodex-0.0.0/src/augint_opencodex/sync_engine.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from augint_opencodex.ignore import ExcludeUpdate, ensure_git_exclude
+from augint_opencodex.manifest import load_manifest
+from augint_opencodex.profiles import ResolvedPolicy, resolve_policy
+from augint_opencodex.renderer import managed_file_paths, render_project
+
+
+@dataclass(frozen=True)
+class SyncReport:
+    """The result of resolving and optionally writing generated files."""
+
+    mode: Literal["write", "dry-run", "check"]
+    policy: ResolvedPolicy
+    changed_files: tuple[Path, ...]
+    stale_files: tuple[Path, ...]
+    written_files: tuple[Path, ...]
+    removed_files: tuple[Path, ...]
+    unchanged_files: tuple[Path, ...]
+    exclude_update: ExcludeUpdate
+
+    @property
+    def needs_changes(self) -> bool:
+        return bool(self.changed_files or self.stale_files) or self.exclude_update.needs_update
+
+
+def sync_project(
+    project_root: Path,
+    manifest_path: Path | None = None,
+    *,
+    mode: Literal["write", "dry-run", "check"] = "write",
+) -> SyncReport:
+    """Load the manifest, resolve policy, and render local project files."""
+
+    resolved_root = project_root.resolve()
+    resolved_manifest_path = _resolve_manifest_path(resolved_root, manifest_path)
+    manifest = load_manifest(resolved_manifest_path)
+    policy = resolve_policy(manifest, resolved_root, resolved_manifest_path)
+    rendered_files = render_project(policy)
+
+    changed_files: list[Path] = []
+    stale_files: list[Path] = []
+    written_files: list[Path] = []
+    removed_files: list[Path] = []
+    unchanged_files: list[Path] = []
+
+    for rendered_file in rendered_files:
+        target_path = resolved_root / rendered_file.path
+        if target_path.exists():
+            current_content = target_path.read_text(encoding="utf-8")
+        else:
+            current_content = None
+
+        if current_content == rendered_file.content:
+            unchanged_files.append(rendered_file.path)
+            continue
+
+        changed_files.append(rendered_file.path)
+        if mode == "write":
+            target_path.parent.mkdir(parents=True, exist_ok=True)
+            target_path.write_text(rendered_file.content, encoding="utf-8")
+            written_files.append(rendered_file.path)
+
+    expected_paths = {rendered_file.path for rendered_file in rendered_files}
+    for managed_path in managed_file_paths():
+        if managed_path in expected_paths:
+            continue
+
+        target_path = resolved_root / managed_path
+        if not target_path.exists():
+            continue
+
+        stale_files.append(managed_path)
+        if mode == "write":
+            target_path.unlink()
+            _prune_empty_parent_dirs(target_path.parent, stop_at=resolved_root)
+            removed_files.append(managed_path)
+
+    exclude_update = ensure_git_exclude(resolved_root, write=mode == "write")
+    return SyncReport(
+        mode=mode,
+        policy=policy,
+        changed_files=tuple(changed_files),
+        stale_files=tuple(stale_files),
+        written_files=tuple(written_files),
+        removed_files=tuple(removed_files),
+        unchanged_files=tuple(unchanged_files),
+        exclude_update=exclude_update,
+    )
+
+
+def _resolve_manifest_path(project_root: Path, manifest_path: Path | None) -> Path:
+    if manifest_path is not None:
+        return manifest_path.resolve()
+    return (project_root / ".ai-codex.json").resolve()
+
+
+def _prune_empty_parent_dirs(path: Path, *, stop_at: Path) -> None:
+    current = path
+    resolved_stop = stop_at.resolve()
+    while current != resolved_stop and current.exists():
+        try:
+            current.rmdir()
+        except OSError:
+            break
+        current = current.parent