@lukstei/wf 0.1.0

package/hooks/claude-codex-hooks.json

@@ -0,0 +1,38 @@
+{
+	"hooks": {
+		"SessionStart": [
+			{
+				"matcher": "startup|resume|clear|compact",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/wf.cjs\" hook pre",
+						"timeout": 10
+					}
+				]
+			}
+		],
+		"UserPromptSubmit": [
+			{
+				"hooks": [
+					{
+						"type": "command",
+						"command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/wf.cjs\" hook pre",
+						"timeout": 10
+					}
+				]
+			}
+		],
+		"Stop": [
+			{
+				"hooks": [
+					{
+						"type": "command",
+						"command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/wf.cjs\" hook stop",
+						"timeout": 10
+					}
+				]
+			}
+		]
+	}
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+	"name": "@lukstei/wf",
+	"version": "0.1.0",
+	"description": "Deterministic skill workflow runner for AI agents",
+	"license": "MIT",
+	"author": "Lukas Steinbrecher",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/lukstei/wf.git"
+	},
+	"bugs": {
+		"url": "https://github.com/lukstei/wf/issues"
+	},
+	"homepage": "https://github.com/lukstei/wf#readme",
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"dist",
+		"hooks",
+		"skills",
+		"rules",
+		".claude-plugin",
+		".codex-plugin",
+		".agents",
+		"AGENTS.md",
+		"README.md",
+		"plugin.json"
+	],
+	"bin": {
+		"wf": "./dist/wf.cjs"
+	},
+	"scripts": {
+		"build": "node esbuild.config.js",
+		"typecheck": "tsc --noEmit",
+		"check": "biome check --write",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"test:update": "vitest run -u",
+		"verify": "npm run test && npm run typecheck"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.5.14",
+		"@types/node": "^22.20.3",
+		"esbuild": "^0.28.2",
+		"typescript": "^7.0.2",
+		"vitest": "^3.0.0"
+	},
+	"dependencies": {
+		"mdast-util-from-markdown": "^2.0.3"
+	},
+	"allowScripts": {
+		"esbuild@0.28.2": true,
+		"fsevents@2.3.3": true
+	}
+}

package/plugin.json

@@ -0,0 +1,4 @@
+{
+	"name": "wf",
+	"description": "Deterministic skill workflow runner for AI agents"
+}

package/rules/AGENTS.md

@@ -0,0 +1,34 @@
+# Workflow Runner (`wf`) Guidelines
+
+These rules govern agent behavior whenever the `wf` plugin or an active workflow is present.
+
+---
+
+## 1. Strict Step-by-Step Execution
+
+- **Execute Only the Active Step:** When a step instruction is injected into context, execute that specific step and nothing else.
+- **Never Jump Ahead:** Do not anticipate or execute subsequent steps, future phases, or follow-on actions ahead of time.
+- **Conclude Immediately:** Stop and complete your response as soon as the current step's task is finished. The workflow engine will automatically inject the next step.
+
+## 2. Never Read Raw Workflow Files
+
+- **Ban on Reading Workflow Files:** Do not use `view_file`, `grep_search`, `read_url_content`, or shell commands to view raw workflow files (`.md` / `.json`) or plugin `SKILL.md` definitions during execution.
+- **Why:** The workflow runner already compiles, tracks, and injects each step with its relevant context into your prompt. Reading raw workflow files clutters the context window, duplicates state, and leads to hallucinated out-of-order execution.
+
+## 3. Condition Step Decision Format
+
+- **Evaluation:** When injected with a condition evaluation step, evaluate whether the stated condition is true or false using appropriate read-only inspection tools if necessary.
+- **Strict Decision Token:** Always end your response with strictly either `[DECISION: YES]` or `[DECISION: NO]`.
+- **Placement:** The decision token must appear at the very end of your response so the runner can deterministically parse the branch choice and advance the workflow.
+
+## 4. Workflow Runner Commands
+
+Users and agents interact with workflows via slash commands:
+
+| Command | Description |
+| :--- | :--- |
+| `/wf <workflow-file>` | Start and run a workflow from a Markdown (`.md`) or JSON (`.json`) file. |
+| `/wf-show [<workflow-file>]` | Display workflow status, Mermaid diagram, and current position (or visualize a file). |
+| `/wf-next` | Advance and execute the next step when a workflow is paused. |
+| `/wf-stop` | Abort and reset the currently active or paused workflow. |
+| `/wf-help` | Display usage instructions and supported runner commands. |

package/skills/wf/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: wf
+description: Run a workflow from a Markdown or JSON file (/wf <workflow-file>)
+disable-model-invocation: true
+---
+
+The wf command starts a workflow and will be intercepted by the workflow runner hook.
+
+Usage:
+  /wf <workflow-file> - Run a workflow from a Markdown (.md) or JSON (.json) file.

package/skills/wf-help/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: wf-help
+description: Show workflow runner commands and usage guide
+disable-model-invocation: true
+---
+
+The wf-help command will be intercepted by the workflow runner hook.
+
+Usage:
+  /wf-help - Display available workflow runner commands.

package/skills/wf-next/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: wf-next
+description: Execute the next step in a paused workflow
+disable-model-invocation: true
+---
+
+The wf-next command will be intercepted by the workflow runner hook.
+
+Usage:
+  /wf-next - Advance and execute the next step of a paused workflow.

package/skills/wf-show/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: wf-show
+description: Visualize workflow status, diagram, and current position (/wf-show [<workflow-file>])
+disable-model-invocation: true
+---
+
+The wf-show command visualizes a workflow and will be intercepted by the workflow runner hook.
+
+Usage:
+  /wf-show                   - Show current workflow status, diagram, and active step.
+  /wf-show <workflow-file>   - Visualize a specific workflow from a Markdown (.md) or JSON (.json) file.

package/skills/wf-stop/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: wf-stop
+description: Stop and reset the active workflow
+disable-model-invocation: true
+---
+
+The wf-stop command will be intercepted by the workflow runner hook.
+
+Usage:
+  /wf-stop - Stop and reset the currently active or paused workflow.