Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/untadotmy/codex_skills

Endless workflow for codex !
https://github.com/untadotmy/codex_skills

ai-agents code-review codex codex-cli developer-tools maintainer-tools openai workflow-automation

Last synced: about 1 month ago
JSON representation

Endless workflow for codex !

Awesome Lists containing this project

README 

          

[![Validate](https://github.com/UntaDotMy/codex_skills/actions/workflows/validate.yml/badge.svg)](https://github.com/UntaDotMy/codex_skills/actions/workflows/validate.yml)



# codex_skills



Native delivery rails for OpenAI Codex CLI.



Codex stays the runtime. This repo adds the repeatable parts around it: skills, workflow routing, review gates, memory, command-output compaction, and branch-closeout proof.



## Native Command Routing — Must Follow First



When a native `codex-skills` command owns the job, use it instead of recreating the behavior with raw shell, generic search, or ad hoc instructions.



**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 -- ` or the hook-provided `Rerun that as:` wrapper before noisy output is produced.



- **Noisy shell commands:** prefer `codex-skills run -- ` for test, build, lint, log, status, search, Docker, Kubernetes, Terraform, package-manager, and CI-style commands. Use `codex-skills rewrite ""` when unsure whether a command has native compaction.

- **Hook block-and-rerun:** if the managed `PreToolUse` hook returns `Rerun that as: `, 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.

- **Repository search:** prefer `codex-skills code-search search --workspace-root "$PWD" --query ""`. Use raw `rg`, `grep`, `find`, or `git grep` only after scoped search is insufficient, and pipe noisy raw search through `codex-skills run --`.

- **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//flow/flow-check.json` before patching.

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



For agent-facing usage in markdown or JSON, run `codex-skills hook instructions` (see also [`docs/hook-usage.md`](docs/hook-usage.md)).



## Hook Retry Handling



The managed hook may return a Codex denial whose reason begins with `Rerun that as:`. This is expected behavior, not a failure.



When that happens:

1. Copy the command after `Rerun that as:`.

2. Run it exactly once.

3. Preserve the resulting exit code and output.

4. Continue from the compacted output.

5. Do not ask the user for permission unless the suggested command itself is destructive or outside the requested task.



Example: 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.



## Start Here



| Need | Run | Why |

| --- | --- | --- |

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

| Check the install | `~/.codex/codex-skills status` or `%USERPROFILE%\.codex\codex-skills.exe status` | Confirms the managed Codex-home surface. |

| First guided run | `codex-skills workflow setup --request "Carry this task to closure"` | The named native operator path for onboarding. |

| Static guide | `codex-skills workflow first-run` | First Success Path guidance without starting state. |

| Start normal work | `codex-skills workflow start` | The lowest-friction first run. |

| See live state | `codex-skills workflow cockpit` | Shows stage, proof, blockers, and next command. |

| Close a branch | `codex-skills workflow finish` | The default closeout path. |



The default operator path is `workflow start -> workflow cockpit -> workflow finish`; the default closeout path is `codex-skills workflow finish`.



After install, the preferred global CLI path for agents on supported operating systems is:



- macOS or Linux: `~/.codex/codex-skills`

- Windows: `~/.codex/codex-skills.exe`



This 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 ` is an advanced override for CI, unusual layouts, or running the binary from a different folder than the extracted release/source checkout.



## Why Use It



Use `codex_skills` when the team needs delivery work to be easier to inspect and harder to fake as done.



| Surface | What it gives you |

| --- | --- |

| Workflow | Intake, routing, cockpit, hosted-check repair, and finish gates. |

| Review | Native `.codex-review.json`, local review gates, and CI-ready artifacts. |

| Memory | Working briefs, completion ledgers, scoped `SYSTEM_MAP.md`, and durable recovery state. |

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

| Profiles | 13 managed specialist profiles synced into `~/.codex/agent-profiles/*.toml`. |



## Quick Install



### Native Install (Recommended)



macOS or Linux:



```bash

curl -fsSL https://raw.githubusercontent.com/UntaDotMy/codex_skills/main/install.sh | bash

~/.codex/codex-skills status

```



Windows PowerShell:



```powershell

irm https://raw.githubusercontent.com/UntaDotMy/codex_skills/main/install.ps1 | iex

& "$env:USERPROFILE\.codex\codex-skills.exe" status

```



Windows CMD:



```bat

curl -fsSL https://raw.githubusercontent.com/UntaDotMy/codex_skills/main/install.cmd -o install.cmd && install.cmd && del install.cmd

%USERPROFILE%\.codex\codex-skills.exe status

```



The 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.



### Manual Release Install



Download 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___`. The release bundle includes the native binary plus the managed skill files, so Rust/Cargo is not required for normal install.



### Contributors: install from source



```bash

git clone https://github.com/UntaDotMy/codex_skills.git

cd codex_skills

cargo run --bin codex-skills -- install

cargo run --bin codex-skills -- status

```



Use `--repo-root ` only when you intentionally run `codex-skills install` from outside the extracted release folder or source checkout.



### Native Update



```bash

~/.codex/codex-skills update

~/.codex/codex-skills verify

~/.codex/codex-skills status

```



```powershell

& "$env:USERPROFILE\.codex\codex-skills.exe" update

& "$env:USERPROFILE\.codex\codex-skills.exe" verify

& "$env:USERPROFILE\.codex\codex-skills.exe" status

```



The 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.



## Find Fast



| Job | Commands |

| --- | --- |

| Route a broad request | `codex-skills workflow route --request "..."` |

| Start single-owner work | `codex-skills workflow start --preset autopilot --request "..."` |

| Start team work | `codex-skills workflow start --mode team --request "Coordinate the next multi-lane task"` |

| Watch live state | `codex-skills workflow cockpit`, `codex-skills workflow dashboard`, `codex-skills workflow watch` |

| Review locally | `codex-skills review pre-commit`, `codex-skills review pre-pr`, `codex-skills review gates check` |

| Finish a branch | `codex-skills workflow branch show`, `codex-skills workflow branch finish`, `gh pr checks --watch` |

| Compact noisy commands | `codex-skills rewrite "cargo test --workspace"`, `codex-skills run -- grep -RIn TODO rust` |

| Refresh memory map | `codex-skills memory scope resolve --create-missing --refresh-system-map` |

| Advanced help | `codex-skills help advanced` |



External 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.



See [Native Gap Map](docs/native-gap-map.md) for the anonymized comparison between external output reducers, runtime-shell peers, and the current native implementation.



Route, 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.



Start 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.



## Daily Paths



Quick labels: Feature work: Bug fixing: PR rescue: TDD-first implementation: Bounded parallel work:



### Feature work



```bash

codex-skills workflow route --request "Add the next feature and carry it to closure"

codex-skills workflow start --preset autopilot --workstream-key feature-branch --request "Add the next feature and carry it to closure"

codex-skills workflow cockpit --workstream-key feature-branch

codex-skills workflow finish --workstream-key feature-branch

```



### Bug fixing



```bash

codex-skills workflow route --request "Trace the regression, fix the root cause, and prove it"

codex-skills workflow start --preset debug --workstream-key bugfix-root-cause --request "Trace the regression, fix the root cause, and prove it"

codex-skills workflow branch hosted fix-loop --workstream-key bugfix-root-cause

codex-skills workflow finish --workstream-key bugfix-root-cause

```



### Review



```bash

codex-skills workflow route --request "Audit the current branch and call out the real gaps"

codex-skills workflow start --preset review --workstream-key review-branch --request "Audit the current branch and call out the real gaps"

codex-skills workflow audit --workstream-key review-branch

codex-skills workflow finish --workstream-key review-branch

```



### TDD-first implementation



```bash

codex-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"

codex-skills workflow cockpit --workstream-key tdd-feature

codex-skills workflow finish --workstream-key tdd-feature

```



### Common job shapes



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



### Native guidance tracks



Brainstorming:



```bash

codex-skills workflow guide

codex-skills workflow route --request "Brainstorm the approach, compare the options, and recommend the right next lane"

```



Plan writing:



```bash

codex-skills workflow route --request "Write the implementation plan, file targets, proof steps, and recovery path before coding"

```



Plan execution:



```bash

codex-skills workflow start --preset autopilot --request "Carry the approved plan to closure"

```



Systematic debugging:



```bash

codex-skills workflow start --preset debug --request "Trace the regression, find the root cause, and prove the real fix"

```



Code review:



```bash

codex-skills workflow start --preset review --request "Review the branch, call out the real gaps, and decide if it is ready"

```



Branch finish:



```bash

codex-skills workflow branch finish

```



### Native plan surface



Use exact file targets, verification steps, and recovery checkpoints before coding.



- File targets: list every expected write target before the first edit.

- Verification steps: name the narrow proving checks first.

- Recovery checkpoints: if interrupted, reopen the workstream with `workflow status`, `workflow cockpit`, and `workflow resume` before changing the plan.



### Native engineering principles



The guide now teaches TDD, YAGNI, and DRY as native workflow prompts and examples instead of pushing operators back to a standalone prompt library:



- TDD:

- YAGNI:

- DRY:

- TDD operator check: keep the native three-stage proof contract visible in `workflow cockpit` and `workflow finish` instead of relying on prose reminders.



### Workflow presets versus lower-level primitives



Keep 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.



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



The 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.



## Presets



Each 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.



| Preset | Use it for | Done means |

| --- | --- | --- |

| `autopilot` | Broad feature or maintenance work. | Working brief, completion gate, cockpit proof board, review pass, and native finish checks are current. |

| `debug` | Stateful bugs, failing checks, and root-cause repair. | Behavior mismatch, root cause, fix, and rerun proof are visible. |

| `tdd` | Test-first delivery. | Failing proof first, fix proof second, regression proof third. |

| `review` | Audit, production-readiness, and merge decisions. | Findings or approval are backed by current evidence. |

| `eco` | Bounded maintenance. | Narrowest honest proving validation passes. |

| `parallel` | Bounded multi-lane work. | Required lanes, proof board, and blockers are terminal. |



### Preset guide



`autopilot`: the default first-run preset.

When to use: broad feature or maintenance work where one owner should keep moving from alignment through closure.

Proof it expects: the working brief, completion gate, cockpit proof board, review pass, and native finish checks stay current before closeout.

If interrupted: reopen the workstream with `workflow status`, `workflow cockpit`, and `workflow resume`.



`debug`: the focused preset for stateful bugs.

`tdd`: the preset for test-first delivery.

Proof it expects: failing proof first, fix proof second, regression proof third, plus the normal review and finish checks.

`review`: the preset for audit, production-readiness, gap-finding, and final validation.

`eco`: the lighter preset for bounded maintenance.

`parallel`: the preset for bounded multi-lane work.

If interrupted: recover from `workflow cockpit`, `workflow team resume`, and `workflow team await`.



The lighter `autopilot` preset and `standard` tier power the default low-friction path.



## Proof Rules



The pack is strict on purpose:



- Work is not done just because implementation happened.

- Work is not done because one test passed or the first rerun turned green after a fix.

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

- The current job scope must be 100% complete for that scope.

- After a fix, rerun the narrow proving checks and re-audit the broader impacted system.

- Verify the relevant language, framework, runtime, and tooling release notes before non-trivial implementation.

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



## Native Review and CI



`.codex-review.json` is the tracked repo-level rule file.



- codex-skills review pre-commit is the local pre-commit surface.

- codex-skills review pre-pr is the local pre-PR surface.

- The cockpit proof view keeps a live proof board.



```bash

codex-skills review pre-commit --format compact

codex-skills review pre-pr --base-ref origin/main --format compact

codex-skills review gates check --surface pre-pr --base-ref origin/main --format compact

cargo test --workspace

```



For heavier Rust validation, run the release build after the workspace test proof.



```bash

cargo build --release --bin codex-skills

cargo fmt --all --check

```



```powershell

cargo build --release --bin codex-skills

cargo fmt --all --check

```



Hosted PR discipline:



1. Run local proof.

2. Push one cohesive feature branch.

3. Open the PR.

4. Wait at least 20 seconds for hosted checks to appear. In checklists this is written as: wait at least 20 seconds.

5. Watch `gh pr checks --watch`.

6. If a hosted lane fails, use `workflow branch hosted fix-loop` and fix the root cause on the same PR.



Run `codex-skills git-workflow preflight --repo-root . --base-ref origin/main` before push or merge-request creation.



The validate workflow is fail-closed: repo-wide Rust proof, native review artifacts, cross-platform manager loops, and the summary must pass.



## Command Output Compaction



Use 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.



```bash

codex-skills rewrite "cargo test --workspace"

codex-skills run -- cargo test --workspace

codex-skills run -- git status

codex-skills run -- grep -RIn TODO rust

codex-skills bench

```



What is implemented today:



- `run` executes the requested command, emits head/tail summaries for noisy or long output, and writes a raw-output recovery log.

- `run` prioritizes high-signal lines around errors, failures, warnings, panics, tracebacks, and assertion output before the compacted head/tail stream.

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

- `hook install` writes a documented global Codex `PreToolUse` hook entry that points at the Rust binary and returns block-and-rerun guidance.

- `hook instructions` prints the agent-facing rerun contract in markdown or JSON.

- `gain` reads native compaction events from the Codex home and reports observed commands, compacted commands, saved bytes, savings percentage, and top commands.

- The runtime never shells out to Go for compaction, hooks, or command dispatch.



### Hook path



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



```json

{

  "hooks": {

    "PreToolUse": [

      {

        "matcher": "Bash",

        "hooks": [

          {

            "type": "command",

            "command": "\"/path/to/codex-skills\" hook pre-tool-use",

            "statusMessage": "Checking native command compaction"

          }

        ]

      }

    ]

  }

}

```



The 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.



## Preserve Existing Flow Evidence



Existing 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.



```bash

codex-skills flow start --target-file rust/crates/codex-skills/src/commands.rs --target-function Application::run

codex-skills flow check

codex-skills flow finish

```



The default artifact is `~/.codex/memories/workspaces//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.



## Professional Text Templates



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



```bash

codex-skills git-workflow commit-message --from-diff --test-result "cargo test --workspace passed"

codex-skills git-workflow pr-body --from-diff --test-result "cargo test --workspace passed"

codex-skills git-workflow lint-message .git/COMMIT_EDITMSG

```



The linter rejects chatty language, escaped newline PR bodies, unrelated AI/Codex wording, unsupported hype wording, and first-person phrasing. `git-workflow preflight --message-file ` and `review pre-pr --pr-body ` use the same professional text rules.



## Memory and System Map



### Global project system map



Use the scoped memory path first so the user workspace stays clean:



```bash

codex-skills memory scope resolve --create-missing --refresh-system-map

codex-skills memory system-map refresh

```



The 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.



Useful memory commands:



```bash

codex-skills memory working-brief record-summary --workspace-root "$PWD" --workstream-key feature-branch --user-story "Ship the native workflow layer"

codex-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

codex-skills memory completion-gate check --workspace-root "$PWD" --workstream-key feature-branch --require-closure-ready

codex-skills memoriesv2 scope resolve --workspace-root "$PWD" --workstream-key feature-branch --create-missing

codex-skills memoriesv2 retrieve --workspace-root "$PWD" --workstream-key feature-branch --query "stable cache" --semantic-recall-mode blended

```



Advanced memory and search surfaces:



- codex-skills memoriesv2 retrieve now supports first-class entity recall plus graph-backed semantic recall modes: `direct`, `bridge`, and `blended`.

- codex-skills memoriesv2 entity upsert|list|query manages typed graph entities.

- codex-skills memoriesv2 hook capture records explicit save-loop or precompact-style events.

- Code-search demo details live at [./docs/code-search-demo-and-gap-map.md](./docs/code-search-demo-and-gap-map.md).



## Manager and Operator Surfaces



The interactive manager now keeps five clear choices:



- Doctor: run a report-first diagnostic pass that combines manager state with deep verification and recommends the next command to run.

- Install: sync the managed skill pack into `~/.codex`.

- Update: refresh an existing install from the current checkout or release source.

- Verify: prove managed artifact health.

- Uninstall: remove the managed pack safely.



Release download overrides are available for controlled environments:



- CODEX_NATIVE_CLI_RELEASE_METADATA_URL

- CODEX_NATIVE_CLI_RELEASE_BASE_URL



## Managed Agent Profiles



The managed install mirrors these 13 specialist lanes into `~/.codex/agent-profiles/*.toml`:



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



Routine work stays in the main lane. Specialist profiles are for the moments where domain ownership or independent verification is worth the extra context.



## Legacy Command Compatibility



The native CLI is the primary surface, but these older command shapes remain visible:



- `codex-skills memory working-brief save` still maps to `record-summary`.

- `codex-skills memory working-brief save --validation-plan ...` still maps to the native `--validation` field.

- `codex-skills memory completion-gate upsert` still maps to `record-requirement`.

- `codex-skills orchestration task begin|progress|complete --task ... --status ... --requirement ... --skill ...` still maps those legacy flags onto the native task fields.

- `codex-skills orchestration task complete --phase complete` still normalizes to the native reconcile closeout phase.



## Documentation Map



| Topic | Link |

| --- | --- |

| First Success Path | [./docs/first-success-path.md](./docs/first-success-path.md) |

| Workflow rules | [./WORKFLOW.md](./WORKFLOW.md) |

| Agent rules | [./AGENTS.md](./AGENTS.md) |

| Compatibility matrix | [./docs/compatibility-matrix.md](./docs/compatibility-matrix.md) |

| Why `codex_skills` over native Codex, runtime-shell comparator, and workflow-teaching comparator | [./docs/why-codex-skills.md](./docs/why-codex-skills.md) |

| Release notes | [./docs/release-notes.md](./docs/release-notes.md) |

| Release proof bundle | [./docs/release-proof-bundle.md](./docs/release-proof-bundle.md) |

| Audit bundle format | [./docs/audit-bundle-format.md](./docs/audit-bundle-format.md) |

| Security audit status | [./docs/security-audit-status.md](./docs/security-audit-status.md) |

| Benchmark suite | [./docs/benchmark-suite.md](./docs/benchmark-suite.md) |

| Shared benchmark harness | [./docs/shared-benchmark-harness.md](./docs/shared-benchmark-harness.md), the shared benchmark harness contract and common evidence format |

| Benchmark comparison scorecard | [./docs/benchmark-comparison-scorecard.md](./docs/benchmark-comparison-scorecard.md) |

| Memory recall benchmark bundle | [./docs/memory-recall-benchmark-bundle.md](./docs/memory-recall-benchmark-bundle.md) |

| 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) |

| Benchmark posture audit | [./docs/audits/2026-04-09-benchmark-posture/audit-summary.md](./docs/audits/2026-04-09-benchmark-posture/audit-summary.md) |

| 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) |

| Demo: PR-fix flow | [./docs/demo-pr-fix-flow.md](./docs/demo-pr-fix-flow.md) |

| Demo: branch-closeout flow | [./docs/demo-branch-closeout-flow.md](./docs/demo-branch-closeout-flow.md) |

| Runtime guardrails and memory protocols | [./docs/runtime-guardrails-and-memory-protocols.md](./docs/runtime-guardrails-and-memory-protocols.md) |

| Open-source memory patterns | [./docs/open-source-memory-patterns.md](./docs/open-source-memory-patterns.md) |

| Context efficiency playbook | [./docs/context-efficiency-playbook.md](./docs/context-efficiency-playbook.md) |



Public 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.



[./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.



The 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.



## Repository Layout



```text

codex_skills/

|- rust/crates/codex-skills     Native install, update, hook, review, flow, and compaction surfaces

|- rust/crates/codex-skills-*   Rust support crates for flow, platform, release assets, and text linting

|- .github/workflows/           native Rust CI and release pipelines

|- .codex-review.json           native review rules

|- AGENTS.md                    agent operating doctrine

|- WORKFLOW.md                  branch and completion rules

```



## Summary



Install `codex_skills` when Codex CLI needs a clearer path from request to proof:



- Start work with the workflow shell.

- Keep state in memory and cockpit surfaces.

- Compact noisy command output before it fills context.

- Prove the branch locally and on hosted checks.

- Finish only when the evidence says the scope is actually done.