Add managed Codex toolkit and portable workflows

.github/workflows/toolkit.yml

@@ -0,0 +1,38 @@
+name: Agentics Toolkit
+
+on:
+  push:
+    branches: [main]
+    paths: ["src/**", "tests/**", "skills/**", "agents/**", "workflows/**", "references/**", "catalog.json", "pyproject.toml", ".github/workflows/toolkit.yml"]
+  pull_request:
+    paths: ["src/**", "tests/**", "skills/**", "agents/**", "workflows/**", "references/**", "catalog.json", "pyproject.toml", ".github/workflows/toolkit.yml"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.11", "3.14"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install '.[test]' build
+      - run: agentics validate
+      - run: python -m unittest discover -s tests -v
+      - run: python -m build
+      - name: Verify isolated wheel installation
+        shell: bash
+        run: |
+          python -m venv "$RUNNER_TEMP/agentics-wheel"
+          "$RUNNER_TEMP/agentics-wheel/bin/python" -m pip install dist/*.whl
+          cd "$RUNNER_TEMP"
+          "$RUNNER_TEMP/agentics-wheel/bin/agentics" validate
+          "$RUNNER_TEMP/agentics-wheel/bin/agentics" install --all --home "$RUNNER_TEMP/agentics-home"
+          "$RUNNER_TEMP/agentics-wheel/bin/agentics" status --home "$RUNNER_TEMP/agentics-home" --json
+          "$RUNNER_TEMP/agentics-wheel/bin/agentics" uninstall --all --home "$RUNNER_TEMP/agentics-home"

.gitignore

@@ -4,3 +4,9 @@
 # macOS Finder metadata
 .DS_Store
 **/.DS_Store
+
+# Python toolkit builds and local environments
+__pycache__/
+.venv/
+dist/
+build/

AGENTS.md

@@ -8,6 +8,27 @@ Central repository for reusable AI agent configuration, rules, workflows, and or
 
 ## Key Commands
 
+### Codex toolkit
+
+```bash
+python3 -m pip install '.[test]' build
+agentics validate
+python3 -m unittest discover -s tests -v
+python3 -m build
+agentics install --all --dry-run
+agentics install --all
+agentics status
+agentics update --dry-run
+```
+
+- Edit canonical sources here; global copies are managed installations, not editable source.
+- Keep skills portable by discovering the target repository's root/scoped guidance and native commands. Project policy, private operational context, and historical markers stay with their owning projects.
+- Maintain catalog IDs, dependencies, bundled-resource links, and existing invocation policies together. Shared custom agents inherit model/reasoning and retain review-only instructions.
+- Every install/update/uninstall must preflight ownership and all selected destinations. Refuse unknown, modified, missing, or additional managed files; dry-run must not create state.
+- Helper target repositories come from explicit `--repo-root` or Git CWD discovery, never the installed package location. Tests mock external writes.
+- Installing workflows does not configure schedules or authorize Git/GitHub publication or live deployment. Keep conventional CI/CD with its owning project.
+- Wheel builds must include the complete catalog. Verify the wheel from outside the checkout as well as source tests.
+
 ### gh aw (Agentic Workflows)
 
 ```bash
@@ -50,11 +71,12 @@ pre-commit run -a   # Run all hooks
 
 ## Architecture
 
-### Three Subprojects
+### Four Subprojects
 
-1. **`.github/workflows/`** — gh aw agentic workflow definitions (markdown → compiled YAML)
-2. **precommit-agentic-check/** — Standalone Python package (`agentic-check` CLI) that runs LLM-backed pre-commit checks on staged diffs. Packaged with setuptools, requires Python ≥3.10, published to PyPI on tags matching `precommit-agentic-check-v*`.
-3. **claude-commands/** — Claude Code custom slash commands (`/review`, `/refine`, `/suggest`, `/design`, `/daily`, `/ticket`) and shared reference files. This repo is the source of truth; files are deployed to `~/.claude/` via `make deploy`.
+1. **Codex toolkit** — `src/agentics_tools/` supplies the `agentics` installer and portable GitHub helpers. Canonical `skills/`, `agents/`, `workflows/`, and `references/` are assembled by `catalog.json` and bundled in the Python wheel.
+2. **`.github/workflows/`** — gh aw agentic workflow definitions (markdown → compiled YAML)
+3. **precommit-agentic-check/** — Standalone Python package (`agentic-check` CLI) that runs LLM-backed pre-commit checks on staged diffs. Packaged with setuptools, requires Python ≥3.10, published to PyPI on tags matching `precommit-agentic-check-v*`.
+4. **claude-commands/** — Claude Code custom slash commands (`/review`, `/refine`, `/suggest`, `/design`, `/daily`, `/ticket`) and shared reference files. This repo is the source of truth; files are deployed to `~/.claude/` via `make deploy`.
 
 ### Claude Commands
 
@@ -136,4 +158,5 @@ Supported engines: `copilot`, `claude`, `codex`, or custom.
 - Never merge Dependabot PRs that modify generated manifests (`.github/workflows/package.json`, etc.) — update the source `.md` files and rerun `gh aw compile --dependabot`
 - Workflow source `.md` files live in `.github/workflows/` — author and edit them there directly.
 - The `CLAUDE.md` and `AGENTS.md` files must stay in sync (the `agents-doc-sync` workflow enforces this)
+- **Maintenance playbooks**: `workflows/` contains manually requested procedures, distinct from gh-aw sources under `.github/workflows/`. Do not recreate retired schedulers.
 - **claude-commands**: Never edit files directly in `~/.claude/commands/` or `~/.claude/shared/` — edit in this repo, then `make deploy`. Commands reference shared files via `~/.claude/shared/...` paths resolved at runtime.

CLAUDE.md

@@ -1,13 +1,34 @@
-# CLAUDE.md
+# AGENTS.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This file provides guidance to agentic coding assistants (such as OpenAI Codex) when working with code in this repository. It mirrors `CLAUDE.md` — the two are kept in sync by the `agents-doc-sync` workflow.
 
 ## Repository Purpose
 
 Central repository for reusable AI agent configuration, rules, workflows, and orchestration tooling. Standardizes how AI assistants and automation behave across projects.
 
 ## Key Commands
 
+### Codex toolkit
+
+```bash
+python3 -m pip install '.[test]' build
+agentics validate
+python3 -m unittest discover -s tests -v
+python3 -m build
+agentics install --all --dry-run
+agentics install --all
+agentics status
+agentics update --dry-run
+```
+
+- Edit canonical sources here; global copies are managed installations, not editable source.
+- Keep skills portable by discovering the target repository's root/scoped guidance and native commands. Project policy, private operational context, and historical markers stay with their owning projects.
+- Maintain catalog IDs, dependencies, bundled-resource links, and existing invocation policies together. Shared custom agents inherit model/reasoning and retain review-only instructions.
+- Every install/update/uninstall must preflight ownership and all selected destinations. Refuse unknown, modified, missing, or additional managed files; dry-run must not create state.
+- Helper target repositories come from explicit `--repo-root` or Git CWD discovery, never the installed package location. Tests mock external writes.
+- Installing workflows does not configure schedules or authorize Git/GitHub publication or live deployment. Keep conventional CI/CD with its owning project.
+- Wheel builds must include the complete catalog. Verify the wheel from outside the checkout as well as source tests.
+
 ### gh aw (Agentic Workflows)
 
 ```bash
@@ -50,11 +71,12 @@ pre-commit run -a   # Run all hooks
 
 ## Architecture
 
-### Three Subprojects
+### Four Subprojects
 
-1. **`.github/workflows/`** — gh aw agentic workflow definitions (markdown → compiled YAML)
-2. **precommit-agentic-check/** — Standalone Python package (`agentic-check` CLI) that runs LLM-backed pre-commit checks on staged diffs. Packaged with setuptools, requires Python ≥3.10, published to PyPI on tags matching `precommit-agentic-check-v*`.
-3. **claude-commands/** — Claude Code custom slash commands (`/review`, `/refine`, `/suggest`, `/design`, `/daily`, `/ticket`) and shared reference files. This repo is the source of truth; files are deployed to `~/.claude/` via `make deploy`.
+1. **Codex toolkit** — `src/agentics_tools/` supplies the `agentics` installer and portable GitHub helpers. Canonical `skills/`, `agents/`, `workflows/`, and `references/` are assembled by `catalog.json` and bundled in the Python wheel.
+2. **`.github/workflows/`** — gh aw agentic workflow definitions (markdown → compiled YAML)
+3. **precommit-agentic-check/** — Standalone Python package (`agentic-check` CLI) that runs LLM-backed pre-commit checks on staged diffs. Packaged with setuptools, requires Python ≥3.10, published to PyPI on tags matching `precommit-agentic-check-v*`.
+4. **claude-commands/** — Claude Code custom slash commands (`/review`, `/refine`, `/suggest`, `/design`, `/daily`, `/ticket`) and shared reference files. This repo is the source of truth; files are deployed to `~/.claude/` via `make deploy`.
 
 ### Claude Commands
 
@@ -136,4 +158,5 @@ Supported engines: `copilot`, `claude`, `codex`, or custom.
 - Never merge Dependabot PRs that modify generated manifests (`.github/workflows/package.json`, etc.) — update the source `.md` files and rerun `gh aw compile --dependabot`
 - Workflow source `.md` files live in `.github/workflows/` — author and edit them there directly.
 - The `CLAUDE.md` and `AGENTS.md` files must stay in sync (the `agents-doc-sync` workflow enforces this)
+- **Maintenance playbooks**: `workflows/` contains manually requested procedures, distinct from gh-aw sources under `.github/workflows/`. Do not recreate retired schedulers.
 - **claude-commands**: Never edit files directly in `~/.claude/commands/` or `~/.claude/shared/` — edit in this repo, then `make deploy`. Commands reference shared files via `~/.claude/shared/...` paths resolved at runtime.

README.md

@@ -2,6 +2,88 @@
 
 > CLI tools, slash commands, and workflows that put AI agents to work across the development lifecycle — from code review to workflow automation.
 
+## Global Codex toolkit
+
+Agentics is the source of truth for 26 reusable skills (25 extracted workflows plus a maintenance router), 13 custom agents, and ten maintenance playbooks. Project commands, product requirements, infrastructure details, and PR policies stay in each project's own guidance.
+
+Install the Python 3.11+ command from a checkout:
+
+```bash
+uv tool install .
+agentics validate
+agentics install --all --dry-run
+agentics install --all
+```
+
+Without uv, install into a dedicated virtual environment with `python3 -m venv .venv` and `.venv/bin/python -m pip install .`, then use `.venv/bin/agentics` for the commands below. Installing the package alone does not install skills or change Codex settings.
+
+```bash
+agentics list
+agentics install --group core --group github
+agentics install --skill stack-rollout --agent simplicity_reviewer
+agentics status --json
+agentics update --dry-run
+agentics update
+agentics uninstall --all --dry-run
+```
+
+| Group | Capabilities |
+| --- | --- |
+| `core` | Change planning, reproduction, cohesion, tests, verification, and final audit |
+| `github` | PR review, refinement, conflicts, comments, drafts, metadata, previews, and gates |
+| `docs` | Change documentation, documentation audits and maintenance, backlog work, and capability maintenance |
+| `ops` | Deployment safety, Cloudflare, Dokploy, service integration, rollout, and observability |
+| `maintenance` | Requested maintenance playbooks and coordination |
+
+Selections include declared dependencies. Omit a selection for `status` to inspect the whole catalog; omit it for `update` or `uninstall` to operate on owned installations. `update --all` only updates already installed items. Removing one skill leaves its supporting roles installed; removing an agent still required by an installed skill is refused.
+
+Skills are copied to `~/.agents/skills/`; agents go to `${CODEX_HOME:-~/.codex}/agents/`. Ownership and content hashes live in `${CODEX_HOME:-~/.codex}/agentics/installed.json`. `--home` and `--codex-home` allow isolated installations and tests. Pulling this repo changes no installed tools: upgrade the command with `uv tool upgrade agentics-toolkit --reinstall`, then run `agentics update`. For a local checkout, rerun `uv tool install --reinstall .` before updating.
+
+The installer checks the complete operation before writing, preserves executable resources, and refuses unknown collisions or locally changed, missing, or additional bundle files. Keep custom edits outside managed copies. If rollback cannot finish, the installer retains its lock and reports recovery paths; restore the affected files before removing the lock and retrying. A stale installation lock otherwise requires inspecting the interrupted operation before removing it. Codex settings, MCP servers, permissions, and global instructions are not changed. Agents inherit model and reasoning settings; review-only instructions do not create a separate sandbox. Restart Codex if newly installed tools do not appear.
+
+Public discovery and custom-agent locations follow the official [skills](https://learn.chatgpt.com/docs/build-skills) and [subagent](https://learn.chatgpt.com/docs/agent-configuration/subagents) documentation. Use the Agentics installer for the complete bundled resources and role dependencies.
+
+### Using skills and maintenance workflows
+
+Invoke skills as `$change-plan`, `$pr-review`, or another name from `agentics list`. Only load the skills needed for the request. PR review remains explicitly invoked. The collection follows the target repository's root and scoped `AGENTS.md`, templates, and owning documentation; it imposes no required project configuration schema.
+
+```bash
+agentics workflows list
+agentics workflows show daily-bug-scan
+```
+
+Use `$maintenance-workflow` with a playbook ID to run a requested procedure. The playbooks include PR maintenance, error triage, bug scans, test gaps, documentation cohesion, product/marketing consistency, code health, and change digests. Installing or reading a playbook creates no schedules and grants no publication or deployment authority. Optional integrations must already be available and authorized.
+
+### Portable GitHub helpers
+
+```bash
+agentics tools --repo-root /path/to/checkout pr-threads list-open-prs
+agentics tools --repo-root /path/to/checkout pr-threads list-merged-prs
+agentics tools --repo-root /path/to/checkout pr-threads list-unresolved-threads --pr 42
+agentics tools --repo-root /path/to/checkout preview --help
+agentics tools --repo-root /path/to/checkout preview-sync --help
+```
+
+Helpers discover the current checkout through Git when `--repo-root` is omitted. An explicit root takes precedence over ambient repository environment variables; `--repo` explicitly selects the GitHub repository. Author filters use `--author` or the authenticated GitHub identity. The merged-PR command discovers the repository's default branch unless `--base` is supplied. Git and authenticated GitHub CLI are required for GitHub operations; preview publication requires GitHub.com and GitHub CLI 2.99+.
+
+Preview capture stays in the consuming project. Agentics owns artifact storage, capture provenance, hashes, native attachment publication, marked comments, and cleanup. Publishing requires the local and PR heads to match, and missing local captures leave published previews intact. Explicit deletion is separate from local cleanup.
+
+### Developing and consuming the collection
+
+Canonical sources are `skills/`, `agents/`, `workflows/`, and `references/`; `catalog.json` declares groups, dependencies, and resource assembly. The wheel bundles these sources, so installations work without the original checkout. Edit canonical sources and reinstall/update; do not edit installed copies.
+
+Project migration keeps application commands, label/body policies, operational caveats, and historical output markers in existing project docs. A project that calls Python helpers must install the toolkit in its own development/CI environment, pinned to an immutable Git revision or a hash-locked wheel. It must never depend on a developer's global Codex directory. A generated dependency wheel is an installation artifact, not a separately maintained source fork.
+
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install '.[test]' build
+.venv/bin/agentics validate
+.venv/bin/python -m unittest discover -s tests -v
+.venv/bin/python -m build
+```
+
+The toolkit CI validates Python 3.11 and 3.14, catalog resources, installer ownership, and isolated wheel installation. Existing Claude commands and the pre-commit package remain separate subprojects.
+
 ## Subprojects
 
 ### claude-commands
@@ -92,7 +174,7 @@ gh aw compile                        # compile .md sources into .lock.yml
 
 | Workflow | Summary | Install |
 |----------|---------|---------|
-| [Agents Doc Sync](#agents-doc-sync) | Keeps `CLAUDE.md` and `AGENTS.md` aligned; opens a PR only when sync changes are needed. | `gh aw add-wizard aaronspindler/agentic_workflows/agents-doc-sync` |
+| [Agents Doc Sync](#agents-doc-sync) | Keeps `CLAUDE.md` and `AGENTS.md` aligned; opens a PR only when sync changes are needed. | `gh aw add-wizard aaronspindler/agentics/agents-doc-sync` |
 
 ### Agents Doc Sync
 
@@ -109,6 +191,13 @@ Detects divergence between `CLAUDE.md` and `AGENTS.md`, updates the file missing
 
 ```
 agentics/
+├── skills/                      # Canonical portable Codex skills
+├── agents/                      # Custom roles with inherited model settings
+├── workflows/                   # Requested maintenance playbooks
+├── references/                  # Canonical resources bundled per skill
+├── catalog.json                 # Groups, dependencies, and resources
+├── src/agentics_tools/           # Installer and portable helper runtime
+├── tests/                       # Toolkit regression coverage
 ├── claude-commands/             # Claude Code slash commands (source of truth)
 │   ├── commands/                #   /review, /refine, /suggest, /design, /daily, /ticket
 │   ├── shared/                  #   Shared config and templates

agents/auditor.toml

@@ -0,0 +1,9 @@
+name = "auditor"
+description = "Read-only auditor for focused evidence and findings."
+developer_instructions = """
+Follow the active repository instructions and the assigned task boundary. Inherit the caller's model and reasoning preferences.
+
+Audit only the requested change for cohesion, duplicated logic, speculative abstractions, unnecessary indirection, partial pattern shifts, naming/placement, documentation drift, and app-local frontend fidelity. Read owning architecture/design guidance and nearby patterns. Judge behavior and maintenance cost rather than line counts. Preserve correctness, authorization, provenance, retained originals, accessibility, resource bounds, recovery, and meaningful tests. Return concrete AUDIT-NNN findings with severity/confidence, exact references, required versus optional follow-up, scope, and limits. Do not substitute a correctness review or implement cleanup.
+
+Stay read-only across files and external systems, including Git, GitHub, services, dashboards, alerts, and credentials. Inspect helper side effects before checks; use non-mutating evidence only. Never reproduce credentials, private records, or raw secret-bearing logs. Return findings to the parent, which owns implementation and authorized publication.
+"""