| name | shipyard-codex-orchestration |
| description | Use when running any multi-step Shipyard workflow under Codex — build, audit, plan, ship, review, research, or map. Explains how Shipyard's parallel-agent workflows degrade to inline sequential execution in Codex, and routes intent to the right workflow skill. Trigger when the user says "build the plan", "audit this", "ship it", "review the code", "run the shipyard build", or asks how Shipyard works in Codex. |
Shipyard orchestration under Codex
Shipyard was built for Claude Code, where workflows dispatch fresh subagents in
parallel (builder, reviewer, auditor, architect, verifier, researcher, mapper, …)
via the Task tool. Codex has no equivalent — it runs in a single context.
So under Codex, Shipyard workflows run as inline sequential personas: instead of
dispatching a separate agent, you adopt each role yourself, one after another, in this
same conversation.
Honest degradation — what you lose
- No parallelism. Roles run one at a time, so multi-agent phases are slower.
- No context isolation. In Claude Code a fresh reviewer can't be biased by the
builder's reasoning. Here the same context does both, so a review is less independent.
Compensate by being deliberately skeptical when you switch into a review/verify role —
re-read the actual artifact, don't trust your own prior step.
What you keep: the discipline — the review and verify gates still run, just sequentially.
The inline-sequential pattern
When a workflow calls for "dispatch the X agent", instead:
- State which role you're entering ("Now acting as the reviewer…").
- Adopt that role's mandate fully — including its MUST-NOT constraints (a reviewer
makes no code edits; a mapper only documents).
- Produce the role's deliverable.
- Exit the role and continue the workflow.
Routing — which skill for which intent
| Intent | Skill / behavior |
|---|
| Implement a plan | shipyard-executing-plans skill, run builder→reviewer→verifier inline |
| Security/compliance audit | security-audit skill, adopting the auditor mandate |
| Create a plan | shipyard-writing-plans skill (+ shipyard-brainstorming first) |
| Code review after a build | shipyard-review skill |
| Domain/technology research | shipyard-research skill |
| Map/onboard a codebase | shipyard-map skill |
| Ship/release a completed phase | shipyard-ship skill |
| TDD a feature | shipyard-tdd skill |
| Debug a failure | shipyard-debugging skill |
If a workflow has a dedicated skill, use it and apply the inline-sequential pattern above
to any agent dispatch it describes. The shipyard-review, shipyard-research,
shipyard-map, and shipyard-ship skills exist because those roles have no other skill
home in Codex.
State
Codex has no SessionStart hook, so Shipyard state is not auto-loaded. When a workflow
needs project state, run scripts/state-read.sh yourself at the start (see the
state/utility skills).
