[shiplog/plan] Fix Codex support story for shiplog phase commands

[devallibus]

Context

A Codex user reported that shiplog was installed, but Codex answered that hunt was not a defined shiplog subcommand. The user also inferred that the problem might be that the actual work repo was galeon, which has no .shiplog setup yet.

The investigation shows the immediate failure is not missing repo-local .shiplog state. The breakage is a packaging and documentation mismatch inside shiplog itself: the current README advertises /shiplog hunt and other explicit slash commands for Codex, while Codex skills currently document explicit skill invocation via /skills or $skill, not arbitrary repo-defined slash subcommands. The installed global Codex skill on disk was also stale and did not include the newer command packaging.

Design Summary

• Codex skill discovery is centered on SKILL.md; explicit invocation is documented via /skills or $skill, not custom commands/shiplog/*.md slash commands.
• The current shiplog README documents /shiplog hunt, /shiplog start, and related commands as if they were available in Codex, which over-promises Codex support.
• The repo's current skills/shiplog/SKILL.md no longer advertises phase-specific slash commands, but the published/installable skill on disk can still be stale, widening the mismatch.
• Repo-local .shiplog files are relevant for routing/mode state once shiplog is active in a project, but they are not the reason Codex rejected hunt as a subcommand.
• Quiet Mode logic for the command layer is already known to be incomplete, so even if the commands exist in another tool, they are not a reliable Codex compatibility story yet.

Approach

Treat this as a shiplog product/docs issue, not a galeon repo setup issue. Tighten the Codex support story so the README, installed skill layout, and actual Codex capabilities all agree.

Alternatives Considered

• Tell users to create .shiplog in every target repo first: Incorrect root-cause diagnosis. That config affects routing/mode behavior after activation, not command discovery.
• Keep documenting /shiplog <phase> for Codex and rely on prompt interpretation: Too ambiguous. It invites deterministic-looking command UX that Codex does not natively provide.
• Delete the command layer entirely: Too aggressive. The command files may still be useful for Claude-style environments; the real fix is to scope and package them by tool.

Sources and Verification Status

• [verified] Claim: Codex skills are documented as directories centered on SKILL.md, and explicit invocation is via /skills or $skill.
  • Source: https://developers.openai.com/codex/skills
  • Checked: The docs describe the skill structure around SKILL.md and say explicit invocation is by including the skill directly in the prompt, using /skills, or typing $.
• [verified] Claim: Codex CLI slash commands are documented as built-in session-control commands.
  • Source: https://developers.openai.com/codex/cli/slash-commands
  • Checked: The docs enumerate built-in commands such as /model, /permissions, /agent, /status, and do not document arbitrary skill-defined slash commands.
• [verified] Claim: The current repo README advertises /shiplog hunt and related slash commands.
  • Source: README.md
  • Checked: The Slash Commands section documents /shiplog hunt, /shiplog plan, /shiplog start, /shiplog commit, /shiplog pr, /shiplog lookup, /shiplog models, and /shiplog resume.
• [verified] Claim: The current repo skill no longer advertises phase-specific /shiplog <phase> entry points.
  • Source: skills/shiplog/SKILL.md
  • Checked: The skill currently lists only /shiplog and /shiplog models as user-invocable.
• [verified] Claim: Quiet-mode coverage for the slash-command layer is already known to be incomplete.
  • Source: .tmp-issue-quiet-mode-audit.md
  • Checked: The audit states that every slash command bypasses SKILL.md and is unaware of quiet mode.

Tasks

• T1: Scope the Codex UX contract in the docs [tier-2]

  • What: Audit Codex-facing docs and remove or qualify any claim that Codex supports custom /shiplog <phase> slash commands. Replace those claims with the actual Codex invocation path ($shiplog, /skills, or natural-language requests that trigger the skill).
  • Files: README.md (modify), skills/shiplog/SKILL.md (modify), any install snippets that mention Codex command behavior
  • Allowed to change: Codex-specific wording, install guidance, support matrix language
  • Must not change: Claude-specific command support unless explicitly called out as tool-specific
  • Forbidden judgment calls: Do not invent undocumented Codex command mechanisms
  • Stop and ask if: The docs need a broader support matrix redesign beyond shiplog
  • Verification: Manual doc review against current OpenAI Codex docs
  • Return artifact: Diff summary and exact docs sections updated
  • Decision budget: narrow
  • Accept when: A Codex user reading the README is no longer led to expect /shiplog hunt to exist as a native Codex slash command
  • Context: This is the user-facing breakage that triggered the report

• T2: Decide how explicit phase entry should work in Codex [tier-1]

  • What: Choose one supported Codex path for explicit phase entry: separate skills (for example shiplog-hunt), a single shiplog skill with internal routing from natural-language requests, or a documented "Claude-only commands" boundary. Write the chosen contract down in the repo.
  • Files: README.md (modify), skills/shiplog/ layout and metadata as needed, release/install docs as needed
  • Decision budget: full
  • Accept when: The repo has one clear, documented Codex story for explicit phase selection and it does not depend on undocumented slash-command behavior
  • Why tier-1: This requires choosing the long-term packaging model for Codex rather than just editing copy

• T3: Align the published/installable Codex skill with repo HEAD [tier-2]

  • What: Ensure the install flow for Codex pulls a skill package whose contents match the repo's current support contract. If the command layer is not part of Codex support, the packaged skill should not imply otherwise.
  • Files: skill packaging/release path, install docs, any generated or mirrored skill directories used for distribution
  • Allowed to change: Packaging metadata, publish instructions, skill bundle contents
  • Must not change: The core shiplog workflow semantics without a separate design decision
  • Stop and ask if: The distribution mechanism is owned by another repo or automation pipeline
  • Verification: Fresh install of the Codex skill from the documented path and manual inspection of installed contents
  • Return artifact: Install verification note with installed file list and invocation behavior summary
  • Decision budget: narrow
  • Accept when: A freshly installed Codex shiplog skill matches the documented Codex behavior
  • Context: The reporter's global ~/.agents/skills/shiplog install was stale relative to repo HEAD

• T4: Clarify repo-local .shiplog state vs. command discovery [tier-3]

  • What: Add a short note explaining that .shiplog/routing.md and optional mode files affect runtime state after activation, but they do not determine whether Codex can discover a shiplog command or subcommand.
  • Files: README.md (modify), optionally a configuration section or FAQ doc
  • Allowed to change: Configuration prose and troubleshooting notes
  • Must not change: Behavior of routing or mode files
  • Forbidden judgment calls: Do not introduce new config files unless separately decided
  • Stop and ask if: Clarifying this cleanly requires adding a broader troubleshooting section
  • Verification: Manual doc review
  • Return artifact: Diff summary with final wording
  • Decision budget: none
  • Accept when: A user can distinguish "Codex can load the skill" from "this repo has shiplog state files configured"
  • Context: The original user misattributed the failure to missing .shiplog in galeon

Open Questions

• Should Codex explicit phase entry become a set of separate skills (shiplog-hunt, shiplog-plan, etc.) instead of a single shiplog skill?
• Should the README add a per-tool support matrix so Claude Code command files and Codex skills are documented separately?
• If a .shiplog/mode.md file is added for cross-tool persistence, should that be committed config or purely local state?

---

Authored-by: openai/gpt-5 (codex)
Captain's log entry created by shiplog

[devallibus]

[shiplog/history] #129: additional Codex user report

A user explicitly reported that shiplog "sucks in Codex" because Codex does not pick up Claude-style commands such as /shiplog:hunt.

The user asked why Codex misses the command surface Claude Code supports and how shiplog should be fixed to work better with Codex.

This report reinforces three points already captured in the issue:

• The failure is experienced as broken command discovery, not as a repo-local .shiplog setup problem.
• Users expect parity with Claude plugin command ergonomics when the README advertises slash commands.
• The fix needs a Codex-native explicit-entry story, not just a wording cleanup.

Authored-by: openai/gpt-5 (codex)