diff --git a/README.md b/README.md index bf67f367c..bbb55f948 100644 --- a/README.md +++ b/README.md @@ -79,7 +79,7 @@ installs and passes the conformance tests but has no certification run yet; | Agent | Tier | Install | First invocation | Safety skills | Outside review needs | Repair | |-------|------|---------|------------------|---------------|----------------------|--------| | Claude Code | full | `--host claude` (default) | `/office-hours` | enforced (hooks block) | Codex CLI, signed in | `./setup --host claude` | -| OpenAI Codex CLI | experimental | `--host codex` → `${CODEX_HOME:-~/.codex}/skills/gstack-*/` | ask for `gstack-office-hours` | destructive commands blocked once you trust gstack's hooks ([Codex hooks](docs/skill-routing-and-contracts.md#codex)); the rest advisory | Claude Code CLI, signed in | `./setup --host codex` | +| OpenAI Codex CLI | experimental | `--host codex` → `${CODEX_HOME:-~/.codex}/skills/gstack-*/` | `$office-hours` | destructive commands blocked once you trust gstack's hooks ([Codex hooks](docs/skill-routing-and-contracts.md#codex)); the rest advisory | Claude Code CLI, signed in | `./setup --host codex` | | OpenCode | experimental | `--host opencode` → `~/.config/opencode/skills/gstack-*/` + `/gstack-*` commands | `/gstack-office-hours` | advisory, not blocked | Codex CLI, signed in | `./setup --host opencode` | | Cursor | experimental | `--host cursor` → `~/.cursor/skills/gstack-*/` | ask for `gstack-office-hours` | advisory, not blocked | Codex CLI, signed in | `./setup --host cursor` | | Factory Droid | experimental | `--host factory` → `~/.factory/skills/gstack-*/` | ask for `gstack-office-hours` | advisory, not blocked | Codex CLI, signed in | `./setup --host factory` | diff --git a/autoplan/SKILL.md.tmpl b/autoplan/SKILL.md.tmpl index 4b5537faf..0491359ae 100644 --- a/autoplan/SKILL.md.tmpl +++ b/autoplan/SKILL.md.tmpl @@ -8,7 +8,7 @@ description: | borderline scope, outside-review disagreements) at one approval gate. Use when asked to "auto review", "autoplan", "run all reviews", "review this plan automatically", or "make the decisions for me". (gstack) -codex_default_prompt: "Use $gstack-autoplan to run the CEO, design, DX and eng reviews over this plan in one pass, decide the routine questions itself, and stop at a single approval gate." +codex_default_prompt: "Use $autoplan to run the CEO, design, DX and eng reviews over this plan in one pass, decide the routine questions itself, and stop at a single approval gate." voice-triggers: - "auto plan" - "automatic review" diff --git a/changelog.d/codex-skill-mentions-use-listed-names.md b/changelog.d/codex-skill-mentions-use-listed-names.md new file mode 100644 index 000000000..d90c8c633 --- /dev/null +++ b/changelog.d/codex-skill-mentions-use-listed-names.md @@ -0,0 +1 @@ +- **On Codex, gstack's suggested prompts and docs now name skills the way Codex lists them.** The picker prompts for nine skills (office-hours, review, ship, qa, autoplan, land-and-deploy, modernize, runaway-stopper and write-skill) said `$gstack-office-hours` and so on, which Codex doesn't recognize, so choosing one loaded nothing. They now say `$office-hours`, `$review` and so on, which load the skill. The README's Codex row and the Claude outside-voice note in docs/skills.md say the same. diff --git a/docs/hosts.md b/docs/hosts.md index 6d223f6c2..200bae2ed 100644 --- a/docs/hosts.md +++ b/docs/hosts.md @@ -167,7 +167,7 @@ after you approve); ask for `gstack-office-hours`, or list them with Codex skills in `.agents/skills` (the workspace tier wins), and workspace skills load only in trusted folders (`/trust`). -Outside reviews require the selected CLI to be installed and authenticated: Claude Code when using gstack in Codex, or Codex on other harnesses. External harnesses discover these commands as `/gstack-claude-code` and `/gstack-codex`; each harness omits its own wrapper. Explicit provider requests keep that provider. The existing `codex_reviews` setting controls automatic outside reviews where supported, regardless of the provider selected. +Outside reviews require the selected CLI to be installed and authenticated: Claude Code when using gstack in Codex, or Codex on other harnesses. External harnesses discover these commands as `/gstack-claude-code` and `/gstack-codex` (Codex lists its one as `claude-code`: mention it as `$claude-code`); each harness omits its own wrapper. Explicit provider requests keep that provider. The existing `codex_reviews` setting controls automatic outside reviews where supported, regardless of the provider selected. `/claude` has been renamed to `/claude-code`. Re-run `./setup --host ` to migrate managed installations, including other harnesses sharing the checkout. Setup preserves the previous installation if replacement generation or installation fails and prints repair instructions. @@ -226,7 +226,7 @@ repair message and reports the outside review as unavailable. It never silently switches to its default. Nested Codex reviews also run with installed skills hidden (`-c skills.include_instructions=false`), so a review cannot turn into a whole nested skill run. Runtime model selection is separate from the setup-time -behavioral profile above. Without the plan-review role, `/claude-code` (`gstack-claude-code` +behavioral profile above. Without the plan-review role, `/claude-code` (`$claude-code` on Codex) preserves Claude's configured model. Set `GSTACK_CLAUDE_MODEL=` or name a model in your request to override it for the invocation, including resumed consultations. See [eval defaults and overrides](../CONTRIBUTING.md#testing--evals) diff --git a/docs/skill-routing-and-contracts.md b/docs/skill-routing-and-contracts.md index a483c3345..bde24649a 100644 --- a/docs/skill-routing-and-contracts.md +++ b/docs/skill-routing-and-contracts.md @@ -95,7 +95,7 @@ The hook reads `destructive_guard` every time it runs, so `gstack-config set des **Contracts on Codex** use the same Stop hook, with the same one block per skill run, records and fail-open rules; Codex sends it the same `stop_hook_active` and `last_assistant_message` keys and takes the same block answer. The transcript is Codex's rollout file (`~/.codex/sessions///
/rollout-*.jsonl`), and the checker tells it from a Claude Code transcript by what the file holds (a rollout starts with a `session_meta` record), never by its path. On Codex: -- A **load** is Codex injecting a `gstack-*` skill into the conversation as a `` message (the app server's skill input does this), or the model reading one with a shell command such as `cat ~/.codex/skills/gstack-review/SKILL.md`. `codex exec '$gstack-review ...'` passes the `$` mention as plain text, so in `exec` the skill loads only when the model reads it. +- A **load** is Codex injecting a `gstack-*` skill into the conversation as a `` message (the app server's skill input does this), or the model reading one with a shell command such as `cat ~/.codex/skills/gstack-review/SKILL.md`. `codex exec '$review ...'` also injects the skill as a `` message (codex-cli 0.170); a mention of the folder name instead of the listed name is plain text, so then the skill loads only when the model reads it. - A **dispatch** is a `spawn_agent` call that started an agent. One that failed (its result has no `agent_id`) doesn't count. - **The contract** comes from gstack's own copy of the skill (`/review/SKILL.md`), because Codex's installed `SKILL.md` keeps only its name and description. - **/review's `specialists-dispatched` item is skipped**, because Codex doesn't run /review's specialist reviewers yet. The adversarial pass and the report are checked as on Claude Code, and the block text names `spawn_agent` and `wait_agent` where Claude Code's names an Agent dispatch. diff --git a/docs/skills.md b/docs/skills.md index 0a25567c6..a9a3811f2 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -1423,7 +1423,7 @@ through `-c model=...`, overriding the CLI's configured model for that call. Native review also sets `-c review_model=...` to that selection, overriding any separate review-model pin. -On Codex hosts, the Claude outside-voice skill is `gstack-claude-code`. Its +On Codex hosts, the Claude outside-voice skill is `$claude-code`. Its review, challenge, and consult calls preserve Claude's configured model. `GSTACK_CLAUDE_MODEL=` supplies an explicit override, including resumed sessions; a model named in your request takes precedence. Harness routing is @@ -1470,7 +1470,7 @@ Claude: Running independent Codex review... ## `/claude-code` -Claude Code provides the outside reviewer when gstack runs in Codex. Other non-Claude harnesses also expose this skill for explicit requests; Claude Code itself omits it. External harnesses install it as `/gstack-claude-code`. +Claude Code provides the outside reviewer when gstack runs in Codex. Other non-Claude harnesses also expose this skill for explicit requests; Claude Code itself omits it. External harnesses install it as `/gstack-claude-code`; Codex lists it as `claude-code`, so mention it as `$claude-code`. **Review** supplies the branch diff for a read-only pass/fail review. **Challenge** asks Claude Code to find concrete failure cases in the same diff. **Consult** supports read-only repository exploration and resumes the session saved in `.context/claude-session-id`. Review and challenge receive context from the parent workflow and run without tools; consultation can read and search files. diff --git a/land-and-deploy/SKILL.md.tmpl b/land-and-deploy/SKILL.md.tmpl index a4ec02a53..bb102fbe2 100644 --- a/land-and-deploy/SKILL.md.tmpl +++ b/land-and-deploy/SKILL.md.tmpl @@ -7,7 +7,7 @@ description: | verifies production health via canary checks. Takes over after /ship creates the PR. Use when: "merge", "land", "deploy", "merge and verify", "land it", "ship it to production". (gstack) -codex_default_prompt: "Use $gstack-land-and-deploy to merge this pull request once its checks pass, wait for CI and the deploy, and verify production health before calling it landed." +codex_default_prompt: "Use $land-and-deploy to merge this pull request once its checks pass, wait for CI and the deploy, and verify production health before calling it landed." allowed-tools: - Bash - Read diff --git a/modernize/SKILL.md.tmpl b/modernize/SKILL.md.tmpl index a8e4992a9..197737905 100644 --- a/modernize/SKILL.md.tmpl +++ b/modernize/SKILL.md.tmpl @@ -8,7 +8,7 @@ description: | Use when asked to "modernize this PR", "rebase this old PR", "revive this branch", or "is this PR still worth landing". Never closes a PR on its own. (gstack) -codex_default_prompt: "Use $gstack-modernize to bring this pull request onto its current base, check for conflicts in meaning as well as in text, and say plainly whether it should stay open." +codex_default_prompt: "Use $modernize to bring this pull request onto its current base, check for conflicts in meaning as well as in text, and say plainly whether it should stay open." triggers: - modernize this pr - rebase this old pr diff --git a/office-hours/SKILL.md.tmpl b/office-hours/SKILL.md.tmpl index 02e36cc83..ac8175634 100644 --- a/office-hours/SKILL.md.tmpl +++ b/office-hours/SKILL.md.tmpl @@ -14,7 +14,7 @@ description: | through design decisions for something that doesn't exist yet, or is exploring a concept before any code is written. Use before /plan-ceo-review or /plan-eng-review. (gstack) -codex_default_prompt: "Use $gstack-office-hours to think this idea through before any code: challenge the premise, find the narrowest wedge, and save a design doc the later skills read." +codex_default_prompt: "Use $office-hours to think this idea through before any code: challenge the premise, find the narrowest wedge, and save a design doc the later skills read." allowed-tools: - Bash - Read diff --git a/qa/SKILL.md.tmpl b/qa/SKILL.md.tmpl index 7bc6706b1..8ab00d59d 100644 --- a/qa/SKILL.md.tmpl +++ b/qa/SKILL.md.tmpl @@ -11,7 +11,7 @@ description: | or asks "does this work?". Three tiers: Quick (critical/high only), Standard (+ medium), Exhaustive (+ cosmetic). Produces contract outcomes or browser health scores, fix evidence, and a ship-readiness summary. For report-only mode, use /qa-only. (gstack) -codex_default_prompt: "Use $gstack-qa to test what changed (browser, API, CLI, jobs, workers, webhooks), reproduce each defect, fix it, and prove the fix with a regression test." +codex_default_prompt: "Use $qa to test what changed (browser, API, CLI, jobs, workers, webhooks), reproduce each defect, fix it, and prove the fix with a regression test." voice-triggers: - "quality check" - "test the app" diff --git a/review/SKILL.md.tmpl b/review/SKILL.md.tmpl index 958d49714..a1d1a2820 100644 --- a/review/SKILL.md.tmpl +++ b/review/SKILL.md.tmpl @@ -8,7 +8,7 @@ description: | over my diff", "review my changes", "code review", "check my diff" or "pre-landing review". Proactively suggest before a merge. (gstack) -codex_default_prompt: "Use $gstack-review to review this diff against its base before it lands: find the bugs that pass CI and break in production, fix the clear ones, and list what remains." +codex_default_prompt: "Use $review to review this diff against its base before it lands: find the bugs that pass CI and break in production, fix the clear ones, and list what remains." allowed-tools: - Bash - Read diff --git a/runaway-stopper/SKILL.md.tmpl b/runaway-stopper/SKILL.md.tmpl index e85ca270f..4660263ad 100644 --- a/runaway-stopper/SKILL.md.tmpl +++ b/runaway-stopper/SKILL.md.tmpl @@ -6,7 +6,7 @@ description: | Find runaway Capy threads and subagents, stop or rotate them safely, and prevent repeats. Use for "find runaway threads", "stop runaway jobs", "rotate this thread" or a token sweep. (gstack) -codex_default_prompt: "Use $gstack-runaway-stopper to scan this crew for runaway threads and subagents, stop what is safe to stop, and report the rest." +codex_default_prompt: "Use $runaway-stopper to scan this crew for runaway threads and subagents, stop what is safe to stop, and report the rest." triggers: - find runaway threads - stop runaway jobs diff --git a/ship/SKILL.md.tmpl b/ship/SKILL.md.tmpl index 4bfb5c8de..e2df92afc 100644 --- a/ship/SKILL.md.tmpl +++ b/ship/SKILL.md.tmpl @@ -8,7 +8,7 @@ description: | "push to main", "create a PR", "merge and push", or "get it deployed". Proactively invoke this skill (do NOT push/PR directly) when the user says code is ready, asks about deploying, wants to push code up, or asks to create a PR. (gstack) -codex_default_prompt: "Use $gstack-ship to take this branch to a pull request: merge the base, run the tests, review the diff, stamp the version and changelog, then push and open or update the PR." +codex_default_prompt: "Use $ship to take this branch to a pull request: merge the base, run the tests, review the diff, stamp the version and changelog, then push and open or update the PR." allowed-tools: - Bash - Read diff --git a/test/gen-skill-docs.test.ts b/test/gen-skill-docs.test.ts index 024605cc3..7e397925b 100644 --- a/test/gen-skill-docs.test.ts +++ b/test/gen-skill-docs.test.ts @@ -2965,13 +2965,47 @@ describe('Codex generation (--host codex)', () => { const tmpl = fs.readFileSync(path.join(ROOT, dir, 'SKILL.md.tmpl'), 'utf-8'); const prompt = extractCodexDefaultPrompt(tmpl); expect(prompt, `${dir} declares codex_default_prompt`).toBeDefined(); - expect(prompt!, dir).toContain(`$gstack-${dir}`); + expect(prompt!, dir).toContain(`$${dir} `); expect(prompt!, `${dir}: a prompt tells the picker what the skill is for`).not.toBe(`Use gstack-${dir} for this task.`); const yaml = Bun.YAML.parse(fs.readFileSync(path.join(AGENTS_DIR, `gstack-${dir}`, 'agents', 'openai.yaml'), 'utf-8')) as { interface: { default_prompt: string } }; expect(yaml.interface.default_prompt, dir).toBe(prompt!); } }); + // Codex 0.170 lists and mentions a skill by its SKILL.md name: (`review`), not + // its gstack-review folder, so `$gstack-review` loads nothing (GST-3196). + // Value: protects=every $-mention a Codex user is shown loads a listed skill; fails_when=a template, the Codex render or a doc says $gstack- where Codex lists ; why_new=the prompt test above checks only seven templates and no docs; seam=none; no_claim=Codex's own mention parser + test('every $gstack- mention in the Codex render and the docs names a skill Codex lists', () => { + const listed = new Set(); + const files: string[] = []; + const walk = (dir: string) => { + for (const e of fs.readdirSync(dir, { withFileTypes: true })) { + const p = path.join(dir, e.name); + if (e.isDirectory()) walk(p); + else if (e.isFile() && /\.(md|ya?ml)$/.test(e.name)) files.push(p); + } + }; + for (const skill of fs.readdirSync(AGENTS_DIR)) { + const md = path.join(AGENTS_DIR, skill, 'SKILL.md'); + if (!fs.existsSync(md)) continue; + const name = fs.readFileSync(md, 'utf-8').match(/^---\n[\s\S]*?^name:[ \t]*(\S+)/m)?.[1]; + if (name) listed.add(name); + walk(path.join(AGENTS_DIR, skill)); + } + expect(listed.has('review') && listed.has('gstack-upgrade')).toBe(true); + const docs = ['README.md', 'docs/hosts.md', 'docs/skills.md', 'docs/skill-routing-and-contracts.md', 'docs/troubleshooting.md']; + const bad: string[] = []; + for (const f of [...files, ...docs.map(d => path.join(ROOT, d))]) { + for (const m of fs.readFileSync(f, 'utf-8').matchAll(/\$(gstack-[a-z0-9-]*[a-z0-9])/g)) { + if (!listed.has(m[1])) bad.push(`${path.relative(f.startsWith(AGENTS_DIR) ? AGENTS_DIR : ROOT, f)}: $${m[1]}`); + } + } + expect(bad).toEqual([]); + const codexRow = fs.readFileSync(path.join(ROOT, 'README.md'), 'utf-8').split('\n').find(l => l.startsWith('| OpenAI Codex CLI |')); + const first = codexRow?.split('|')[4]?.match(/`\$([a-z0-9-]+)`/)?.[1]; + expect(first && listed.has(first) ? first : codexRow).toBe('office-hours'); + }); + test('a template without codex_default_prompt: keeps the generic default_prompt', () => { const tmpl = fs.readFileSync(path.join(ROOT, 'careful', 'SKILL.md.tmpl'), 'utf-8'); expect(extractCodexDefaultPrompt(tmpl)).toBeUndefined(); diff --git a/test/modernize-skill.test.ts b/test/modernize-skill.test.ts index e5ff6386a..0ef7746da 100644 --- a/test/modernize-skill.test.ts +++ b/test/modernize-skill.test.ts @@ -20,7 +20,7 @@ describe('/modernize skill', () => { test('frontmatter: tier 2, sensitive, a Codex default prompt and the four triggers', () => { expect(tmpl.startsWith('---\nname: modernize\npreamble-tier: 2\n')).toBe(true); expect(tmpl).toMatch(/^sensitive: true$/m); - expect(tmpl).toMatch(/^codex_default_prompt: "Use \$gstack-modernize to /m); + expect(tmpl).toMatch(/^codex_default_prompt: "Use \$modernize to /m); for (const t of ['modernize this pr', 'rebase this old pr', 'revive this branch', 'is this pr still worth landing']) { expect(tmpl, t).toContain(' - ' + t + '\n'); } diff --git a/write-skill/SKILL.md.tmpl b/write-skill/SKILL.md.tmpl index 877c8b013..03bddebfb 100644 --- a/write-skill/SKILL.md.tmpl +++ b/write-skill/SKILL.md.tmpl @@ -7,7 +7,7 @@ description: | levels, drift and size checks, full diets. Use when asked to "write a skill", "improve this skill", "add this lesson to the skill" or "put this skill on a diet". (gstack) -codex_default_prompt: "Use $gstack-write-skill to change this skill the lean way: fix the tool first, edit the line that already covers the idea, and record the size before and after." +codex_default_prompt: "Use $write-skill to change this skill the lean way: fix the tool first, edit the line that already covers the idea, and record the size before and after." triggers: - write a skill - improve this skill