{"id":47272984,"url":"https://github.com/untadotmy/codex_skills","last_synced_at":"2026-05-10T17:11:50.071Z","repository":{"id":343015701,"uuid":"1174966824","full_name":"UntaDotMy/codex_skills","owner":"UntaDotMy","description":"Endless workflow for codex !","archived":false,"fork":false,"pushed_at":"2026-05-02T15:19:44.000Z","size":2530,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-02T16:26:02.155Z","etag":null,"topics":["ai-agents","code-review","codex","codex-cli","developer-tools","maintainer-tools","openai","workflow-automation"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/UntaDotMy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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":"2026-03-07T03:43:33.000Z","updated_at":"2026-05-02T15:17:56.000Z","dependencies_parsed_at":null,"dependency_job_id":"612d6f58-92d5-43f0-87b6-41f2e3b18f89","html_url":"https://github.com/UntaDotMy/codex_skills","commit_stats":null,"previous_names":["untadotmy/codex_skills"],"tags_count":102,"template":false,"template_full_name":null,"purl":"pkg:github/UntaDotMy/codex_skills","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UntaDotMy%2Fcodex_skills","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UntaDotMy%2Fcodex_skills/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UntaDotMy%2Fcodex_skills/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UntaDotMy%2Fcodex_skills/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/UntaDotMy","download_url":"https://codeload.github.com/UntaDotMy/codex_skills/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UntaDotMy%2Fcodex_skills/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32542201,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T12:25:33.646Z","status":"ssl_error","status_checked_at":"2026-05-02T12:24:51.733Z","response_time":132,"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":["ai-agents","code-review","codex","codex-cli","developer-tools","maintainer-tools","openai","workflow-automation"],"created_at":"2026-03-15T14:31:01.241Z","updated_at":"2026-05-10T17:11:50.049Z","avatar_url":"https://github.com/UntaDotMy.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\nPurpose: Present the native codex_skills product surface, install paths, and proof-first workflow.\nCaller: Contributors, operators, and AI agents onboarding to the managed skill pack.\nDependencies: Native CLI commands, workflow docs, memory surfaces, review gates, and release artifacts.\nMain Functions: Explain what to run first, where to find each surface, and how closure proof works.\nSide Effects: Sets contributor and operator expectations for the repo-managed native experience.\n--\u003e\n[![Validate](https://github.com/UntaDotMy/codex_skills/actions/workflows/validate.yml/badge.svg)](https://github.com/UntaDotMy/codex_skills/actions/workflows/validate.yml)\n\n# codex_skills\n\nNative delivery rails for OpenAI Codex CLI.\n\nCodex stays the runtime. This repo adds the repeatable parts around it: skills, workflow routing, review gates, memory, command-output compaction, and branch-closeout proof.\n\n## Native Command Routing — Must Follow First\n\nWhen a native `codex-skills` command owns the job, use it instead of recreating the behavior with raw shell, generic search, or ad hoc instructions.\n\n**Token-saving rule:** the goal is to prevent noisy raw command output from entering Codex context. Do not run a raw noisy command first and compact afterward; route through `codex-skills run -- \u003ccommand\u003e` or the hook-provided `Rerun that as:` wrapper before noisy output is produced.\n\n- **Noisy shell commands:** prefer `codex-skills run -- \u003ccommand\u003e` for test, build, lint, log, status, search, Docker, Kubernetes, Terraform, package-manager, and CI-style commands. Use `codex-skills rewrite \"\u003ccommand\u003e\"` when unsure whether a command has native compaction.\n- **Hook block-and-rerun:** if the managed `PreToolUse` hook returns `Rerun that as: \u003ccommand\u003e`, immediately run that exact command. Do not ask the user, do not treat the hook block as a task failure, and do not repeat the raw command first.\n- **Repository search:** prefer `codex-skills code-search search --workspace-root \"$PWD\" --query \"\u003cquery\u003e\"`. Use raw `rg`, `grep`, `find`, or `git grep` only after scoped search is insufficient, and pipe noisy raw search through `codex-skills run --`.\n- **Existing-source edits:** run or validate Preserve Existing Flow evidence first. Use `codex-skills flow start`, `codex-skills flow check`, and `codex-skills flow finish`, and record the owner path in `~/.codex/memories/workspaces/\u003cworkspace-slug\u003e/flow/flow-check.json` before patching.\n- **Commit/PR/final response text:** use `codex-skills git-workflow commit-message --from-diff`, `codex-skills git-workflow pr-body --from-diff`, and `codex-skills git-workflow lint-message \u003cfile\u003e` against the templates in `templates/commit-body.md`, `templates/pr-body.md`, `templates/final-response.md`, and `templates/review-summary.md` before submitting. Run `codex-skills review pre-pr` and `codex-skills review gates check` before finalizing.\n\nFor agent-facing usage in markdown or JSON, run `codex-skills hook instructions` (see also [`docs/hook-usage.md`](docs/hook-usage.md)).\n\n## Hook Retry Handling\n\nThe managed hook may return a Codex denial whose reason begins with `Rerun that as:`. This is expected behavior, not a failure.\n\nWhen that happens:\n1. Copy the command after `Rerun that as:`.\n2. Run it exactly once.\n3. Preserve the resulting exit code and output.\n4. Continue from the compacted output.\n5. Do not ask the user for permission unless the suggested command itself is destructive or outside the requested task.\n\nExample: a raw `cargo test --workspace` may produce `Rerun that as: codex-skills run -- cargo test --workspace`; the correct next action is to run `codex-skills run -- cargo test --workspace` and continue from its compacted output.\n\n## Start Here\n\n| Need | Run | Why |\n| --- | --- | --- |\n| First install, no Rust required | Download a release, extract it, run `./codex-skills install` or `.\\codex-skills.exe install` | Installs the native binary and managed skills into Codex home. |\n| Check the install | `~/.codex/codex-skills status` or `%USERPROFILE%\\.codex\\codex-skills.exe status` | Confirms the managed Codex-home surface. |\n| First guided run | `codex-skills workflow setup --request \"Carry this task to closure\"` | The named native operator path for onboarding. |\n| Static guide | `codex-skills workflow first-run` | First Success Path guidance without starting state. |\n| Start normal work | `codex-skills workflow start` | The lowest-friction first run. |\n| See live state | `codex-skills workflow cockpit` | Shows stage, proof, blockers, and next command. |\n| Close a branch | `codex-skills workflow finish` | The default closeout path. |\n\nThe default operator path is `workflow start -\u003e workflow cockpit -\u003e workflow finish`; the default closeout path is `codex-skills workflow finish`.\n\nAfter install, the preferred global CLI path for agents on supported operating systems is:\n\n- macOS or Linux: `~/.codex/codex-skills`\n- Windows: `~/.codex/codex-skills.exe`\n\nThis matters because the install metadata remembers the source bundle or checkout so `status`, `update`, `verify`, `doctor`, and `menu` can still work when the installed binary is called from another project. For AI-agent or shell contexts where PATH resolution is not guaranteed, prefer the explicit installed path in the Codex home root. `--repo-root \u003cpath\u003e` is an advanced override for CI, unusual layouts, or running the binary from a different folder than the extracted release/source checkout.\n\n## Why Use It\n\nUse `codex_skills` when the team needs delivery work to be easier to inspect and harder to fake as done.\n\n| Surface | What it gives you |\n| --- | --- |\n| Workflow | Intake, routing, cockpit, hosted-check repair, and finish gates. |\n| Review | Native `.codex-review.json`, local review gates, and CI-ready artifacts. |\n| Memory | Working briefs, completion ledgers, scoped `SYSTEM_MAP.md`, and durable recovery state. |\n| Command compaction | Native benchmark-style output reduction through `codex-skills run --`: hook-integrated shell rewrite, semantic reducers, bounded streaming with `--stream`, raw recovery, and savings analytics without third-party runtime dependencies. |\n| Profiles | 13 managed specialist profiles synced into `~/.codex/agent-profiles/*.toml`. |\n\n## Quick Install\n\n### Native Install (Recommended)\n\nmacOS or Linux:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/UntaDotMy/codex_skills/main/install.sh | bash\n~/.codex/codex-skills status\n```\n\nWindows PowerShell:\n\n```powershell\nirm https://raw.githubusercontent.com/UntaDotMy/codex_skills/main/install.ps1 | iex\n\u0026 \"$env:USERPROFILE\\.codex\\codex-skills.exe\" status\n```\n\nWindows CMD:\n\n```bat\ncurl -fsSL https://raw.githubusercontent.com/UntaDotMy/codex_skills/main/install.cmd -o install.cmd \u0026\u0026 install.cmd \u0026\u0026 del install.cmd\n%USERPROFILE%\\.codex\\codex-skills.exe status\n```\n\nThe bootstrap installer detects your OS and architecture, downloads the matching GitHub release archive into a temporary directory, extracts it, runs `codex-skills install`, verifies `status`, and deletes the temporary files. Set `CODEX_SKILLS_VERSION=vX.Y.Z` to install a specific release instead of the latest release.\n\n### Manual Release Install\n\nDownload the archive for your OS from GitHub Releases, extract it, open a terminal in the extracted folder, then run `./codex-skills install` or `.\\codex-skills.exe install`. Archives are named like `codex-skills_\u003cversion\u003e_\u003cos\u003e_\u003carch\u003e`. The release bundle includes the native binary plus the managed skill files, so Rust/Cargo is not required for normal install.\n\n### Contributors: install from source\n\n```bash\ngit clone https://github.com/UntaDotMy/codex_skills.git\ncd codex_skills\ncargo run --bin codex-skills -- install\ncargo run --bin codex-skills -- status\n```\n\nUse `--repo-root \u003cpath\u003e` only when you intentionally run `codex-skills install` from outside the extracted release folder or source checkout.\n\n### Native Update\n\n```bash\n~/.codex/codex-skills update\n~/.codex/codex-skills verify\n~/.codex/codex-skills status\n```\n\n```powershell\n\u0026 \"$env:USERPROFILE\\.codex\\codex-skills.exe\" update\n\u0026 \"$env:USERPROFILE\\.codex\\codex-skills.exe\" verify\n\u0026 \"$env:USERPROFILE\\.codex\\codex-skills.exe\" status\n```\n\nThe Rust manager remembers the source checkout in install metadata, fast-forwards that checkout on `update`, rebuilds the native CLI when needed, delta-syncs changed files, removes stale managed files, and preserves unrelated Codex-home files. Shell and PowerShell wrapper launchers are no longer shipped.\n\n## Find Fast\n\n| Job | Commands |\n| --- | --- |\n| Route a broad request | `codex-skills workflow route --request \"...\"` |\n| Start single-owner work | `codex-skills workflow start --preset autopilot --request \"...\"` |\n| Start team work | `codex-skills workflow start --mode team --request \"Coordinate the next multi-lane task\"` |\n| Watch live state | `codex-skills workflow cockpit`, `codex-skills workflow dashboard`, `codex-skills workflow watch` |\n| Review locally | `codex-skills review pre-commit`, `codex-skills review pre-pr`, `codex-skills review gates check` |\n| Finish a branch | `codex-skills workflow branch show`, `codex-skills workflow branch finish`, `gh pr checks --watch` |\n| Compact noisy commands | `codex-skills rewrite \"cargo test --workspace\"`, `codex-skills run -- grep -RIn TODO rust` |\n| Refresh memory map | `codex-skills memory scope resolve --create-missing --refresh-system-map` |\n| Advanced help | `codex-skills help advanced` |\n\nExternal output-compaction tools are feature benchmarks for expected output reduction and recoverability, not runtime dependencies. The default path stays the native Rust implementation because it is integrated with Codex hooks, Preserve Existing Flow, review gates, install/update, repository instructions, raw-output recovery, and persisted `gain` analytics.\n\nSee [Native Gap Map](docs/native-gap-map.md) for the anonymized comparison between external output reducers, runtime-shell peers, and the current native implementation.\n\nRoute, start, watch, cockpit, and finish now share one operator-shell vocabulary: `stage`, `active_lane`, `proof_state`, `blocker`, `next_command`, and `recovery_path`. The workflow shell also keeps the active launch surface intact, so source-checkout runs use `cargo run --bin codex-skills -- ...` and installed runs keep using the installed executable.\n\nStart with the preset-driven native CLI when the operator wants a top-layer product surface: Use `workflow route`, `workflow start --preset ...`, `workflow cockpit`, and `workflow finish` for most delivery work.\n\n## Daily Paths\n\nQuick labels: Feature work: Bug fixing: PR rescue: TDD-first implementation: Bounded parallel work:\n\n### Feature work\n\n```bash\ncodex-skills workflow route --request \"Add the next feature and carry it to closure\"\ncodex-skills workflow start --preset autopilot --workstream-key feature-branch --request \"Add the next feature and carry it to closure\"\ncodex-skills workflow cockpit --workstream-key feature-branch\ncodex-skills workflow finish --workstream-key feature-branch\n```\n\n### Bug fixing\n\n```bash\ncodex-skills workflow route --request \"Trace the regression, fix the root cause, and prove it\"\ncodex-skills workflow start --preset debug --workstream-key bugfix-root-cause --request \"Trace the regression, fix the root cause, and prove it\"\ncodex-skills workflow branch hosted fix-loop --workstream-key bugfix-root-cause\ncodex-skills workflow finish --workstream-key bugfix-root-cause\n```\n\n### Review\n\n```bash\ncodex-skills workflow route --request \"Audit the current branch and call out the real gaps\"\ncodex-skills workflow start --preset review --workstream-key review-branch --request \"Audit the current branch and call out the real gaps\"\ncodex-skills workflow audit --workstream-key review-branch\ncodex-skills workflow finish --workstream-key review-branch\n```\n\n### TDD-first implementation\n\n```bash\ncodex-skills workflow start --preset tdd --workstream-key tdd-feature --request \"Write the failing test first, implement the smallest fix that makes it pass, and close with regression proof\"\ncodex-skills workflow cockpit --workstream-key tdd-feature\ncodex-skills workflow finish --workstream-key tdd-feature\n```\n\n### Common job shapes\n\nFeature work, Bug fixing, PR rescue, TDD-first implementation, and Bounded parallel work all use the same visible loop: route, start, cockpit, prove, finish. Branch finish uses `workflow branch finish`, and hosted failures go through `workflow branch hosted fix-loop`.\n\n### Native guidance tracks\n\nBrainstorming:\n\n```bash\ncodex-skills workflow guide\ncodex-skills workflow route --request \"Brainstorm the approach, compare the options, and recommend the right next lane\"\n```\n\nPlan writing:\n\n```bash\ncodex-skills workflow route --request \"Write the implementation plan, file targets, proof steps, and recovery path before coding\"\n```\n\nPlan execution:\n\n```bash\ncodex-skills workflow start --preset autopilot --request \"Carry the approved plan to closure\"\n```\n\nSystematic debugging:\n\n```bash\ncodex-skills workflow start --preset debug --request \"Trace the regression, find the root cause, and prove the real fix\"\n```\n\nCode review:\n\n```bash\ncodex-skills workflow start --preset review --request \"Review the branch, call out the real gaps, and decide if it is ready\"\n```\n\nBranch finish:\n\n```bash\ncodex-skills workflow branch finish\n```\n\n### Native plan surface\n\nUse exact file targets, verification steps, and recovery checkpoints before coding.\n\n- File targets: list every expected write target before the first edit.\n- Verification steps: name the narrow proving checks first.\n- Recovery checkpoints: if interrupted, reopen the workstream with `workflow status`, `workflow cockpit`, and `workflow resume` before changing the plan.\n\n### Native engineering principles\n\nThe guide now teaches TDD, YAGNI, and DRY as native workflow prompts and examples instead of pushing operators back to a standalone prompt library:\n\n- TDD:\n- YAGNI:\n- DRY:\n- TDD operator check: keep the native three-stage proof contract visible in `workflow cockpit` and `workflow finish` instead of relying on prose reminders.\n\n### Workflow presets versus lower-level primitives\n\nKeep the native CLI as the primary surface instead of drifting back toward a prompt-library-only identity. The router prints a short \"Start Now\" command first, keeps a scoped variant available for traceable workstreams, and cockpit shows route, active lanes, proof state, a live proof board, blockers, and the next command in one place. The branch path keeps proof-board gate status visible.\n\nUseful workflow command shelf: `codex-skills workflow lead start`, `codex-skills workflow team start`, `codex-skills workflow team resume`, `codex-skills workflow team await`, `codex-skills workflow team shutdown`, `codex-skills workflow finisher start`, `codex-skills workflow finisher resume`, `codex-skills workflow finisher await`, `codex-skills workflow finisher shutdown`, `codex-skills workflow status`, `codex-skills workflow audit`, `codex-skills workflow worktree start`, `codex-skills workflow worktree finish`, `codex-skills workflow worktree discard`, `codex-skills workflow tiers show`, and `codex-skills workflow hooks show`.\n\nThe dashboard includes a synthesized runtime-state summary and team-health summary so operators do not have to reconstruct that picture from raw memory artifacts. Cockpit surfaces the same runtime-state summary and team-health summary alongside the proof board, with a lighter day-to-day shell summary. Finish starts with a lighter closeout summary. `workflow finish` now leads with the next closeout command, and `workflow branch finish` can point straight at the merge command when the PR is already green.\n\n## Presets\n\nEach preset now says what it owns, what it does not own, and what done means at that stage, so the operator can see the boundary instead of inferring it.\n\n| Preset | Use it for | Done means |\n| --- | --- | --- |\n| `autopilot` | Broad feature or maintenance work. | Working brief, completion gate, cockpit proof board, review pass, and native finish checks are current. |\n| `debug` | Stateful bugs, failing checks, and root-cause repair. | Behavior mismatch, root cause, fix, and rerun proof are visible. |\n| `tdd` | Test-first delivery. | Failing proof first, fix proof second, regression proof third. |\n| `review` | Audit, production-readiness, and merge decisions. | Findings or approval are backed by current evidence. |\n| `eco` | Bounded maintenance. | Narrowest honest proving validation passes. |\n| `parallel` | Bounded multi-lane work. | Required lanes, proof board, and blockers are terminal. |\n\n### Preset guide\n\n`autopilot`: the default first-run preset.\nWhen to use: broad feature or maintenance work where one owner should keep moving from alignment through closure.\nProof it expects: the working brief, completion gate, cockpit proof board, review pass, and native finish checks stay current before closeout.\nIf interrupted: reopen the workstream with `workflow status`, `workflow cockpit`, and `workflow resume`.\n\n`debug`: the focused preset for stateful bugs.\n`tdd`: the preset for test-first delivery.\nProof it expects: failing proof first, fix proof second, regression proof third, plus the normal review and finish checks.\n`review`: the preset for audit, production-readiness, gap-finding, and final validation.\n`eco`: the lighter preset for bounded maintenance.\n`parallel`: the preset for bounded multi-lane work.\nIf interrupted: recover from `workflow cockpit`, `workflow team resume`, and `workflow team await`.\n\nThe lighter `autopilot` preset and `standard` tier power the default low-friction path.\n\n## Proof Rules\n\nThe pack is strict on purpose:\n\n- Work is not done just because implementation happened.\n- Work is not done because one test passed or the first rerun turned green after a fix.\n- Finished work must be re-audited against the user story, PRD or spec when one exists, explicit tasks, active plan items, tracked requirements, required lanes, and closure-ready evidence.\n- The current job scope must be 100% complete for that scope.\n- After a fix, rerun the narrow proving checks and re-audit the broader impacted system.\n- Verify the relevant language, framework, runtime, and tooling release notes before non-trivial implementation.\n- Use the right inspection tool: browser automation such as Playwright for web UI, live desktop runtime with screenshots or equivalent visual evidence for desktop UI, and runtime-native inspection for CLI, services, workflows, or devices.\n\n## Native Review and CI\n\n`.codex-review.json` is the tracked repo-level rule file.\n\n- codex-skills review pre-commit is the local pre-commit surface.\n- codex-skills review pre-pr is the local pre-PR surface.\n- The cockpit proof view keeps a live proof board.\n\n```bash\ncodex-skills review pre-commit --format compact\ncodex-skills review pre-pr --base-ref origin/main --format compact\ncodex-skills review gates check --surface pre-pr --base-ref origin/main --format compact\ncargo test --workspace\n```\n\nFor heavier Rust validation, run the release build after the workspace test proof.\n\n```bash\ncargo build --release --bin codex-skills\ncargo fmt --all --check\n```\n\n```powershell\ncargo build --release --bin codex-skills\ncargo fmt --all --check\n```\n\nHosted PR discipline:\n\n1. Run local proof.\n2. Push one cohesive feature branch.\n3. Open the PR.\n4. Wait at least 20 seconds for hosted checks to appear. In checklists this is written as: wait at least 20 seconds.\n5. Watch `gh pr checks --watch`.\n6. If a hosted lane fails, use `workflow branch hosted fix-loop` and fix the root cause on the same PR.\n\nRun `codex-skills git-workflow preflight --repo-root . --base-ref origin/main` before push or merge-request creation.\n\nThe validate workflow is fail-closed: repo-wide Rust proof, native review artifacts, cross-platform manager loops, and the summary must pass.\n\n## Command Output Compaction\n\nUse the Rust-native command wrapper before noisy shell commands when you want `codex-skills` to compact long output and record a raw-output recovery path instead of dumping everything directly into the agent transcript. The current Rust cut keeps command execution transparent, emits high-signal error/warning context plus head/tail summaries for noisy output, saves the full stdout/stderr log, and records native savings analytics without a Go fallback or third-party compaction runtime dependency.\n\n```bash\ncodex-skills rewrite \"cargo test --workspace\"\ncodex-skills run -- cargo test --workspace\ncodex-skills run -- git status\ncodex-skills run -- grep -RIn TODO rust\ncodex-skills bench\n```\n\nWhat is implemented today:\n\n- `run` executes the requested command, emits head/tail summaries for noisy or long output, and writes a raw-output recovery log.\n- `run` prioritizes high-signal lines around errors, failures, warnings, panics, tracebacks, and assertion output before the compacted head/tail stream.\n- `rewrite` returns the explicit current-executable `codex-skills run -- ...` wrapper for inspection or scripts and understands common shell wrappers, environment prefixes, and pipelines by routing them through `bash -lc`.\n- `hook install` writes a documented global Codex `PreToolUse` hook entry that points at the Rust binary and returns block-and-rerun guidance.\n- `hook instructions` prints the agent-facing rerun contract in markdown or JSON.\n- `gain` reads native compaction events from the Codex home and reports observed commands, compacted commands, saved bytes, savings percentage, and top commands.\n- The runtime never shells out to Go for compaction, hooks, or command dispatch.\n\n### Hook path\n\n`codex-skills hook install` writes the current Codex hook entry to the global user config path, `~/.codex/hooks.json`. The managed hook remains a `PreToolUse` hook with a `Bash` matcher because command-output wrapping is scoped to shell commands.\n\n```json\n{\n  \"hooks\": {\n    \"PreToolUse\": [\n      {\n        \"matcher\": \"Bash\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"\\\"/path/to/codex-skills\\\" hook pre-tool-use\",\n            \"statusMessage\": \"Checking native command compaction\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\nThe hook contract is explicit rerun guidance rather than hidden command mutation. The Rust hook installer manages every supported lifecycle event (`PreToolUse`, `PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`, `SessionStart`, `UserPromptSubmit`, and `Stop`). `PreToolUse` owns command compaction before noisy output exists; the other lifecycle hooks are native no-op/checkpoint surfaces reserved for memory and recovery wiring without shell-profile wrappers.\n\n## Preserve Existing Flow Evidence\n\nExisting source-file edits use a native preserve-flow gate before implementation. Docs-only, formatting-only, generated-only, and explicitly greenfield work are exempt; established source behavior needs owner-path evidence before review gates pass.\n\n```bash\ncodex-skills flow start --target-file rust/crates/codex-skills/src/commands.rs --target-function Application::run\ncodex-skills flow check\ncodex-skills flow finish\n```\n\nThe default artifact is `~/.codex/memories/workspaces/\u003cworkspace-slug\u003e/flow/flow-check.json`. It records the target file or function, current behavior to preserve, entry point, producer, source of truth, storage/state/queue owner, side-effect owner, consumers, cleanup/recovery path, edit boundary, validation needed, and validation evidence. The schema is documented in `docs/flow-check-schema.md`, and native review blocks existing source edits when that artifact is missing or incomplete.\n\n## Professional Text Templates\n\nCommit bodies, PR bodies, final responses, and review summaries should stay professional, concise, and scoped to the actual diff. Central templates live in `templates/commit-body.md`, `templates/pr-body.md`, `templates/final-response.md`, and `templates/review-summary.md`.\n\n```bash\ncodex-skills git-workflow commit-message --from-diff --test-result \"cargo test --workspace passed\"\ncodex-skills git-workflow pr-body --from-diff --test-result \"cargo test --workspace passed\"\ncodex-skills git-workflow lint-message .git/COMMIT_EDITMSG\n```\n\nThe linter rejects chatty language, escaped newline PR bodies, unrelated AI/Codex wording, unsupported hype wording, and first-person phrasing. `git-workflow preflight --message-file \u003cpath\u003e` and `review pre-pr --pr-body \u003ctext\u003e` use the same professional text rules.\n\n## Memory and System Map\n\n### Global project system map\n\nUse the scoped memory path first so the user workspace stays clean:\n\n```bash\ncodex-skills memory scope resolve --create-missing --refresh-system-map\ncodex-skills memory system-map refresh\n```\n\nThe project-scoped global `SYSTEM_MAP.md` target lives under Codex-managed memory, not inside the user repo. Use `codex-skills memory system-map refresh` when the map is missing, stale, or contradicted by current code. The generated map records visible top-level folders, files, direct child structure, applications, entrypoints, main flows, and key ownership hints. Use trace-by-function or trace-by-flow from the relevant entrypoint, mark unknown facts as `Not found`, respect generated artifact trees, handle a monorepo or multi-app workspace by app, and read the target file plus traced function or flow before editing. Modified files should keep file doc headers in the native comment style when the scoped rules require them.\n\nUseful memory commands:\n\n```bash\ncodex-skills memory working-brief record-summary --workspace-root \"$PWD\" --workstream-key feature-branch --user-story \"Ship the native workflow layer\"\ncodex-skills memory completion-gate record-requirement --workspace-root \"$PWD\" --workstream-key feature-branch --requirement-id workflow-primary --text \"Ship the native workflow layer\" --status in_progress\ncodex-skills memory completion-gate check --workspace-root \"$PWD\" --workstream-key feature-branch --require-closure-ready\ncodex-skills memoriesv2 scope resolve --workspace-root \"$PWD\" --workstream-key feature-branch --create-missing\ncodex-skills memoriesv2 retrieve --workspace-root \"$PWD\" --workstream-key feature-branch --query \"stable cache\" --semantic-recall-mode blended\n```\n\nAdvanced memory and search surfaces:\n\n- codex-skills memoriesv2 retrieve now supports first-class entity recall plus graph-backed semantic recall modes: `direct`, `bridge`, and `blended`.\n- codex-skills memoriesv2 entity upsert|list|query manages typed graph entities.\n- codex-skills memoriesv2 hook capture records explicit save-loop or precompact-style events.\n- Code-search demo details live at [./docs/code-search-demo-and-gap-map.md](./docs/code-search-demo-and-gap-map.md).\n\n## Manager and Operator Surfaces\n\nThe interactive manager now keeps five clear choices:\n\n- Doctor: run a report-first diagnostic pass that combines manager state with deep verification and recommends the next command to run.\n- Install: sync the managed skill pack into `~/.codex`.\n- Update: refresh an existing install from the current checkout or release source.\n- Verify: prove managed artifact health.\n- Uninstall: remove the managed pack safely.\n\nRelease download overrides are available for controlled environments:\n\n- CODEX_NATIVE_CLI_RELEASE_METADATA_URL\n- CODEX_NATIVE_CLI_RELEASE_BASE_URL\n\n## Managed Agent Profiles\n\nThe managed install mirrors these 13 specialist lanes into `~/.codex/agent-profiles/*.toml`:\n\n`backend-and-data-architecture`, `cloud-and-devops-expert`, `git-expert`, `memory-status-reporter`, `mobile-development-life-cycle`, `preserve-existing-flow`, `qa-and-automation-engineer`, `reviewer`, `security-and-compliance-auditor`, `software-development-life-cycle`, `ui-design-systems-and-responsive-interfaces`, `ux-research-and-experience-strategy`, and `web-development-life-cycle`.\n\nRoutine work stays in the main lane. Specialist profiles are for the moments where domain ownership or independent verification is worth the extra context.\n\n## Legacy Command Compatibility\n\nThe native CLI is the primary surface, but these older command shapes remain visible:\n\n- `codex-skills memory working-brief save` still maps to `record-summary`.\n- `codex-skills memory working-brief save --validation-plan ...` still maps to the native `--validation` field.\n- `codex-skills memory completion-gate upsert` still maps to `record-requirement`.\n- `codex-skills orchestration task begin|progress|complete --task ... --status ... --requirement ... --skill ...` still maps those legacy flags onto the native task fields.\n- `codex-skills orchestration task complete --phase complete` still normalizes to the native reconcile closeout phase.\n\n## Documentation Map\n\n| Topic | Link |\n| --- | --- |\n| First Success Path | [./docs/first-success-path.md](./docs/first-success-path.md) |\n| Workflow rules | [./WORKFLOW.md](./WORKFLOW.md) |\n| Agent rules | [./AGENTS.md](./AGENTS.md) |\n| Compatibility matrix | [./docs/compatibility-matrix.md](./docs/compatibility-matrix.md) |\n| Why `codex_skills` over native Codex, runtime-shell comparator, and workflow-teaching comparator | [./docs/why-codex-skills.md](./docs/why-codex-skills.md) |\n| Release notes | [./docs/release-notes.md](./docs/release-notes.md) |\n| Release proof bundle | [./docs/release-proof-bundle.md](./docs/release-proof-bundle.md) |\n| Audit bundle format | [./docs/audit-bundle-format.md](./docs/audit-bundle-format.md) |\n| Security audit status | [./docs/security-audit-status.md](./docs/security-audit-status.md) |\n| Benchmark suite | [./docs/benchmark-suite.md](./docs/benchmark-suite.md) |\n| Shared benchmark harness | [./docs/shared-benchmark-harness.md](./docs/shared-benchmark-harness.md), the shared benchmark harness contract and common evidence format |\n| Benchmark comparison scorecard | [./docs/benchmark-comparison-scorecard.md](./docs/benchmark-comparison-scorecard.md) |\n| Memory recall benchmark bundle | [./docs/memory-recall-benchmark-bundle.md](./docs/memory-recall-benchmark-bundle.md) |\n| Memory recall audit | [./docs/audits/2026-04-11-memory-recall-benchmark/audit-summary.md](./docs/audits/2026-04-11-memory-recall-benchmark/audit-summary.md) |\n| Benchmark posture audit | [./docs/audits/2026-04-09-benchmark-posture/audit-summary.md](./docs/audits/2026-04-09-benchmark-posture/audit-summary.md) |\n| Competitive apples-to-apples audit | [./docs/audits/2026-04-09-competitive-apples-to-apples/audit-summary.md](./docs/audits/2026-04-09-competitive-apples-to-apples/audit-summary.md) |\n| Demo: PR-fix flow | [./docs/demo-pr-fix-flow.md](./docs/demo-pr-fix-flow.md) |\n| Demo: branch-closeout flow | [./docs/demo-branch-closeout-flow.md](./docs/demo-branch-closeout-flow.md) |\n| Runtime guardrails and memory protocols | [./docs/runtime-guardrails-and-memory-protocols.md](./docs/runtime-guardrails-and-memory-protocols.md) |\n| Open-source memory patterns | [./docs/open-source-memory-patterns.md](./docs/open-source-memory-patterns.md) |\n| Context efficiency playbook | [./docs/context-efficiency-playbook.md](./docs/context-efficiency-playbook.md) |\n\nPublic claims stay source-backed. A durable audit artifact required before numeric security or governance claims are upgraded, and [./docs/security-audit-status.md](./docs/security-audit-status.md) defines the boundary between published artifacts and unproven claims. [./docs/release-proof-bundle.md](./docs/release-proof-bundle.md) is the durable proof artifact published with notable releases.\n\n[./docs/audits/2026-04-09-competitive-apples-to-apples/audit-summary.md](./docs/audits/2026-04-09-competitive-apples-to-apples/audit-summary.md) is the current published source-backed competitive audit bundle for workflow, memory, and indexing peers.\n\nThe benchmark docs track real scenario evidence across 8 flows, including greenfield delivery, stateful fixes, hosted rescue, branch closeout, closure proof, Windows validation, docs governance, and regression hardening.\n\n## Repository Layout\n\n```text\ncodex_skills/\n|- rust/crates/codex-skills     Native install, update, hook, review, flow, and compaction surfaces\n|- rust/crates/codex-skills-*   Rust support crates for flow, platform, release assets, and text linting\n|- .github/workflows/           native Rust CI and release pipelines\n|- .codex-review.json           native review rules\n|- AGENTS.md                    agent operating doctrine\n|- WORKFLOW.md                  branch and completion rules\n```\n\n## Summary\n\nInstall `codex_skills` when Codex CLI needs a clearer path from request to proof:\n\n- Start work with the workflow shell.\n- Keep state in memory and cockpit surfaces.\n- Compact noisy command output before it fills context.\n- Prove the branch locally and on hosted checks.\n- Finish only when the evidence says the scope is actually done.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funtadotmy%2Fcodex_skills","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funtadotmy%2Fcodex_skills","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funtadotmy%2Fcodex_skills/lists"}