Codex picker prompts and docs name skills the way Codex lists them (GST-3196) (#4524)

On Codex, the suggested prompts for nine gstack skills and the README
now say `$office-hours`, `$review` and so on, which load the skill;
`$gstack-office-hours` loaded nothing.

Why: Codex lists each skill by the `name:` in its SKILL.md, not the
`gstack-` folder, and skill_prefix never changes that name on Codex.

Nothing to do: the next `./setup --host codex` picks it up.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
This commit is contained in:
Garry Tanandcapy-ai[bot] authored and GitHub committed 2026-11-19 13:10:18 +00:00
1 parent b0f865c00c
commit b23e1b01a7
16 files changed
+52 -17

No files matched your search

+1 -1
View File
@@ -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` |
+1 -1
View File
@@ -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"
@@ -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.
+2 -2
View File
@@ -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 <name>` 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=<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)
+1 -1
View File
@@ -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/<yyyy>/<mm>/<dd>/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 `<skill>` 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 `<skill>` 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 `<skill>` 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 (`<gstack>/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.
+2 -2
View File
@@ -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=<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.
+1 -1
View File
@@ -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
+1 -1
View File
@@ -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
+1 -1
View File
@@ -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
+1 -1
View File
@@ -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"
+1 -1
View File
@@ -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
+1 -1
View File
@@ -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
+1 -1
View File
@@ -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
+35 -1
View File
@@ -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-<skill> where Codex lists <skill>; 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<string>();
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();
+1 -1
View File
@@ -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');
}
+1 -1
View File
@@ -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 <name> 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