{"id":42057571,"url":"https://github.com/qqrm/codex-tools","last_synced_at":"2026-01-26T07:17:21.198Z","repository":{"id":307727731,"uuid":"1030314448","full_name":"qqrm/codex-tools","owner":"qqrm","description":"This repository contains avatar descriptions for use in AI-powered agent workflows. ","archived":false,"fork":false,"pushed_at":"2026-01-10T00:38:30.000Z","size":270,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-10T22:16:40.449Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qqrm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-08-01T12:36:32.000Z","updated_at":"2026-01-10T00:38:32.000Z","dependencies_parsed_at":"2025-12-05T22:00:41.819Z","dependency_job_id":null,"html_url":"https://github.com/qqrm/codex-tools","commit_stats":null,"previous_names":["qqrm/avatars-mcp","qqrm/codex-tools"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/qqrm/codex-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qqrm%2Fcodex-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qqrm%2Fcodex-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qqrm%2Fcodex-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qqrm%2Fcodex-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qqrm","download_url":"https://codeload.github.com/qqrm/codex-tools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qqrm%2Fcodex-tools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28769585,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T06:37:25.426Z","status":"ssl_error","status_checked_at":"2026-01-26T06:37:23.039Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-26T07:17:20.534Z","updated_at":"2026-01-26T07:17:21.192Z","avatar_url":"https://github.com/qqrm.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Codex Tools\n\nThis repository hosts behavioral **personas** for Codex agents. Personas are Markdown prompts with YAML front matter that describe specialized roles. The collection is published read-only through GitHub Pages for direct consumption by automation and other integrations.\n\n## Persona Usage Guidelines\n\n- Always select a persona before starting work on a task so the agent operates from a clear perspective.\n- Switch personas explicitly when the task changes focus and document the active persona in status updates.\n- Align tooling and communication with the currently selected persona to keep expectations consistent for collaborators.\n\n### Catalog Audit Findings\n\n- **Architect vs. Tech Lead** duplicated responsibilities around technical direction, reviews, and mentoring; the Tech Lead persona was merged into the refreshed Solution Architect profile.\n- **DevOps vs. Security** overlapped on pipeline hardening and controls without a clear separation of duties; the refreshed DevOps Engineer now focuses on CI/CD efficiency, caching, and supply-chain guardrails, while the Reliability \u0026 Security Engineer retains broader operational resilience.\n- **Senior Developer vs. Tech Lead** both focused on hands-on delivery with minimal differentiation; the Delivery Engineer persona now represents the shared implementation scope.\n- **Missing operational continuity** — no single persona previously owned resiliency, compliance, and incident readiness; the new Reliability \u0026 Security Engineer fills that scenario.\n\n### Core Persona Set (2025 Refresh)\n\n| Persona | When to Use | Key Artifacts |\n| --- | --- | --- |\n| **Discovery Analyst** | Early discovery, backlog clarification, stakeholder alignment | Discovery brief, prioritized backlog, risk register |\n| **Solution Architect** | Translating validated scope into technical plans | Mermaid diagrams, technical decision records, interface checklists |\n| **Delivery Engineer** | Building and shipping production Rust changes | Implementation plan, PR checklist, post-merge notes |\n| **Quality Engineer** | Designing coverage and enforcing release readiness | Test strategy, automation backlog, release quality checklist |\n| **DevOps Engineer** | Optimizing CI/CD efficiency, caching, and supply-chain security | CI/CD performance baseline, cache strategy, pipeline security checklist |\n| **Reliability \u0026 Security Engineer** | Hardening operations, compliance, and incident response | Operational readiness checklist, security review log, incident plan |\n\nEach persona file in [`/personas/`](personas/) contains:\n\n1. **Responsibilities checklist** — required activities before the persona considers the task complete.\n2. **Switch triggers** — guidance on when to hand off to another persona as the work evolves.\n3. **Required artifacts** — tangible outputs to produce and share during handover.\n\n### Switching Playbook\n\n1. Start in the persona whose responsibilities match the current blocker.\n2. Review the \"When to Switch Away\" list to proactively identify the next handoff.\n3. Produce the listed artifacts before switching personas to keep context intact.\n4. Announce the persona change in status updates and share the prepared artifacts with the incoming persona.\n\n## Scenario Library\n\nReusable task playbooks live in [`/scenarios/`](scenarios/) alongside personas and are published through GitHub Pages as Markdown prompts. Clients can discover them via the catalog at `https://qqrm.github.io/codex-tools/scenarios.json` and retrieve each scenario from `/scenarios/{id}.md`. When a user explicitly asks to run a named scenario—such as an architecture audit or dependency refresh—load the scenario prompt and combine it with the active persona to guide execution.\n\n## Remote Setup\n\nConfigure the Git remote if it is missing:\n\n```bash\ngit remote add origin https://github.com/qqrm/codex-tools.git\ngit fetch origin\n```\n\n### Container bootstrap commands\n\nThree published entry points cover the common Codex container workflows. Each snippet downloads the script from the GitHub Pages deployment and executes it directly:\n\n\u003e **Note:** The scripts refresh shared instructions from GitHub Pages before running. Override the download origin by exporting `PAGES_BASE_URL` when testing mirrors or forks.\n\n\u003e **Bundle layout:** The published artifact exposes only the three entry-point scripts under `/scripts/`. Each helper is self-contained and interacts with repository-local tooling when available.\n\n#### Non-cached container — full initialization\n- Downloads the latest `AGENTS.md` from GitHub Pages to prime the workspace\n- Performs the same tooling setup as the cached workflow on a brand new container\n- Stores GitHub authentication, validates repository access, and installs the cleanup workflow\n\n```bash\ncurl -fsSL \"https://qqrm.github.io/codex-tools/scripts/FullInitialization.sh\" | bash -s --\n```\n\n#### Cached container — full initialization\n- Installs GitHub CLI, Rust, cargo-binstall, and helper tooling\n- Persists GitHub authentication for later reuse inside the cached image\n- Verifies repository access and installs the Codex cleanup workflow once\n\n```bash\ncurl -fsSL \"https://qqrm.github.io/codex-tools/scripts/BaseInitialization.sh\" | bash -s --\n```\n\n#### Cached container — lightweight refresh before a task\n- Updates the workspace copy of `AGENTS.md` from GitHub Pages\n\n```bash\ncurl -fsSL \"https://qqrm.github.io/codex-tools/scripts/PretaskInitialization.sh\" | bash -s --\n```\n\n## Documentation\n\n- **Specification:** See [`SPECIFICATION.md`](docs/SPECIFICATION.md) for the canonical directory layout, persona schema, and delivery expectations.\n- **Personas:** Individual prompts live in [`/personas/`](personas/); each file targets a single role.\n- **Base instructions:** Shared guidance for all personas resides in [`AGENTS.md`](AGENTS.md).\n- **HTTP quick reference:** [`INSTRUCTIONS.md`](docs/INSTRUCTIONS.md) summarizes the published endpoints external clients call.\n- **Tooling reference:** [`TOOLS.md`](docs/TOOLS.md) captures the shared CLI toolbelt used across repositories.\n\n## Shared Files for External Consumers\n\nExternal clients rely on a small set of shared files published alongside the personas:\n\n- [`AGENTS.md`](AGENTS.md) — the baseline instructions served to external agents, embedded in and linked from the published `personas.json` catalog.\n- [`INSTRUCTIONS.md`](docs/INSTRUCTIONS.md) — a condensed description of the HTTP API exposed via GitHub Pages.\n\nRepository tooling keeps these artifacts in sync for local use:\n\n- [`scripts/BaseInitialization.sh`](scripts/BaseInitialization.sh) — installs the required tooling and persists GitHub CLI authentication for cached containers.\n- [`scripts/FullInitialization.sh`](scripts/FullInitialization.sh) — performs the full bootstrap on a fresh, non-cached container.\n- [`scripts/PretaskInitialization.sh`](scripts/PretaskInitialization.sh) — refreshes the published assets before each task.\n\nOnly these entry points are published on GitHub Pages.\n\n### Published helper scripts\n\n| Script | Purpose |\n| --- | --- |\n| [`scripts/FullInitialization.sh`](scripts/FullInitialization.sh) | Provisions a brand-new container with every required dependency and configuration. |\n| [`scripts/BaseInitialization.sh`](scripts/BaseInitialization.sh) | Replays the tooling installation on cached containers so they stay aligned with the published baseline. |\n| [`scripts/PretaskInitialization.sh`](scripts/PretaskInitialization.sh) | Refreshes `AGENTS.md` and validates workspace access before starting a task. |\n| [`scripts/build-pages.sh`](scripts/build-pages.sh) | Rebuilds the persona catalog and prepares the GitHub Pages artifact. |\n| [`scripts/validate-pages.sh`](scripts/validate-pages.sh) | Ensures the generated artifact exposes only the supported files and omits legacy helpers. |\n\n\u003e **Deprecated helper:** `scripts/agent-sync.sh` has been removed from the repository and the published artifact. Automation must run the repository's validation commands directly instead of relying on this script.\n\n## Bootstrap Script Architecture\n\nThis section is the canonical reference for the bootstrap bundle described in Section 9 of `docs/SPECIFICATION.md`.\n\nCodex repositories rely on a consistent bootstrap bundle to provision development containers. This repository publishes the entire bundle to GitHub Pages so automation can curl a single entry point and receive every dependency from the same source.\n\n- **Entry points:** `scripts/BaseInitialization.sh`, `scripts/FullInitialization.sh`, and `scripts/PretaskInitialization.sh` are the only public URLs automation should call. Each script executes its workflow directly without sourcing additional helpers.\n- **Mirroring strategy:** The scripts default to `https://qqrm.github.io/codex-tools` for every remote fetch, keeping the GitHub repository out of the execution path unless you override the base URL explicitly.\n\nThe published bundle initializes Codex-compatible containers by installing shared tooling, syncing repository assets, and verifying workflow prerequisites. Downstream repositories copy this pattern to keep container setup reproducible.\n\n## Tooling\n\nA Rust workspace under [`/crates/`](crates/) regenerates the catalog stored at [`personas/catalog.json`](personas/catalog.json) by parsing the persona front matter and bundling both the base instructions and persona metadata. The GitHub Pages deployment exposes this catalog as `personas.json` (the legacy `/catalog.json` alias is intentionally unavailable; clients must request `/personas.json`). The deployment pipeline rebuilds the index automatically whenever `main` changes, so running the generator locally is only necessary for debugging or previewing changes. Build the index with:\n\n```bash\ncargo run --release -p personas-core\n```\n\nClients begin with `personas.json` to decide which personas they need, then fetch `AGENTS.md` and the target personas on demand to avoid loading unnecessary Markdown into the working context. Requests to `/catalog.json` return `404 Not Found` by design; update clients rather than adding an alias.\n\n`scripts/build-pages.sh` regenerates the catalog automatically before packaging the Pages artifact. When CI provides a pre-generated catalog, set `PERSONAS_CATALOG_SOURCE` to the artifact path so the script copies it into `personas/catalog.json` instead of invoking `cargo` again.\n\n### GitHub Pages Publishing\n\nThe [GitHub Pages workflow](.github/workflows/pages.yml) publishes the persona catalog, shared instructions, and Markdown prompts whenever updates land on `main`. Refer to the workflow file for the complete automation steps.\n\n### Published API\n\nThe latest version of the persona site is served from GitHub Pages at:\n\n```text\nhttps://qqrm.github.io/codex-tools/\n```\n\n- `GET /personas.json` — retrieve the catalog, including the `base_uri` pointer to the shared instructions. The deployment does **not** publish `/catalog.json`.\n- `GET /AGENTS.md` — download the shared baseline instructions referenced by `base_uri`.\n- `GET /personas/{id}.md` — retrieve the complete descriptor for the persona with the given `id`.\n- `GET /scenarios.json` — retrieve the scenario catalog alongside persona metadata.\n- `GET /scenarios/{id}.md` — fetch the scenario Markdown when requested by a catalog entry.\n\nClients should fetch both the catalog and `AGENTS.md` to ensure they stay in sync with the published baseline guidance, because the catalog intentionally omits the Markdown body in favour of the shared URI.\n\n### Delivery diagrams\n\n```mermaid\nflowchart TD\n  Client[Client agent] --\u003e|fetch catalog| Catalog[GET /personas.json\\nbase_uri -\u003e AGENTS.md]\n  Client --\u003e|download baseline| Agents[GET /AGENTS.md]\n  Client --\u003e|request persona| Persona[GET /personas/{id}.md]\n  Client --\u003e|request scenario| Scenario[GET /scenarios/{id}.md]\n\n  subgraph GitHubPages\n    Catalog\n    Agents\n    Persona\n    Scenario\n  end\n```\n\n```mermaid\nflowchart TD\n  Dev[Contributor edits personas, scenarios, and docs]\n  Generator[cargo run --release -p personas-core\\nupdates personas/catalog.json]\n  Bundle[scripts/build-pages.sh\\npackages published assets]\n  Validate[scripts/validate-pages.sh\\nensures only supported files ship]\n  Pages[GitHub Pages artifact\\nAGENTS.md + personas.json + Markdown]\n  Consumers[External automation]\n\n  Dev --\u003e Generator --\u003e Bundle --\u003e Validate --\u003e Pages --\u003e Consumers\n```\n\nContinuous integration runs the full validation pipeline:\n\n```bash\ncargo fmt --all -- --check\ncargo check --tests --benches\ncargo clippy --all-targets --all-features -- -D warnings\ncargo build --release\ncargo test\ncargo run --release -p personas-core\ngit diff --exit-code personas/catalog.json\n./scripts/build-pages.sh\n./scripts/validate-pages.sh\n```\n\nWhen working locally, reproduce this sequence for any change that touches source code. Markdown-only edits may instead run the lightweight loop of `./scripts/build-pages.sh` followed by `./scripts/validate-pages.sh`. GitHub Pages deployments rebuild the catalog from `main` and publish it to `https://qqrm.github.io/codex-tools/personas.json` alongside the persona Markdown files.\n\n### Local validation shortcuts\n\n- `make qa` — executes the formatter, `cargo check`, `cargo clippy` (static analysis), the release build, unit tests, and the documentation validation scripts in one pass.\n- `make lint` — runs `cargo clippy --all-targets --all-features -- -D warnings` as the canonical static-analysis command.\n- `make catalog` — rebuilds `personas/catalog.json` to preview the published catalog locally.\n\n### Test coverage highlights\n\n- `crates/core/src/lib.rs` — YAML parsing, catalog generation, and URI resolution logic.\n- `crates/core/src/bin/generate_catalog.rs` — CLI validation of repository layout and catalog generation error handling.\n- `crates/core/src/bin/generate_persona_audit.rs` — persona audit generation, `--check` drift detection, and argument parsing.\n\nThe validation script checks that the published artifact keeps the shared documentation and catalog files in sync. It fails if `AGENTS.md`, the docs bundle (`docs/INSTRUCTIONS.md` and `docs/SPECIFICATION.md`), the catalog exports (`personas/catalog.json`, `personas.json`, `index.json`), the codex cleanup workflow (`workflows/codex-cleanup.yml`), or the bootstrap entry points (`scripts/BaseInitialization.sh`, `scripts/FullInitialization.sh`, `scripts/PretaskInitialization.sh`) are missing or empty.\n\nFor detailed schemas, examples, and API usage, always defer to `SPECIFICATION.md`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqqrm%2Fcodex-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqqrm%2Fcodex-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqqrm%2Fcodex-tools/lists"}