| name | call-codex-with-openspec-cmd |
| description | How to invoke OpenSpec skills for a Codex-based Houmao managed agent using the $openspec-* command syntax via gateway prompt. |
| license | MIT |
Call Codex with OpenSpec Commands
Use this skill when you need to instruct a Codex-based Houmao managed agent to use OpenSpec skills. The correct invocation is via gateway prompt with the $openspec-<skill-name> command prefix.
Available OpenSpec Commands
| Command | Skill | Purpose |
|---|
$openspec-explore | openspec-explore | Explore openspec/ directory and understand change artifacts |
$openspec-propose | openspec-propose | Create a new OpenSpec change proposal |
$openspec-apply-change | openspec-apply-change | Implement an OpenSpec change |
$openspec-ext-explain | openspec-ext-explain | Create/update Q&A docs under explain/ directory |
$openspec-ext-hack-through-test | openspec-ext-hack-through-test | Propose, revise, or run hack-through-test mode |
$openspec-ext-respond-to-review | openspec-ext-respond-to-review | Read review report and decide open questions |
$openspec-ext-review-plan | openspec-ext-review-plan | Review current OpenSpec change and write report |
$openspec-ext-revise-by-decision | openspec-ext-revise-by-decision | Push review decisions into change artifacts |
Invocation Syntax
houmao-mgr agents gateway prompt \
--agent-name <agent-name> \
--prompt "$openspec-<command> <arguments>"
Examples
Explore an issue
houmao-mgr agents gateway prompt \
--agent-name hm-worker \
--prompt "$openspec-explore igamenovoer/houmao#60: env vars from launch profiles not propagated to Codex TUI processes"
Propose a new change
houmao-mgr agents gateway prompt \
--agent-name hm-worker \
--prompt "$openspec-propose implement-foo-bar"
Apply an existing change
houmao-mgr agents gateway prompt \
--agent-name hm-worker \
--prompt "$openspec-apply-change openspec/changes/2026-04-30-implement-foo-bar"
Respond to review
houmao-mgr agents gateway prompt \
--agent-name hm-worker \
--prompt "$openspec-ext-respond-to-review openspec/changes/2026-04-30-implement-foo-bar/review/review-20260430-120000.md"
Revise by decision
houmao-mgr agents gateway prompt \
--agent-name hm-worker \
--prompt "$openspec-ext-revise-by-decision openspec/changes/2026-04-30-implement-foo-bar"
Prerequisites
- Agent must be Codex-based Houmao managed agent (TUI transport)
- Agent must have a live gateway (
gateway_health: healthy)
- Agent's workdir should contain
openspec/ directory
- Agent should have OpenSpec skills in its skillset
Verification
Check gateway status before sending:
houmao-mgr agents gateway status --agent-name <agent-name>
Expected:
gateway_health: healthy
managed_agent_connectivity: connected
request_admission: open
Pitfalls
- Always use
gateway prompt, not agents prompt — the latter bypasses TUI skill loading
- Always include
$ prefix — $openspec-* is the magic trigger
- Use
--prompt flag, not --message
- If agent returns
not_ready, the TUI may be in modal state — wait or interrupt first
Related Skills
houmao-agent-messaging — general agent communication patterns
houmao-agent-inspect — checking agent liveness and gateway status