Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CODEX-INSTALL-PROMPT.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ Review the changes in `~/.codex/AGENTS.md`, `~/.codex/PLANS.md`, and `~/.codex/c

Confirm that these skills are installed: `delivery-lifecycle`, `neuroarxiv`, `plan-history`, `publication`, `repository-knowledge`, `roadmap-maintainer`, and `toolkit-maintainer`. Confirm that `codex-practical-kit-rules` and `task-brief` are absent. Confirm that the RepoWise MCP table has `default_tools_approval_mode = "approve"`, `required = true`, and `startup_timeout_sec = 1800`.

Verify that Node.js and native Codex plugin commands work before changing an existing installation. Install the official `ponytail@ponytail` plugin only when absent. Preserve its existing version, settings, and enabled or disabled state. Use the selected Codex home for native commands. Reject a conflicting marketplace source or unowned standalone Ponytail skill. Remove the old copied skill only when the toolkit manifest owns it and native installation succeeds. Confirm that the plugin provides all six Ponytail skills and its lifecycle hooks. Do not change Ponytail modes. Explain the Codex `@ponytail` skill controls and link to README's complete-removal steps.
Verify that Node.js and native Codex plugin commands work before you change an existing installation. Install `ponytail@ponytail` only when absent. Preserve its existing version, configuration, and enabled state. Use the selected Codex home for native commands. Reject a conflicting marketplace source or unowned standalone Ponytail skill. Remove the old copied skill only when the toolkit manifest owns it and native installation succeeds. Make sure that Ponytail provides all six skills and its lifecycle hooks. Do not change Ponytail modes. Do not install or refresh the `just-every/12ui-plugin` Git package. Preserve separately installed 12UI plugins. Use 12UI only for website projects. Explain the Codex `@ponytail` skill controls and link to the complete-removal steps in README.

Do not trust toolkit or Ponytail hooks on my behalf. Tell me to open `/hooks` in a new Codex session. If version 0.2.0 was active, do not resume that old session. That session can retain the stale continuation that version 0.2.1 corrected.

Expand Down
33 changes: 22 additions & 11 deletions MANIFEST.sha256
Original file line number Diff line number Diff line change
Expand Up @@ -20,12 +20,14 @@ a4d0bc13747cf250f25fb599b37f90cf519c95a29382f4da544afe9ff8095372 ./.agent/plan-
d60f352d0db1404c70afb4bb8b2ca3fd1c610572aa40720e8a0b7baa7885418c ./.gitattributes
13d683d7a117f01846724725f15a844768d16f52d226ec6d3f76143b1fc3f6f8 ./.github/workflows/ci.yml
15cefba6945d22a52b5b8ef6dd656fffcb698627b9fb23dacc5c8ec27ad1680d ./.gitignore
6d7a25701ba2532525fe556f1a55529ab09af6675522f749afb22609f7f8183e ./CODEX-INSTALL-PROMPT.md
289d0dd251ded6c2e7df393a3a08433878a2ddf94514db47ad545c239a28e110 ./CODEX-INSTALL-PROMPT.md
6612129aca01053f15098204fb4bbaafdf85a667956202530bdcbc339e58e462 ./LICENSE
e4912f4f8d644555dcd57d5e336a249cf8a9d7f6222b78096d6b403f45a8a215 ./PLAYGROUND.md
964bddcb73a1cd9492eaf0340987a5f33aa57cad53f4ca62e4c73e984f82fa3f ./README.md
979191eeef7975567b4c44c9fb6dc38bf78e431eda582ff55d4f37eb2f69a441 ./THIRD_PARTY.md
59b191889c8b7d098ddaf6b029f6f12b3ce6590893e1823f4448ad3b90c03fb4 ./assets/AGENTS.block.md
3fdaf82fc173bdf11c9a6b437974750231bae94a383cb2adc13df1056d159625 ./README.md
a2802fdddcfb519f086723b9edf8835cafb38303b8af5dbd8dbbf85fb281029c ./THIRD_PARTY.md
3d652285f38f181fa273e1fc993b08dafa2fc3113c2109ccbdabf1a0c7fec573 ./apply-updates.ps1
74d504bff9dc0b10f116f6b83a452a1c757ca7ad7c65797c7439e928bfbbe45e ./apply-updates.sh
d0ab843abb452ecba5386cbc56659aac83400cd4c5fb086db501e232f2e4d0a9 ./assets/AGENTS.block.md
b9f9eb58967f54b19fb3a58b1db32e4c25299ae10c06e2e45a6611c250801a71 ./assets/hooks/session_start.py
3027ffa3ef382dcd0c96f6280ba861bb4a9410011e1176d71d7aa7911805821f ./assets/runtime/repowise_bootstrap.py
a564a3b00a86f43d38318b76168593bc965b2f1decf67a328d499a054aa35f36 ./assets/skills/adversarial-review/SKILL.md
Expand All @@ -38,7 +40,7 @@ a564a3b00a86f43d38318b76168593bc965b2f1decf67a328d499a054aa35f36 ./assets/skill
baa988b652f856bce1a4e183bf327879a021896eb65617b2fd4903e34a461339 ./assets/skills/defect-diagnostic/agents/openai.yaml
f98f3661b7b4cfbe6a1b061e075898ae21b65cbb6765abec76b332b03cab2f9b ./assets/skills/defect-diagnostic/references/diagnostic-summary.md
20fb4b743b3ed14fa58ae1710bf5c621eb1f0b20dad552212221594368fa2d4c ./assets/skills/delivery-lifecycle/SKILL.md
9320e46907d34dd905159c75abba4b37bd7ce990f30a023d6b80c4715d6a0196 ./assets/skills/delivery-lifecycle/references/coordination.md
2995e2472f94e403ab399be52c0497dd591346bb4edcf86b055768551e33fefc ./assets/skills/delivery-lifecycle/references/coordination.md
b24f6d4c5d6ba9d3a4ab4215eac302764e8dcb0fe2c6dc76789b3ffe77a8e21f ./assets/skills/delivery-lifecycle/references/decision-handoffs.md
d9d882f331eaed467f783b899073d992b9f9872927f76ce8c7a2069295a8a080 ./assets/skills/delivery-lifecycle/references/delivery-lifecycle.md
2536a374b63658e5e0bbca17d1a9ed25a41b61eeb539702cc8ee7c6f41bf1a31 ./assets/skills/delivery-lifecycle/references/git-isolation.md
Expand All @@ -63,11 +65,13 @@ b87078d33fa47da8a2f60b1b5155671f593b7dcf198e50e307c788bd42bc154c ./assets/skill
c5465d35f51779e1b75da0d96bdb75e792fbe0a2691685f4c5e54140f1ed7388 ./assets/skills/roadmap-maintainer/SKILL.md
a8a3764af5e50240c687019e5bf56d927728a0e802ab4ce2168d3816e2b69cbd ./assets/skills/roadmap-maintainer/assets/roadmap-template.md
afe980a9557961e9fa13d65fa066c62d50b87523234a4f88886ae494a1e302be ./assets/skills/toolkit-maintainer/SKILL.md
4bd91aa5c60f699f19c0e5e049b3fcf01a419baaf161202bb1bf67620240be14 ./check-updates.ps1
b97c626ce8e220598d12f7bd0cce5099d331aae71a45f692a9eb57d669d0c038 ./check-updates.sh
913770b6e8fa270a4f8927ce9840c877366eb6a06a76a4fac47b3c773b9bcf4c ./docs/HOTFIX-0.2.1.md
78823831a732ebf870c45b9acc92abddfdddbdbb47db6db81a38ada0497de00f ./docs/OPERATING-MANUAL.md
97dd789229fa55905bd20290c2767ef7bd274cc81965a6f4eb1136dda9ed0adb ./docs/OPTIONAL-REVIEW-TOOLS.md
9bee78762d4d1f446cfb816878e36671cdd823ab62521d32833cc915a572796e ./docs/REMOVE-CBM.md
208aeeb48807fd9a4d44ea7a5960e88f4a41d77ba2ac6351ad410b80f319233a ./docs/REPOWISE.md
d69f7436f838d6daa56b7a311cfdbe7f77fbbf1b9c6c2835a813709e75187416 ./docs/REPOWISE.md
e27b3d72ff47ebf7230a96b3a5f2d6ea3f410e22ef382f8e7d9cd27c7bb59892 ./docs/REVIEW.md
e86355a4eae8ec5cd42e7674461ebaf1acc4f14f20fa9600da2bb5248efb8e43 ./docs/SPEC-KIT.md
f7298a2735489830b11a83c5a852984916147e8c3408214cc722d58a4f7a139f ./docs/WHY-THIS-SHAPE.md
Expand Down Expand Up @@ -125,12 +129,17 @@ a5d8013da3d22afba28c1259e29e3255d1d19969d0934b2f59069f0de80ea31b ./docs/plans/c
5f2abf3bc85fbfc580d05139165ff95f29a3a85246bab2724c5f949eb93f26a5 ./docs/plans/cpk-058-plan-history-compaction.md
43141b61bf800dc9956603b6e88cdd0c3a5564340d3f4aee3fb6b0682dceee00 ./docs/plans/cpk-059-public-pr-release.md
8cea5185f3a1181dc9a1419f3f980712b2b9e35936ec2a8011629d67cd0d041f ./docs/plans/cpk-060-windows-codex-resolution.md
23106fd9f30090fc85692c14612b95f69be5b8d2757137a3df19ed6093d2af0b ./docs/roadmap.md
ccc9e20f5cd288592bde3dc81fd49820e9f7d62ef2274a99af8ac9781d5d3f5c ./docs/plans/cpk-061-component-updates-agent-cleanup.md
487d05e84cc1c1849f7dff4fc08eac2adad08af9dab8091b60bac48c8ad085c4 ./docs/plans/cpk-062-managed-update-application-12ui.md
471a4a4af80c1f234983f629dc007708f94fde7868952f15004be57a5176eb82 ./docs/plans/cpk-063-12ui-codex-compatibility.md
92f55f0ad064584f3aba2b4231d8172a318999a314923028281063887157f8cf ./docs/plans/cpk-064-publish-managed-updates.md
1c2e4ea4987be8065f417c1bd8296dd6db50cb2e63760dd1f6a952573f18e6b4 ./docs/plans/cpk-065-restore-thread-archival.md
5907afa0a540861224ec35d1742854ad42af8985598930d53a7affc4b5774f15 ./docs/roadmap.md
6f8f14ca5fd8ad935eee66256b3f7c49d5c40957eedff938ba21365e30869719 ./doctor.ps1
ab56a88d9188979f06ea142d1f58ea0d6ad9088e83a965bd324209d83da513ad ./doctor.sh
8087bdb3ee654c0baac278a8e3bf85e33e314f8acfd486e7ebf675126a697058 ./install.ps1
3466d2e34145cfdaa83d793960794b2aefc96f3d9c48d22fd2af930ec819e9c4 ./install.sh
7c4238f798f567de9b7de28268b5fd344a861ce8fff1d16da7f2e2966908f8f5 ./kit.py
fd117b24c3810c2078a610c9a97034d711b0bf2551e7ff832b5fce62f51c94c2 ./kit.py
331f17ca1486b5779d9b57a3a73834328eb3089ce612e636e6a8e5085899d61e ./run-tests.ps1
e6df9f1da02280a66161583529b06a34f0103041e9587afad0fac6074eecc15b ./run-tests.sh
85a2ba72e2b0cd1ab6c25a51f39059502415c3ac62a6bffa613d7e31b6422cd4 ./setup-repo.ps1
Expand All @@ -141,8 +150,10 @@ e1e231aac51822f7e1bb3aa61aba138cf8c5df9cefd3079b0c1b5a98eea03bd9 ./tests/fixtur
a269775204ae7cad2457d00f5565c90da2df41a9719479f3489ec01afdd2519c ./tests/fixtures/cpk056-agent-cases.json
e32941eb74be1f2cdcb6c82cf71e113b841651bf0d01786f364176de2da1b9c5 ./tests/fixtures/cpk056-agent-grading.json
289367b7090a0d71936b41f08c4a354bc2758013dceb709819de36a1b73d9aa6 ./tests/live_plan_history.py
9b6d3048643461026467186632f3de49fbc533aaa8a91de46b699c67cfe7bad3 ./tests/test_kit.py
1979109d44a6b49c01747216c99dc6598e5cc725b986df4eea60215e4598f4d8 ./tests/test_ponytail.py
2424e4d7cbf073c2b7da64f4e455b375ebd4f2c99be1df9a37aedd07e8e8676d ./tests/test_kit.py
dbeb390655fbe5321578256db17b6a7c9edc1a4a7e7499ff5fe524dccbfc1719 ./tests/test_ponytail.py
8fb5aefac7fa8a9cef45296f2dacbcc0663bed19a0daee5d94f71cebce15b012 ./tests/test_updates.py
54673ace20ec6333c73ead405c82d52560848bc8b9aa3a0102fc39935cc3ab87 ./tests/update_subprocess_fixture.py
d16f7eadc8c668e82a1d0d2554ed04def15cb0a4b2ce13ac1ce1339bc0e62161 ./uninstall.ps1
f12cff94ef7f9b0ca489cbe43e1de737011476966e04c1578f4977177b0da217 ./uninstall.sh
e96e2cd99b37377ca84d420d142d097981f303f5006d930880352ad9404d3b13 ./upstream.lock.json
c7dfb29d1712e1617306f327bdc4d66d4aecfce048def64382c797290e242631 ./upstream.lock.json
69 changes: 63 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ The managed `AGENTS.md` is a small skill router. Skill descriptions keep unrelat

## Included components

The kit installs the official Ponytail plugin and these task skills:
The kit installs the official Ponytail plugin. It also installs these task skills:

- `simple-english`
- `neuroarxiv`
Expand Down Expand Up @@ -44,12 +44,50 @@ pwsh -File .\install.ps1
pwsh -File .\doctor.ps1
```

The installer copies managed skills to `~/.agents/skills/`. Do not edit installed copies. Codex manages Ponytail separately as a native plugin.
The installer copies managed skills to `~/.agents/skills/`. Do not edit installed copies. Codex manages Ponytail as a native plugin.

The installer writes a managed block in `~/.codex/AGENTS.md`. It renders the absolute PLANS path and names installed skills.

The installer also writes `$CODEX_HOME/PLANS.md` and managed Codex hooks. Session Start announces the AGENTS router.

## Check and apply managed component updates

On macOS or Linux, run this read-only command from the source checkout:

```bash
./check-updates.sh
```

On Windows, run:

```powershell
pwsh -File .\check-updates.ps1
```

The command reads authoritative upstream sources for all managed runtime tools and bundled skills. It excludes optional tools and does not change installations, plugins, pins, or configuration.

The report compares toolkit pins with upstream identities. Native plugins have no toolkit pin. The report identifies their upstream release and Codex-owned lifecycle.

A complete report returns status 0, including when upstream differs. A request error returns status 2 and prints no partial report.

To apply all managed updates on macOS or Linux, run:

```bash
./apply-updates.sh
```

On Windows, run:

```powershell
pwsh -File .\apply-updates.ps1
```

The apply command updates `upstream.lock.json` and the selected toolkit installation. It also refreshes each installed managed plugin by its marketplace name.

The command refuses an untracked source lock or an independent source edit. A prior successful apply remains valid when its source lock matches the selected installation. The command validates upstream data before mutation. It writes the source lock only after installation succeeds.

If an operation fails, the command stops and returns status 2. Correct the reported cause, then run the command again.

## Global and repository instructions

The installer manages `~/.codex/AGENTS.md` and `$CODEX_HOME/PLANS.md`. These files apply to every repository unless a nearer repository file overrides them.
Expand All @@ -76,7 +114,7 @@ For large histories, agents create reusable reading summaries under `.agent/plan

An unrecorded destination skill is a conflict. The installer stops before it changes that directory.

Open a new Codex session after installation. Use `/hooks` to review and trust the toolkit and Ponytail commands.
Open a new Codex session after installation. Use `/hooks` to review and trust the toolkit and plugin commands.

## Ponytail

Expand All @@ -101,12 +139,31 @@ Bare `@ponytail` reports the mode. `@ponytail default off` changes the default f

The upstream Codex instructions use `@` commands; they do not promise a `/ponytail` slash-menu entry. See the [official Ponytail commands](https://github.com/DietrichGebert/ponytail#commands).

Use Codex's plugin manager for updates, enablement, and removal. Toolkit reinstall does not update or re-enable Ponytail.
Use Codex's plugin manager for enablement and removal. The apply command refreshes Ponytail but does not re-enable it.

Migration removes an old standalone Ponytail skill only when the toolkit manifest owns its destination and native installation succeeds. An unowned skill or conflicting marketplace source stops installation. Resolve that ownership conflict before retrying.

`--codex-home` selects the Codex home for installation and Doctor. Otherwise, the toolkit uses `CODEX_HOME` or `~/.codex`. Use the same home for native plugin commands.

## 12UI

Install a compatible 12UI plugin through the Codex plugin directory if you want to use it. The toolkit does not install, update, or require 12UI.

The toolkit uses 12UI only for website projects. It does not use 12UI for native applications or other user-interface work.

The toolkit preserves separately installed 12UI plugins and does not copy or edit their skills.

The `just-every/12ui-plugin` Git package at version `0.2.108` includes a Claude Code pane. Its hook configuration contains `modules`, which Codex `0.160.0` rejects.

If an older toolkit installed that package, remove it and its marketplace registration:

```text
codex plugin remove 12ui-design@12ui-plugin
codex plugin marketplace remove 12ui-plugin
```

These commands leave a separately installed `12ui-design@openai-curated-remote` plugin intact. Later toolkit install and apply commands do not restore the Git package.

## Rule owners

An applicable skill selects only the rules needed for its task:
Expand Down Expand Up @@ -157,7 +214,7 @@ See [RepoWise notes](docs/REPOWISE.md) for setup, refresh, opt-out, and trust-bo

## Uninstall

Uninstall removes toolkit-managed global integrations and copied skills. `--purge` also removes the toolkit data directory. Both retain native Ponytail resources, settings, uv, RepoWise, and Plan history.
Uninstall removes toolkit-managed global integrations and copied skills. `--purge` also removes the toolkit data directory. Both retain native plugin resources, uv, RepoWise, and Plan history.

For complete removal, follow the ordered steps below. Keep the source checkout until the removal commands finish.

Expand Down Expand Up @@ -278,7 +335,7 @@ On macOS or Linux, run:

```bash
./run-tests.sh
sh -n doctor.sh install.sh run-tests.sh setup-repo.sh uninstall.sh
sh -n apply-updates.sh check-updates.sh doctor.sh install.sh run-tests.sh setup-repo.sh uninstall.sh
git diff --check
sha256sum --check MANIFEST.sha256
```
Expand Down
17 changes: 11 additions & 6 deletions THIRD_PARTY.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,36 +13,41 @@
### SimpleEnglish

- Source: https://github.com/AminBlg/SimpleEnglish
- Pinned commit: `59bf6702197a5aadc96d197ea17f290d8d50dcd3`
- Installed files: the Simple English skill, its two reference files, and `LICENSE`
- Pinned commit and installed files: see `skills.simple-english` in `upstream.lock.json`
- License: MIT

### NeuroArxiv

- Source: https://github.com/UditAkhourii/neuroarxiv
- Pinned commit: `b5d20efa12dd1ba177ce890d56809d2e027f8055`
- Pinned commit: see `skills.neuroarxiv` in `upstream.lock.json`
- Installed files: `skills/neuroarxiv/SKILL.md`, `LICENSE`
- License: MIT
- Integration: required prior-art workflow for qualifying open technical mechanisms

### RepoWise

- Source: https://github.com/repowise-dev/repowise
- Pinned runtime version: `0.45.0`
- Pinned runtime version: see `runtime_tools.repowise` in `upstream.lock.json`
- License: AGPL-3.0-or-later
- Integration: persistent uv tool, MCP server, and marker-delimited Git hook
- RepoWise is not copied into or linked with this kit.

### uv

- Source: https://github.com/astral-sh/uv
- Pinned installer version: `0.12.4`
- Installer SHA-256: `f1ee4a249799525a330df57643335120150c9102db7483b1d37546cc43af3a16`
- Pinned installer version and platform SHA-256 values: see `runtime_tools.uv` in `upstream.lock.json`
- License: Apache-2.0 OR MIT
- Integration: checksum-verified upstream installer when `uv` is absent

## Optional components

### 12UI

- Installation and updates: Codex plugin directory, outside toolkit management
- Use: website projects only
- Compatibility: the toolkit does not install the `just-every/12ui-plugin` Git package because version `0.2.108` includes unsupported Claude Code hooks
- Existing plugins: retained without changes

### OpenAI ExecPlan guidance

- Source: https://developers.openai.com/cookbook/articles/codex_exec_plans/
Expand Down
3 changes: 3 additions & 0 deletions apply-updates.ps1
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
#Requires -Version 7.0
& python (Join-Path $PSScriptRoot "kit.py") apply-updates @args
exit $LASTEXITCODE
4 changes: 4 additions & 0 deletions apply-updates.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
#!/usr/bin/env sh
set -eu
HERE=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
exec python3 "$HERE/kit.py" apply-updates "$@"
2 changes: 2 additions & 0 deletions assets/AGENTS.block.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
<!-- cpk-rule-owner: routing -->
<!-- cpk-rule-guard: Use only the skills that match the current task. -->
<!-- cpk-rule-guard: Use 12ui-design only for website projects. -->

## Codex Practical Kit

Expand All @@ -19,3 +20,4 @@ Use only the skills that match the current task. Follow the focused references s
- Severe defect analysis: `defect-diagnostic`.
- Publication or version selection: `publication`.
- Toolkit rule changes: `toolkit-maintainer`.
- Use 12ui-design only for website projects. Do not use it for native apps or other UI work.
8 changes: 7 additions & 1 deletion assets/skills/delivery-lifecycle/references/coordination.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@
<!-- cpk-rule-guard: User instructions take precedence over skill guidelines. -->
<!-- cpk-rule-guard: Only the active coordinator can delegate, manage task state, commit, publish, or orchestrate review. -->
<!-- cpk-rule-guard: The coordinator can run at most one write-capable implementation subagent at a time. -->
<!-- cpk-rule-guard: Capture each terminal delegated result. -->
<!-- cpk-rule-guard: Archive only an explicitly targeted finished agent subtree. -->
<!-- cpk-rule-guard: Do not interrupt or replace a healthy active delegated task because it is slow. -->
<!-- cpk-rule-guard: When told to stop, start no new edit, test, review, subagent, commit, or CI action. -->

Expand All @@ -17,7 +19,11 @@ The coordinator can run at most one write-capable implementation subagent at a t

While an implementation subagent writes, the coordinator performs read-only work.

The coordinator closes each subagent after it reports `complete` or `blocked`.
A stopped turn does not finish an assignment when a required follow-up remains. Keep the same agent available until the complete assignment reports `complete` or `blocked`.

Capture each terminal delegated result. Then use exposed native thread archival to archive that exact finished agent thread. Always specify the finished thread identifier.

Archive only an explicitly targeted finished agent subtree. Archival cleans persisted thread history and does not prove that agent capacity was released. Do not use a default target that can select the coordinator. Archiving a parent can also archive its descendants, so wait until every descendant has finished and owes no required follow-up. Do not delete session files or edit Codex state directly.

Elapsed time alone cannot authorize a duplicate or restart of an active delegated task. Keep and poll the same task until it completes, reports blocked, or the platform reports that it stopped without coordinator action.

Expand Down
3 changes: 3 additions & 0 deletions check-updates.ps1
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
#Requires -Version 7.0
& python (Join-Path $PSScriptRoot "kit.py") check-updates @args
exit $LASTEXITCODE
Loading
Loading