Add Codex plugin support alongside Claude Code

.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "ytstack",
+  "interface": {
+    "displayName": "ytstack"
+  },
+  "plugins": [
+    {
+      "name": "ytstack",
+      "source": {
+        "source": "local",
+        "path": "./"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Developer Tools"
+    }
+  ]
+}

.codex-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "ytstack",
+  "version": "0.1.6",
+  "description": "Project memory, milestone planning, and curated gstack and superpowers workflows for AI coding agents.",
+  "author": {
+    "name": "Yesterday",
+    "url": "https://github.com/Yesterday-AI"
+  },
+  "homepage": "https://github.com/Yesterday-AI/ytstack",
+  "repository": "https://github.com/Yesterday-AI/ytstack",
+  "license": "MIT",
+  "keywords": ["codex", "project-management", "development-methodology"],
+  "skills": "./skills/",
+  "hooks": "./codex/hooks.json",
+  "interface": {
+    "displayName": "ytstack",
+    "shortDescription": "Plan, build, and resume work across sessions",
+    "longDescription": "Keep project decisions and progress on disk. Plan milestones, review scope and architecture, and apply test-first development with explicit verification.",
+    "developerName": "Yesterday",
+    "category": "Developer Tools"
+  }
+}

.github/workflows/plugin-check.yml

@@ -0,0 +1,30 @@
+name: Plugin checks
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Codex packaging and lifecycle integration
+        run: python3 -m unittest discover -s tests -p 'codex_plugin_test.py' -v
+      - name: Claude commit-hook regression
+        run: bash tests/post-tool-use-bash.test.sh
+      - name: Skill contracts
+        shell: bash
+        run: |
+          result=0
+          bin/ytstack-check || result=$?
+          if [ "$result" -ne 0 ] && [ "$result" -ne 2 ]; then
+            exit "$result"
+          fi

.ytstack/DECISIONS.md

@@ -639,3 +639,61 @@ Plus: ops-layer split during the same session (yopstack created as own public re
 - Regression test: `tests/post-tool-use-bash.test.sh` (10 cases) is the contract guard.
 
 **Supersedes:** none.
+
+
+---
+
+## 2026-10-13: Add Codex distribution alongside Claude Code
+
+**Context:** The maintainer requested a PR making the existing Claude plugin usable as a Codex plugin. Codex could not discover ytstack in the active skill catalog. Shared wrappers also rely on Claude skill-directory variables and shell-injection blocks, so a manifest alone would not make them executable.
+
+**Options considered:**
+- A) Add a manifest only; leave host-specific skill and hook assumptions unresolved.
+- B) Keep shared skills and immutable vendor content, add a Codex manifest/self-marketplace and an adapter for host mechanics.
+- C) Fork all skills into a second Codex-only tree.
+
+**Chose:** B, implementing the requested additional host with one source of skill content.
+
+**Reason:** Both hosts can use the same artifacts and procedures. Codex needs explicit execution of the wrapper blocks and correct installed skill paths. A per-skill adapter link covers direct invocation even without trusted lifecycle hooks. A separate hook manifest prevents discovery of Claude-only team and tool events.
+
+**How to apply:**
+- `.codex-plugin/plugin.json` loads the existing `skills/`; `.agents/plugins/marketplace.json` self-marketplaces the repo root as `ytstack@ytstack`.
+- `bin/ytstack-codex` derives plugin/skill paths and sets the target project from the working directory for each shared shell block or lifecycle hook.
+- Codex registers SessionStart, PreCompact, and SessionEnd only. Hook trust remains the host's explicit user-controlled setting. Without hooks, skills read state directly and support explicit resume/handoff.
+- Claude Agent Teams, its subagent role files, and edit/commit hooks remain Claude-specific. Codex's team skill reports the limitation and offers the sequential workflow; it does not emulate those events with Codex subagents.
+- No Claude marketplace dependencies are copied into the Codex manifest. Required optional capabilities must be available separately.
+- Keep the two plugin manifest versions aligned. Existing Claude installation and vendored content remain unchanged.
+
+**Supersedes:** The Claude-only host assumption in the 2026-04-23 "Skills-based plugin, not Agent SDK library" and 2026-04-24 path/wrapper decisions. The skills-based architecture, vendor-as-source-of-truth rule, and Claude's native wrapper behavior remain in force.
+
+---
+
+## 2026-10-13: Generate a separate Codex package from unchanged Claude sources
+
+**Context:** During PR #23 review the maintainer rejected Codex instructions in skills loaded by Claude and Claude environment variables in the Codex adapter. The maintainer selected keeping Claude sources unchanged and automatically deriving a separate Codex package.
+
+**Chose:** Keep `skills/`, `hooks/`, and `.claude-plugin/` unchanged. `bin/build-codex` generates `codex/skills/` and the three `codex/hooks/` lifecycle scripts; the Codex manifest selects only these paths. Generated files are committed so plugin installation needs no build step.
+
+**Reason:** The procedures have one maintained source, while each host loads its own instructions and environment contract. Claude retains native dynamic shell injection. Codex runs explicit Bash blocks with `YTSTACK_PLUGIN_ROOT`, `YTSTACK_SKILL_DIR`, and `YTSTACK_PROJECT_DIR`. Codex's project path resolves to the current Git repository/worktree root, with the current directory as the non-Git fallback.
+
+**How to apply:**
+- After changing source skills, their resources, or lifecycle hooks, run `python3 bin/build-codex` and commit the generated output. CI runs `--check` to reject drift.
+- Keep host adaptations in the generator and `codex/adapter.md`. Never add Codex instructions to the Claude source skills.
+- Copy skill references and templates with their skills. Keep all `vendor/` content unchanged; generated wrappers still read the same six procedures verbatim.
+- Codex's `spawn-milestone-team` entry explains the support limit and sequential alternative; it contains no Claude capability probe or spawn procedure.
+- Fail generation on unhandled Claude environment variables so new host dependencies require an explicit adaptation.
+
+**Supersedes:** The direct shared-skill loading, per-source-skill Codex links, and Claude environment compatibility layer in the earlier Codex distribution decision. The additional Codex host, separate hook registration, user-controlled hook trust, and support limits remain.
+
+
+---
+
+## 2026-10-13: Remove generated Codex copies; load the existing skills directly
+
+**Context:** The maintainer rejected copying the skills and requested the minimal necessary Codex integration. The generated second tree was unnecessary.
+
+**Chose:** Both manifests select the existing skills/. Delete bin/build-codex and all generated skill, resource, and hook copies. No source skill receives Codex boilerplate or a content rewrite.
+
+**How to apply:** Keep Codex tool mappings in codex/adapter.md. The Codex SessionStart entry passes these as optional host context to the shared hook. Without trusted hooks, read the adapter explicitly before following skills. The small runtime helper supplies the shared scripts' existing CLAUDE_* inputs and resolves the repository root; those compatibility names do not require a Claude executable. All three lifecycle events use the original hook scripts. Do not reintroduce generated copies or a second skill tree.
+
+**Supersedes:** The earlier generated-package decision and per-skill Codex-link approach. The host-specific manifests, three-event Codex registration, hook trust, and repository-subdirectory fix remain.

.ytstack/REVIEW-NOTES.md

@@ -158,3 +158,15 @@ Running list of items to verify, revisit, or polish at end-of-cycle review. Adde
 - **At v0.1 release:** items remaining must be annotated with target version (v0.1.1, v0.2, etc.) or closed as "intentionally out of scope."
 
 **File is append-only within a milestone.** When re-organizing or resolving, add a date and move resolved items to a `## Resolved` section at the bottom (keep for audit).
+
+
+## Codex compatibility (2026-10-13)
+
+- [x] Verified Codex CLI 0.162.1 local marketplace discovery, install/enable, and app-server skill/hook loading in a temporary profile: 21 skills, 3 lifecycle hooks, no load errors. Hooks remain untrusted until the user reviews them.
+- [x] Integration tests cover the configured hook commands, project/user state lookup, compaction handoff, session journaling without tracked-state mutation, all six vendor imports, paths with spaces, invalid skills, and failure propagation. Existing Claude commit-hook regression passes; validator warnings match main (109).
+- [ ] Manual interactive Codex desktop walkthrough after hook trust: resume an initialized project, complete a task, compact, then confirm the next session sees the handoff. Deterministic hook tests and app-server discovery do not validate model behavior or the desktop trust UI.
+- Codex support deliberately excludes Claude Agent Teams and edit/commit hooks. The Codex adapter explains sequential execution and explicit scope/verification; do not advertise full hook/team parity. `docs/codex.md` records the boundary.
+
+- [x] PR #23 review follow-up: Claude skills, hooks, and manifests are byte-identical to main. Fresh Codex profile discovers 21 generated skills and 3 hooks from codex/. Fifteen tests cover host separation, generation drift, copied resources, both hosts' vendor imports, and repository-subdirectory lifecycle behavior.
+
+- [x] PR #23 simplification supersedes the generated-package notes above: all copied skills/resources/hooks and the generator removed. Both hosts load the original skills/ tree; 13 tests and fresh Codex discovery pass. Codex SessionStart includes the single runtime adapter; the documented no-hook path reads it explicitly. Claude startup receives no Codex instructions.

.ytstack/STATE.md

@@ -1,14 +1,16 @@
 ---
 project: ytstack
 slug: ytstack
-last_updated: 2026-05-31T13:20:00Z
+last_updated: 2026-10-13T09:42:26Z
 current_milestone: M015
 active_slice: none
 active_task: none
 ---
 
 # State
 
+**Status (2026-10-13, PR #23 correction):** Removed the generated Codex skill/hook copies and build tooling. Both hosts load the original 21 skills from skills/ and reuse the lifecycle scripts in hooks/. Codex-specific runtime instructions live only in codex/adapter.md, supplied at SessionStart or read explicitly without trusted hooks. The helper provides the existing script environment and resolves repository-root paths, including starts in subdirectories. All 13 integration tests pass, including both hosts' six vendor imports, lifecycle state/journal behavior, and the single-source package check. Fresh Codex discovery loads the 21 original skill files and three hooks without errors or warnings. The contract checker reports the same 109 baseline warnings, no failures. The interactive desktop walkthrough remains a manual follow-up. This supersedes the earlier generated-package implementation in this PR.
+
 **Status (2026-05-31, vendor drift audit + superpowers pull):** Audited both vendored subtrees for upstream breaking changes against the ytstack wrapper contract (wrappers inline the six wrapped SKILL.md verbatim via `` ```!cat ``; breaking surface = path-rename = silent empty `cat`, or procedure rewrite). **superpowers PULLED** `6efe32c -> 6fd4507`: all three wrapped SKILL.md (TDD, systematic-debugging, verification-before-completion) byte-identical upstream, zero ytstack-behavior change; only drumherum moved (README, tests, using-git-worktrees, finishing-a-development-branch). Merge `ca6675e` / squash `ad14900`; `bin/ytstack-check` = 0 fails (exit 2 = warnings-only). **NOTE: ca6675e is already on origin/main (pushed)** -- the push went out without an explicit push in-conversation (auto-mechanism or the still-present `thirsty-bhabha-a03490` worktree); flagged to the human. **gstack NOT pulled**, held at `aeea57f` (upstream `3bef43b` is a v1 restructure, ~1000 changed lines/file): methodology anchors all survive (no hard break), but a net-new `gbrain:` frontmatter `context_queries` block + `GSTACK_PLAN_MODE` is surface NOT covered by DECISIONS 2026-04-25 "Vendored-preamble drift accepted" (that decision only covers `|| true` shell, not frontmatter) -- revisit that decision before pulling gstack. KNOWLEDGE gotchas added (drift-audit method + gbrain). Hold-gstack is deliberately NOT yet a locked DECISIONS entry (left as a STATE/KNOWLEDGE fact pending the gbrain-strategy call). No version bump for the vendor refresh -- decided 2026-05-31, no ytstack-behavior change so it stays 0.1.6.
 
 **Status (2026-05-31, M015):** Fixed issue #22 via `systematic-debugging` (root cause empirically reproduced, not trusted from the report). The `post-tool-use-bash` hook is now **stub-once** (creates the draft `T##-SUMMARY.md` once on the first real `git commit`, never re-writes; matcher tightened to a real `git commit` after a command separator) and commit-to-task linking moved into `summarize-task` (greps `git log` for the `M###-S##-T##:` ref into a committed `## Commits` section). This kills the duplicate "Commits so far" lines + never-settling working tree that broke worktree/`spawn-milestone-team` dispatch. New regression test `tests/post-tool-use-bash.test.sh` (10 cases, all green). Version bumped 0.1.5 -> **0.1.6**. DECISIONS entry "post-tool-use-bash is stub-once" + KNOWLEDGE gotcha added. **SHIPPED:** committed (`1c1d612` fix, `77365f5` chore), pushed to `origin/main`, tagged **v0.1.6** (pushed), CHANGELOG.md created, **issue #22 CLOSED**. Cache caveat: live for users only after `/plugin update` to 0.1.6.

AGENTS.md

@@ -10,7 +10,7 @@ Before any architectural proposal, read in order: `docs/concept.md` (stable summ
 
 Stop. Read this section before acting.
 
-ytstack is an opinionated software-development OS packaged as a Claude Code plugin. It has strict UX contracts and a curated scope. Agents that skip this file produce churn -- the wrong abstraction, the wrong scope, drift away from the artifact model.
+ytstack is an opinionated software-development OS packaged for Claude Code and Codex. It has strict UX contracts and a curated scope. Agents that skip this file produce churn -- the wrong abstraction, the wrong scope, drift away from the artifact model.
 
 **Your job is to protect the human from shipping low-quality skills.** Before you open a PR or commit a skill change, you MUST:
 
@@ -25,7 +25,7 @@ If you can't verify all five above, stop and tell the human what you can't verif
 ## What ytstack is (and is not)
 
 **Is:**
-- A Claude Code plugin (skills + hooks + commands)
+- A Claude Code and Codex plugin (one shared skill tree and lifecycle scripts, host-specific registration; see `docs/codex.md` for the support boundary)
 - A curated clamp around selected superpowers and gstack skills, vendored via git subtree, NEVER modified
 - An artifact-first system: `.ytstack/PROJECT.md`, `DECISIONS.md`, `KNOWLEDGE.md`, `STATE.md`, milestone/slice/task hierarchy
 - SessionStart-hook-driven context injection (following superpowers' using-superpowers pattern)

CONTRIBUTING.md

@@ -105,6 +105,21 @@ Per ytstack's design direction, we credit external methodology work generically,
 5. Test standalone with mock `CLAUDE_PROJECT_DIR`.
 6. Add REVIEW-NOTES entry for integration-test-needed.
 
+## Codex compatibility
+
+Both hosts load `skills/` and reuse the lifecycle scripts in `hooks/`.
+Keep skill content in that one tree. Codex tool mappings live in
+`codex/adapter.md`; the Codex SessionStart path supplies them before the shared
+directive. `bin/ytstack-codex` supplies the existing script environment, including
+repository-root resolution. Register supported events in `codex/hooks.json`.
+There is no generation step, skill copy, or per-skill Codex boilerplate.
+Keep `.codex-plugin/plugin.json` and `.claude-plugin/plugin.json` versions aligned.
+
+Run `python3 -m unittest discover -s tests -p 'codex_plugin_test.py' -v` and
+`bash tests/post-tool-use-bash.test.sh` alongside `bin/ytstack-check`. CI accepts
+the validator's warnings-only exit code (2) and rejects failures. See
+[Codex setup](docs/codex.md) for installation and manual discovery checks.
+
 ## How to add a new vendor subtree
 
 1. Verify the license is compatible (MIT / Apache-2.0 / similar permissive).

QUICKSTART.md

@@ -4,6 +4,10 @@ From zero to a tracked, shipped task -- the way you actually use ytstack: by tal
 
 ## Install
 
+For Codex, follow [Codex setup](docs/codex.md). The workflow below uses Claude
+Code command names; in Codex select the corresponding skill from ytstack with
+`$ytstack:<skill-name>`. Claude Agent Teams are not available through the Codex adapter.
+
 ### Local dev (recommended for first try)
 
 ```bash

README.md

@@ -6,13 +6,14 @@
   <p><em>An opinionated OS for AI coding agents. Plan like a PM, execute like a senior eng.</em></p>
 
   <p>
-    A Claude Code plugin that turns multi-session, multi-week projects into something your agent can actually hold onto. Project memory on disk, curated skill set, parallel execution via native Agent Teams. One install, one namespace, no stack to maintain.
+    A plugin for Claude Code and Codex that turns multi-session, multi-week projects into something your agent can actually hold onto. Project memory on disk, curated skill set, and native Agent Teams in Claude Code. One install, one namespace, no stack to maintain.
   </p>
 
   <p>
     <a href="./LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-blue"></a>
     <img alt="version" src="https://img.shields.io/badge/version-0.1.5-FC4E14">
     <img alt="Claude Code" src="https://img.shields.io/badge/Claude%20Code-plugin-0A0A0A">
+    <img alt="Codex" src="https://img.shields.io/badge/Codex-plugin-0A0A0A">
     <img alt="skills" src="https://img.shields.io/badge/skills-21-FC4E14">
     <img alt="hooks" src="https://img.shields.io/badge/hooks-8-FC4E14">
   </p>
@@ -178,6 +179,24 @@ Source: [`docs/ytstack-debugging-flow.excalidraw`](docs/ytstack-debugging-flow.e
 
 ## Install
 
+### Codex
+
+```bash
+codex plugin marketplace add Yesterday-AI/ytstack
+codex plugin add ytstack@ytstack
+```
+
+Start a new session. With trusted hooks, ytstack supplies its runtime context
+automatically. Without hooks, first ask Codex to read the installed plugin's
+`codex/adapter.md`, then select `$ytstack:using-ytstack` in the skill picker.
+On local hosts with hook support, review and trust the plugin hooks for automatic
+startup context, compaction handoff, and session journaling. Both hosts load the same 21 skill files. Claude Agent Teams and edit/commit hooks remain
+Claude-only; Codex uses the sequential task flow and explicit verification.
+See [Codex setup and compatibility](docs/codex.md) for local development,
+hook-free usage, and validation.
+
+The installation methods below are for Claude Code.
+
 ### Local dev (recommended for first try)
 
 ```bash
@@ -272,6 +291,7 @@ Ships:
 - 8 hooks (SessionStart / PreCompact / SessionEnd / TeammateIdle / TaskCreated / TaskCompleted / PreToolUse-Edit / PostToolUse-Bash). SessionStart-hook now injects the using-ytstack directive + project state.
 - Full docs (`AGENTS.md`, `CONTRIBUTING.md`, `QUICKSTART.md`, UX contracts, references, methodology)
 - Plugin manifest + marketplace manifest, published via the `yesterday-public-plugins` catalog
+- Codex manifest + self-marketplace, shared skills, and 3 lifecycle hooks; see [host support](docs/codex.md#supported-behavior)
 
 See `.ytstack/ROADMAP.md` for the task list, `.ytstack/STATE.md` for progress, `.ytstack/REVIEW-NOTES.md` for deferred items.