docs(codex): document plan mode and build mode compatibility

- Add Plan Mode vs Build Mode section to installation docs
- Explain spec generation works in both modes
- Note that execution scripts run from terminal in Codex
- Add platform comparison table (Claude Code vs Codex features)
- Update README Codex section with $spec-driven: syntax and plan/build note

Author: Habib0x0

README.md

@@ -219,15 +219,25 @@ bash scripts/spec-exec.sh --spec-name user-authentication
 
 #### Usage in Codex
 
-Codex does not use slash commands. Instead, invoke the skill by typing one of the prompt phrases defined in the plugin manifest:
+Codex commands use `$spec-driven:` prefix instead of `/`:
 
-| What you type in Codex | What it does |
+```
+$spec-driven:spec user-authentication
+$spec-driven:spec-status
+$spec-driven:spec-exec
+```
+
+You can also invoke the skill by typing one of its default prompt phrases:
+
+| Prompt | Action |
 | --- | --- |
 | `Create a spec for this feature` | Start a new spec workflow |
 | `Validate the current spec` | Run validation on the active spec |
 | `Break this design into tasks` | Regenerate tasks from the design doc |
 
-You can also reference the skill by its display name, e.g. `Use Spec Driven to plan user authentication`.
+Or reference it by display name: `Use Spec Driven to plan user authentication`.
+
+**Plan mode vs build mode:** Works in both. Plan mode generates the spec for review before writing; build mode writes files directly. Implementation scripts (`spec-exec.sh`, `spec-loop.sh`) run from your terminal.
 
 All generated spec files live in `.codex/specs/<feature-name>/` when running under Codex.
 

docs/getting-started/installation.md

@@ -70,6 +70,32 @@ You can also reference the skill by its display name, e.g. `Use Spec Driven to p
 
 Under Codex, spec files are written to `.codex/specs/<feature-name>/`.
 
+### Plan Mode vs Build Mode
+
+Codex supports two execution modes. The plugin works in both:
+
+**Plan Mode (`codex --plan`)**
+
+- The agent generates the full spec content (requirements, design, tasks)
+- Codex presents it as a plan for review — no files are written yet
+- Review the spec, then approve to apply it in build mode
+- Use this when you want to see what the spec would look like before committing
+
+**Build Mode (`codex` default)**
+
+- The agent generates and writes spec files directly to `.codex/specs/`
+- Implementation scripts (`spec-exec.sh`, `spec-loop.sh`) must be run from your terminal, not inside Codex
+- Use this when you want the spec created immediately and are ready to implement
+
+**Key differences from Claude Code:**
+
+| Feature | Claude Code | Codex |
+|---------|-------------|-------|
+| Spec generation | Writes files directly | Writes files in build mode; plans in plan mode |
+| Task sync | Syncs to Claude Code todo system | No native todo sync; tasks live in `tasks.md` |
+| Execution | `/spec-exec` and `/spec-loop` slash commands | Run `spec-exec.sh` / `spec-loop.sh` from terminal |
+| Spec directory | `.claude/specs/` | `.codex/specs/` |
+
 ## Next steps
 
 - Follow the [Quick start](quick-start.md) to create your first spec