Codex adapter split + hook enforcement port + output gating

.github/workflows/release.yml

@@ -29,7 +29,8 @@ jobs:
         id: version
         run: |
           PLUGIN_VERSION=$(jq -r '.version' .claude-plugin/plugin.json)
-          LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null | sed 's/^v//' || echo "0.0.0")
+          LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0")
+          LATEST_TAG=${LATEST_TAG#v}
 
           echo "plugin=$PLUGIN_VERSION latest_tag=$LATEST_TAG"
 

.gitignore

@@ -30,3 +30,6 @@ dist/
 *.log
 *.tmp
 .worktrees
+docs*
+codex/docs/
+codex/*.md

AGENTS.md

@@ -0,0 +1,43 @@
+# Devkit For Codex
+
+devkit is a deterministic workflow engine. In this repo, treat the YAML workflow and MCP state as the source of truth: start a workflow, execute only the current step, report the step result, then advance.
+
+## Workflow Discipline
+
+- Use `devkit_start` to begin a workflow and `devkit_advance` to move to the next step.
+- Do not skip, reorder, or merge workflow steps unless the engine returns a branch/loop transition that does so.
+- For command steps, do not run the command yourself. Call `devkit_advance`; the engine owns command execution.
+- For prompt steps, do the requested work, summarize the result as the step output, then call `devkit_advance`.
+- For loop steps, keep the iteration small and use `.devkit/scratchpads/current.md` when the step asks for it.
+- If an active workflow exists, finish or explicitly stop it before starting a different workflow.
+
+## Tool Mapping
+
+- Claude `Bash` maps to Codex shell execution.
+- Claude `Read`, `Grep`, and `Glob` map to shell reads, `rg`, and file inspection.
+- Claude `Edit` and `Write` map to `apply_patch` for manual edits.
+- Claude `Agent` and `Task` map to Codex subagents when the current environment exposes them; otherwise use external CLI runners or stop and report that model-diverse dispatch is unavailable.
+- Claude `WebFetch` and `WebSearch` map to Codex web tools only when browsing is available and allowed.
+
+## Enforcement Notes
+
+Claude Code installs lifecycle hooks from `hooks/hooks.json` and can hard-block out-of-step tools. Codex-specific lifecycle hooks, prompt bridges, and config are planned for the separate `devkit-codex` adapter, which points Codex at this repo's MCP engine once released. Follow the same workflow policy voluntarily here, and rely on Codex sandbox/approval boundaries plus the MCP engine for stateful workflow control.
+
+Hard guarantees that still hold under Codex:
+
+- The MCP engine controls step order.
+- Command steps execute inside the engine.
+- Session state, branches, loops, gates, and reports remain engine-owned.
+
+Guarantees that are adapter-owned under Codex:
+
+- Blocking arbitrary shell/edit tool use during hard prompt steps.
+- Running post-tool validation automatically after every edit or command.
+- Blocking assistant stop while a workflow is incomplete.
+- Validating subagent completion through a host lifecycle event.
+
+## Repo Boundaries
+
+- Keep Claude packaging in `.claude-plugin/`, `mcpb/`, and `hooks/` working.
+- Keep Codex-specific integration in the separate `devkit-codex` repository once it is released, unless the change is shared engine behavior.
+- Do not hand-edit generated binaries or bundled release artifacts.

CLAUDE.md

@@ -2,16 +2,16 @@
 
 Navigation map for Claude Code working in this repo. Anchor-style, not narrative — keep it short. `pr-ready`'s doc-check targets this file, so stale entries get caught at PR time.
 
-devkit is a Claude Code plugin: deterministic YAML workflow engine, thin-dispatcher skills, enforcement hooks, multi-agent consensus.
+devkit is a Claude Code plugin: deterministic YAML workflow engine, dispatcher and capability skills, enforcement hooks, multi-agent consensus.
 
 ## Layout
 
 | Path | What | Grep here for |
 |---|---|---|
-| `skills/` | 38 SKILL.md dispatchers | Skill descriptions; what triggers each workflow |
+| `skills/` | 38 SKILL.md skills (engine dispatchers + capability tools) | Skill descriptions; what each skill triggers (workflow or direct exec) |
 | `skills/_principles.yml` | Shared cross-cutting principle config | Rules applied to every skill |
 | `skills/creating-workflows/` | Workflow YAML schema reference | Step types, `parallel:`/`branch:`/`loop:`/`expect:` semantics |
-| `workflows/` | 21 YAML workflow definitions | What each skill actually runs |
+| `workflows/` | 22 YAML workflow definitions | What each skill actually runs |
 | `src/engine/engine.go` | Go workflow executor | How `parallel: [ids]` skips-then-fans-out (`parallelChildren`), branch eval, loop gates |
 | `src/engine/workflow.go` | Workflow struct + YAML parsing | Step field definitions |
 | `src/cmd/guard.go` | Hook gatekeeper | What Bash/Edit/etc. is allowed per step type + enforce level |
@@ -40,7 +40,8 @@ devkit is a Claude Code plugin: deterministic YAML workflow engine, thin-dispatc
 
 ## Architectural invariants
 
-- **Workflows are deterministic.** The engine controls step sequencing, loops, branches, and gates — not the model. Skills are thin dispatchers that call `devkit_start` then loop on `devkit_advance` until done.
+- **Workflows are deterministic.** The engine controls step sequencing, loops, branches, and gates — not the model. YAML is parsed once, the graph is fixed, steps run with state persistence and hook enforcement.
+- **Skills come in two flavors.** *Engine-shim skills* (most) are thin dispatchers that call `devkit_start` then loop on `devkit_advance`, delegating to the workflow engine. *Capability skills* (e.g., `skills/scrape/`) are runtime-interpreted prompt templates where the model is the executor — it picks a backend from what's installed, generates shell/script via heredoc, judges output, falls through on failure. Use the capability form when work needs on-the-spot adaptation that pre-compiled YAML can't express (anti-bot arms races, heterogeneous backend outputs, content-judgment branching).
 - **Parallel step pattern.** Steps listed in another step's `parallel: [ids]` are skipped during the sequential walk (see `parallelChildren` in `src/engine/engine.go`) and dispatched concurrently via `runParallel`. Never expect a step that appears in a parallel list to also execute in its sequential position.
 - **Enforce levels gate hook permissions.** `enforce: soft` lets gather/setup steps run `git diff` and other shell work during dispatch; `enforce: hard` blocks them. The gatekeeper logic lives in `src/cmd/guard.go`; see `guard_test.go` for the allow/deny matrix.
 - **Engine binary is separate from the CLI wrapper.** `bin/devkit` is the committed shell wrapper; it execs `devkit-engine` (compiled Go, gitignored). The wrapper handles install/version checks; the engine handles workflow execution.

README.md

@@ -1,14 +1,16 @@
 # Devkit
 
-A deterministic development harness for AI agents. The MCP engine controls workflow execution (step ordering, gates, loops, branches). The agent handles creativity. Every step is enforced, measured, and auditable.
+A deterministic development harness for AI agents. The MCP engine controls workflow execution (step ordering, gates, loops, branches). The agent handles creativity. Every step is tracked, measured, and auditable.
 
-Works with just Claude. Optionally adds Codex and Gemini for multi-agent consensus.
+Works with Claude Code as the original full-enforcement host. Other host adapters can use the same MCP engine and workflows by registering `bin/devkit mcp`; the Codex adapter is distributed separately by `devkit-codex`. Optionally adds Codex and Gemini for multi-agent consensus.
 
 ---
 
 ## Install
 
-### 1. Devkit (required)
+### Claude Code
+
+#### 1. Devkit (required)
 
 ```bash
 /plugin marketplace add 5uck1ess/marketplace
@@ -17,7 +19,7 @@ Works with just Claude. Optionally adds Codex and Gemini for multi-agent consens
 
 Auto-updates are enabled by default. Devkit updates itself when you restart Claude Code.
 
-### 2. Multi-agent plugins (optional)
+#### 2. Multi-agent plugins (optional)
 
 These enable `tri:*` commands (tri-review, tri-debug, tri-security, etc.) to run Claude + Codex + Gemini in parallel.
 
@@ -36,7 +38,7 @@ If plugins aren't installed, the CLI fallbacks work too:
 brew install codex gemini-cli
 ```
 
-### 3. Companion plugins (optional)
+#### 3. Companion plugins (optional)
 
 These handle concerns devkit doesn't — methodology, specialized reviews, and context management. No overlap.
 
@@ -64,7 +66,19 @@ These handle concerns devkit doesn't — methodology, specialized reviews, and c
 /plugin install context-mode@context-mode
 ```
 
-### 4. Optional tools
+### Codex
+
+Codex support lives in the separate `devkit-codex` adapter. That adapter installs Codex-specific hooks/config and points Codex at this repo's MCP server (`bin/devkit mcp`). This repo remains the core workflow engine and shared workflow/skill source of truth.
+
+Manual MCP registration shape for host adapters:
+
+```toml
+[mcp_servers.devkit]
+command = "/absolute/path/to/devkit/bin/devkit"
+args = ["mcp"]
+```
+
+### Optional tools
 
 ```bash
 brew install rtk       # Token optimization (60-90% savings on Bash output)
@@ -165,22 +179,25 @@ devkit-engine probe-local
 
 ## How It Works
 
-Devkit runs as an **MCP server** inside Claude Code. When a workflow starts, the engine takes control:
+Devkit runs as an **MCP server** inside the host agent. Under Claude Code it is packaged as a plugin; other adapters register `bin/devkit mcp` through their host-specific MCP config. When a workflow starts, the engine takes control:
 
 ```
 devkit_start("research", "best Go testing frameworks")
   → Engine creates session, returns Step 1 + condensed principles
-  → Claude executes the step using standard tools
-  → Claude calls devkit_advance(session_id)
+  → Host agent executes the step using standard tools
+  → Host agent calls devkit_advance(session_id)
   → Engine validates, records output, returns Step 2
   → ...repeat until WORKFLOW COMPLETE
 
-Enforcement (runs automatically):
+Claude Code enforcement (runs automatically):
   PreToolUse hook → blocks out-of-step actions during command steps
   Stop hook → prevents session end during active workflows
+
+External adapters:
+  Register the same MCP server and provide host-specific hooks/guardrails.
 ```
 
-**Why MCP?** Claude can't skip steps because the engine controls what comes next. Claude can't call tools that aren't valid for the current step. The engine holds state — Claude doesn't self-report.
+**Why MCP?** The host agent can't skip steps because the engine controls what comes next. The engine holds state — the agent doesn't self-report workflow position. Claude Code additionally blocks invalid tools through hooks; other hosts can add equivalent adapter-side guardrails while still relying on engine-owned command steps.
 
 ---
 
@@ -300,7 +317,7 @@ All agents run in worktree isolation.
 
 ## Coding Rules
 
-Language-specific rules that auto-activate when Claude reads matching files. Installed to `~/.claude/rules/` — rules guide how to write, hooks catch what you missed.
+Language-specific rules that auto-activate when Claude reads matching files. Installed to `~/.claude/rules/` — rules guide how to write, hooks catch what you missed. Other host adapters should load the matching files from `resources/rules/`.
 
 ```bash
 /setup-rules
@@ -337,16 +354,17 @@ MCP Server (bin/devkit mcp — auto-started by plugin)
   │   ├── Command steps → engine executes shell directly ($0 cost)
   │   │   Values passed via $DEVKIT_INPUT / $DEVKIT_OUT_<step_id>
   │   │   env vars — never interpolated into the command string.
-  │   ├── Prompt steps → Claude works, calls devkit_advance when done
+  │   ├── Prompt steps → host agent works, calls devkit_advance when done
   │   ├── Loop with gate → run, verify, keep or revert
   │   ├── Branch → case-insensitive word-boundary match → goto
-  │   └── Parallel → Agent tool dispatch (Claude/Codex/Gemini)
+  │   └── Parallel → host subagent/external runner dispatch
   └── Principles injected per step (~120 tokens, not full skill files)
 
 Enforcement:
-  ├── MCP tool scoping — Claude can only call devkit_advance to progress
-  ├── PreToolUse hook — exit 2 blocks tools during command steps
-  └── Stop hook — blocks session end during active workflows
+  ├── MCP state — host agent can only progress by calling devkit_advance
+  ├── Claude Code: PreToolUse hook exits 2 to block invalid tools
+  ├── Claude Code: Stop hook blocks session end during active workflows
+  └── External adapters: host-specific hooks/proxies enforce what their host exposes
 
 Terminal usage (devkit workflow <name> "<description>"):
   ├── Subprocess runners for Codex/Gemini CLI

devkit.mcpb.sources.json

@@ -2,7 +2,7 @@
   "mcpb/launcher/main.go": "ad2ce60992bcff323663ac31a63dfae93e782c8556043be8b77ece3b874ade36",
   "mcpb/launcher/go.mod": "7f2e8c3f695fe8cbe8cafa7eb9a269e8d0e5141023f2ea20ef5fc7cbd2f22bc2",
   "mcpb/launcher/main_test.go": "b723d82d0ce371a6c46eb062a1a312cf6aaaf306ef7edf40f3e35972cc4b153f",
-  "mcpb/manifest.json": "b7d68aed66f89e2c2f7b78faa8ea43bcccfe771a47d9c7c3d267095459ceaab5",
+  "mcpb/manifest.json": "e1cf2fb068b915f51bfe179349b2a10f0079445f0ca37c0e0a96e8476f3994c9",
   "mcpb/server/devkit": "3833a48a67dfb8d9db7e1513617c0b1df5d7ebb6bf0c3023c60ab048ed63002f",
-  "mcpb/server/devkit.exe": "92d489e463ea2779d5b7e8008812319ba4e06cc2a7694df926e060236ee2384e"
+  "mcpb/server/devkit.exe": "13e8f43d946ff43dd28d85a4c06d55814a8d534e2628e7721d6e3b6d716d3026"
 }

mcpb/manifest.json

@@ -1,19 +1,25 @@
 {
   "manifest_version": "0.3",
   "name": "devkit-engine",
-  "version": "2.1.19",
+  "version": "2.1.29",
   "description": "devkit MCP engine launcher — POSIX proxies to bin/devkit, Windows spawns a native PE stub to bypass CreateProcess + CVE-2024-27980 constraints",
-  "author": { "name": "5uck1ess" },
+  "author": {
+    "name": "5uck1ess"
+  },
   "server": {
     "type": "binary",
     "entry_point": "server/devkit",
     "mcp_config": {
       "command": "${__dirname}/server/devkit",
-      "args": ["mcp"],
+      "args": [
+        "mcp"
+      ],
       "platform_overrides": {
         "win32": {
           "command": "${__dirname}/server/devkit.exe",
-          "args": ["mcp"]
+          "args": [
+            "mcp"
+          ]
         }
       }
     }

skills/adr/SKILL.md

@@ -20,15 +20,15 @@ If the user hasn't specified, ask one question: "What decision are you documenti
 ## Step 2: Check Existing ADRs
 
 ```bash
-mkdir -p docs/adr
-ls docs/adr/ 2>/dev/null | grep -oE '^[0-9]+' | sort -n | tail -1
+mkdir -p .devkit/docs/adr
+ls .devkit/docs/adr/ 2>/dev/null | grep -oE '^[0-9]+' | sort -n | tail -1
 ```
 
 Add 1 to the highest number found, zero-padded to 4 digits. If no output, the directory is empty — start at `0001`.
 
 ## Step 3: Write the ADR
 
-Create `docs/adr/NNNN-short-title.md`:
+Create `.devkit/docs/adr/NNNN-short-title.md`:
 
 ```markdown
 # NNNN. Short Decision Title

skills/doc-gen/SKILL.md

@@ -5,7 +5,7 @@ description: Generate documentation for code — use when asked to document a mo
 
 # Documentation Generation
 
-Deterministic doc generation. Analyze target → generate via the documenter subagent → write to docs/ or specified path.
+Deterministic doc generation. Analyze target → generate via the documenter subagent → write to a requested non-repo path or `.devkit/docs/`.
 
 ## Invoke
 

skills/health/SKILL.md

@@ -11,12 +11,16 @@ Report on devkit installation health and available capabilities.
 
 ### Plugins
 
+Claude Code plugin checks:
+
 ```bash
 echo "=== Plugin Status ==="
 echo -n "codex plugin: " && (/codex:status >/dev/null 2>&1 && echo "installed" || echo "not installed")
 echo -n "gemini plugin: " && (/gemini:status >/dev/null 2>&1 && echo "installed" || echo "not installed")
 ```
 
+Under non-Claude hosts, report Claude plugin status as "not applicable" and check MCP config plus external CLIs instead.
+
 ### Devkit Engine
 
 Use the `devkit_status` tool to check workflow progress.
@@ -109,6 +113,7 @@ List all skills from `skills/` directory, marking which ones need external CLIs:
 ## Rules
 
 - Check actual CLI availability with `command -v`, not just PATH
+- If running under Codex, do not call Claude slash commands such as `/codex:status`; mark Claude plugin checks as not applicable
 - Report versions where possible
 - Clearly indicate which features work without external CLIs
 - Show tri:* as "partial" if some but not all CLIs are present

skills/mega-pr/SKILL.md

@@ -20,14 +20,14 @@ description: >-
 
 # Mega PR Review
 
-Run `/devkit:tri-review` and `/pr-review-toolkit:review-pr` simultaneously for maximum review coverage.
+Run `/devkit:tri-review` and `/pr-review-toolkit:review-pr` simultaneously for maximum review coverage when those skills/plugins are available. Under non-Claude hosts, run devkit's tri-review MCP workflow and any available external review command; if `pr-review-toolkit` is not installed in the host, report that part as unavailable instead of fabricating results.
 
 ## Step 1: Launch Both Reviews
 
 **[PARALLEL]** — invoke both in a single message using the Skill tool:
 
-1. `Skill: devkit:tri-review` — dispatches Claude + Codex + Gemini reviewers
-2. `Skill: pr-review-toolkit:review-pr` — dispatches specialized aspect reviewers (silent-failure-hunter, type-design-analyzer, test-analyzer, code-reviewer, etc.)
+1. `Skill: devkit:tri-review` — dispatches available model-diverse reviewers
+2. `Skill: pr-review-toolkit:review-pr` — dispatches specialized aspect reviewers when the Claude plugin is installed (silent-failure-hunter, type-design-analyzer, test-analyzer, code-reviewer, etc.)
 
 Pass any user-provided arguments (custom prompt, specific files) to both skills unchanged.
 

skills/onboard/SKILL.md

@@ -5,7 +5,7 @@ description: Generate a codebase onboarding guide — use when asked to explain
 
 # Codebase Onboarding
 
-Deterministic onboarding guide generation. Analyze structure → architect via the researcher subagent → write guide to `docs/ONBOARDING.md`.
+Deterministic onboarding guide generation. Analyze structure → architect via the researcher subagent → write guide to `.devkit/docs/ONBOARDING.md`.
 
 ## Invoke
 

skills/pr-ready/SKILL.md

@@ -38,7 +38,7 @@ Then follow each step the engine returns. Call `devkit_advance` after completing
 3. **lint** — runs linter, fixes violations, loops until clean
 4. **test** — runs test suite, fixes failures, loops until passing
 5. **security** — scans for hardcoded secrets, injection, XSS, traversal, insecure deps
-6. **doc-check** — classifies the diff (feature/bugfix/breaking/internal/docs-only) and decides per-file whether README, ROADMAP, CLAUDE.md, docs/, `skills/*/SKILL.md`, plugin.json, or `workflows/*.yml` need updates. Applies mechanical edits directly (moving roadmap bullets, adding command rows, syncing SKILL.md step lists); flags ambiguous updates as `[!]` in the output checklist. Commits applied edits with `docs: update ...` so they land in the PR alongside the code. CHANGELOG.md is intentionally skipped — it is managed by the release pipeline. Runs **before** `changelog` so any doc commit it creates is captured in the PR description.
+6. **doc-check** — classifies the diff (feature/bugfix/breaking/internal/docs-only) and decides per-file whether README, ROADMAP, CLAUDE.md, `skills/*/SKILL.md`, plugin.json, or `workflows/*.yml` need updates. Applies mechanical edits directly (moving roadmap bullets, adding command rows, syncing SKILL.md step lists); flags ambiguous updates as `[!]` in the output checklist. Commits applied edits with `docs: update ...` so they land in the PR alongside the code. CHANGELOG.md is intentionally skipped — it is managed by the release pipeline. Runs **before** `changelog` so any doc commit it creates is captured in the PR description.
 7. **changelog** — generates entry from git diff (now includes any doc-check commits)
 8. **create-pr** — pushes branch, creates PR via gh pr create with title/summary/changelog/test plan
 9. **monitor** — waits for CI, classifies reviewer comments (code_fix/style_nit/question/false_positive/out_of_scope), applies fixes, replies, pushes, loops until all resolved