From 5f1c050eb8a0a8dc7beb89bd7eb765686c476d04 Mon Sep 17 00:00:00 2001
From: Tym Rabchuk <tymrabchuk@gmail.com>
Date: Tue, 19 May 2026 16:03:23 -0400
Subject: [PATCH] docs: clarify Codex workflow triggers

---
 README.md                     | 43 +++++++++++++++++++++++++++++++++--
 hooks/codex-slash-commands.sh | 17 ++++++++++++++
 test/hooks_test.sh            |  7 ++++++
 3 files changed, 65 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 48d7cfc..fae6528 100644
--- a/README.md
+++ b/README.md
@@ -23,6 +23,44 @@ By default this writes:
 - `~/.codex/config.toml`
 - `~/.codex/hooks.json`
 
+After installing, start a new Codex session and run:
+
+```text
+/hooks
+```
+
+Codex requires first-run review for new non-managed command hooks before they
+can run. Review the devkit-codex hook commands, confirm that the paths point to
+your local `devkit` and `devkit-codex` checkouts, then trust them.
+
+For less fragile hook commands, install with an absolute devkit path:
+
+```sh
+./install.sh --devkit "$(cd ../devkit && pwd)"
+```
+
+Start Codex from a git repository when testing workflows. The core devkit MCP
+server expects to start inside a project repo; a plain directory will make MCP
+startup fail before `devkit_start` and `devkit_advance` are exposed.
+
+Codex CLI handles `/` commands itself, so unknown slash commands such as
+`/feature` may be rejected before hooks can inspect them. To run a devkit
+workflow in Codex, use the text trigger form:
+
+```text
+devkit feature: add a tiny no-op test file
+```
+
+```text
+devkit workflow tri-security: audit this repository
+```
+
+Natural-language prompts can also dispatch common workflows:
+
+```text
+please run a security audit
+```
+
 Use `--config` and `--hooks` to target alternate files, which is useful for
 testing:
 
@@ -51,8 +89,9 @@ non-devkit hooks files untouched.
 - Registers the core devkit MCP server with Codex as `mcp_servers.devkit`.
 - Enables Codex hooks in `config.toml`.
 - Generates a devkit-owned `hooks.json` with Codex lifecycle hooks.
-- Bridges `/feature`, `/bugfix`, `/tri-review`, `/health`, and other devkit
-  workflow prompts into MCP-driven workflow instructions.
+- Bridges devkit workflow prompts such as feature requests, bugfixes,
+  tri-review, health checks, and security audits into MCP-driven workflow
+  instructions.
 - Maps devkit agent definitions to Codex `explorer` or `worker` subagent
   guidance.
 
diff --git a/hooks/codex-slash-commands.sh b/hooks/codex-slash-commands.sh
index ee23f73..a6094cb 100755
--- a/hooks/codex-slash-commands.sh
+++ b/hooks/codex-slash-commands.sh
@@ -101,6 +101,23 @@ if [[ -n "$RAW_NAME" ]]; then
   exit 0
 fi
 
+case "$FIRST_LINE" in
+  devkit\ workflow\ *:*)
+    RAW_NAME=${FIRST_LINE#devkit workflow }
+    NAME=${RAW_NAME%%:*}
+    ARGS=${RAW_NAME#*:}
+    ARGS=$(trim_left "$ARGS")
+    dispatch_target "$NAME" "$ARGS" && exit 0
+    ;;
+  devkit\ *:*)
+    RAW_NAME=${FIRST_LINE#devkit }
+    NAME=${RAW_NAME%%:*}
+    ARGS=${RAW_NAME#*:}
+    ARGS=$(trim_left "$ARGS")
+    dispatch_target "$NAME" "$ARGS" && exit 0
+    ;;
+esac
+
 PROMPT_LC=$(printf '%s' "$PROMPT" | tr '[:upper:]' '[:lower:]')
 case "$PROMPT_LC" in
   *"build a feature"* | *"new feature"* | *"add a feature"* | *"implement "*) dispatch_target "feature" "$PROMPT" && exit 0 ;;
diff --git a/test/hooks_test.sh b/test/hooks_test.sh
index 5e26df7..71fad5e 100755
--- a/test/hooks_test.sh
+++ b/test/hooks_test.sh
@@ -92,6 +92,13 @@ else
   fail "slash bridge natural-language trigger failed"
 fi
 
+explicit_out=$(jq -n --arg cwd "$DEVKIT_ROOT" '{hook_event_name:"UserPromptSubmit",cwd:$cwd,prompt:"devkit feature: tiny no-op"}' | DEVKIT_ROOT="$DEVKIT_ROOT" bash "$ROOT/hooks/codex-slash-commands.sh" 2>/dev/null || true)
+if printf '%s' "$explicit_out" | jq -e '.hookSpecificOutput.additionalContext | contains("workflow \"feature\"")' >/dev/null; then
+  pass "slash bridge covers explicit devkit trigger"
+else
+  fail "slash bridge explicit devkit trigger failed"
+fi
+
 unset_out=$(jq -n '{hook_event_name:"UserPromptSubmit",cwd:"/tmp",prompt:"/feature tiny no-op"}' | env -u DEVKIT_ROOT bash "$ROOT/hooks/codex-slash-commands.sh" 2>/dev/null || true)
 if [[ -z "$unset_out" ]]; then
   pass "slash bridge no-ops without DEVKIT_ROOT"