@lukstei/wf 0.1.0

package/.agents/plugins/wf/hooks.json

@@ -0,0 +1,16 @@
+{
+	"wf": {
+		"PreInvocation": [
+			{
+				"type": "command",
+				"command": "node ./dist/wf.cjs hook pre"
+			}
+		],
+		"Stop": [
+			{
+				"type": "command",
+				"command": "node ./dist/wf.cjs hook stop"
+			}
+		]
+	}
+}

package/.agents/plugins/wf/plugin.json

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

package/.agents/plugins/wf/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/.agents/plugins/wf/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/.agents/plugins/wf/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/.agents/plugins/wf/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/.agents/plugins/wf/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/.agents/plugins/wf/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.

package/.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+	"$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+	"name": "wf-marketplace",
+	"owner": {
+		"name": "Lukas Steinbrecher",
+		"url": "https://github.com/lukstei"
+	},
+	"plugins": [
+		{
+			"name": "wf",
+			"description": "Deterministic skill workflow runner for AI agents",
+			"source": "./",
+			"category": "productivity"
+		}
+	]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+	"name": "wf",
+	"description": "Deterministic skill workflow runner for AI agents",
+	"hooks": "./hooks/claude-codex-hooks.json"
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+	"name": "wf",
+	"description": "Deterministic skill workflow runner for AI agents",
+	"hooks": "./hooks/claude-codex-hooks.json"
+}

package/AGENTS.md

@@ -0,0 +1,12 @@
+- Prefer snapshot testing of a list of assertions
+- Always place workflow state transitions and status mutations in `src/transitions.ts`
+- Run `npm run verify` after each change
+- Keep the code as clean and pure as possible
+  - no unecessary condition checking
+  - no over-defensive programming (instead assert, the precondtions of a function if necessary)
+  - no unecessary optional types
+  - No unecessary exporting of internal types
+  - Especially no unecessary states, always think about how to keep the state minimal
+- Prefer inline types, if the type is not reused
+- Prefer discriminated unions
+- No use of any or unjustified type castings

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lukas Steinbrecher
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,189 @@
+# @lukstei/wf
+
+> Deterministic skill workflow runner for AI agents
+
+[![CI](https://github.com/lukstei/wf/actions/workflows/ci.yml/badge.svg)](https://github.com/lukstei/wf/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![NPM Version](https://img.shields.io/npm/v/@lukstei/wf.svg)](https://www.npmjs.com/package/@lukstei/wf)
+
+> [!NOTE]
+> `wf` is currently in alpha (`v0.1.x`). Expect bugs and breaking changes.
+
+When you give an AI coding agent a multi-step plan, it tries to execute the whole thing at once. It skips tests, hallucinates future steps, and blows past human review points.
+
+`wf` turns Markdown runbooks into step graphs and feeds them to the agent one step at a time. The agent cannot see or run future steps until the current step passes.
+
+Runs in Google Antigravity, Claude Code, and OpenAI Codex.
+
+```mermaid
+flowchart TD
+    A["Markdown runbook (.md)"] --> B["wf compiler"]
+    B --> C["Inject active step"]
+    C --> D["Agent executes step"]
+    D --> E{"Step type"}
+    E -->|"Linear"| F["Advance to next step"]
+    E -->|"Gate"| G["Pause for human approval"]
+    E -->|"Condition"| H["Branch on YES / NO"]
+    F --> C
+    G --> C
+    H --> C
+```
+
+## Goals
+
+- **Skills as workflows:** Turn existing `SKILL.md` files and Markdown runbooks into executable workflows with minimal changes.
+- **Minimal syntax:** Plain Markdown headings, conditions, and human gates. No custom DSL.
+- **Agent does the work:** The model inspects code, runs tools, and evaluates conditions. `wf` only enforces step order and human checkpoints.
+- **Zero infrastructure:** Runs as a self-contained plugin. No server, database, or background daemon.
+
+## Non-goals
+
+- **Full-blown workflow engine:** No heavy orchestration frameworks, distributed graph runners, or complex runtime dependencies.
+
+## How it works
+
+- **One step at a time:** The agent prompt only contains instructions for the active step. Future steps stay hidden.
+- **Explicit branch decisions:** Conditional steps require `[DECISION: YES]` or `[DECISION: NO]` before the graph advances.
+- **Human gates:** Steps marked `## Gate:` pause execution until you run `/wf-next`.
+- **Visual status:** Generates Mermaid diagrams showing the current position in the graph.
+- **Zero runtime dependencies:** Single bundle in `dist/wf.cjs` invoked directly by agent lifecycle hooks.
+
+## Supported environments
+
+| Environment | Slash commands | Lifecycle hooks |
+| :--- | :--- | :--- |
+| Google Antigravity | `/wf`, `/wf-show`, `/wf-next`, `/wf-stop`, `/wf-help` | `PreInvocation`, `Stop` |
+| Claude Code | `/wf`, `/wf-show`, `/wf-next`, `/wf-stop`, `/wf-help` | `SessionStart`, `UserPromptSubmit`, `Stop` |
+| OpenAI Codex | `/wf`, `/wf-show`, `/wf-next`, `/wf-stop`, `/wf-help` | `SessionStart`, `UserPromptSubmit`, `Stop` |
+
+## Installation
+
+### Google Antigravity
+Clone into your global or workspace plugin directory:
+```bash
+git clone https://github.com/lukstei/wf.git ~/.gemini/config/plugins/wf
+```
+
+### Claude Code
+Add the marketplace catalog and install:
+```bash
+/plugin marketplace add lukstei/wf
+/plugin install wf@wf-marketplace
+```
+
+### OpenAI Codex
+Add the marketplace catalog, install, and trust:
+```bash
+codex plugin marketplace add lukstei/wf
+codex plugin install wf
+codex plugin trust wf
+```
+
+## Quickstart
+
+### 1. Write a workflow (`deploy.md`)
+
+```markdown
+# Production Deployment
+
+Ensure all checks pass before deploying.
+
+## 1. Run tests
+Run the test suite:
+`npm run verify`
+
+## 2. If: Did all tests pass?
+
+### Publish
+Publish packages to npm and create GitHub release.
+
+### No
+Stop and report the failures.
+
+## Gate: Confirm release
+Check the files in `dist/`. Ready to publish to production?
+```
+
+### 2. Run in chat
+
+In Antigravity, Claude Code, or Codex:
+
+```text
+/wf deploy.md
+```
+
+| Command | Description |
+| :--- | :--- |
+| `/wf <workflow-file>` | Start a workflow and inject step 1. Supports relative paths, `@path`, or `@[path]`. |
+| `/wf-show [<workflow-file>]` | Display workflow status, Mermaid diagram, and current step. Visualizes a file when provided. |
+| `/wf-next` | Advance and execute the next step when a workflow is paused at a gate. |
+| `/wf-stop` | Stop and reset the active or paused workflow. |
+| `/wf-help` | Display usage instructions and supported runner commands. |
+
+## Syntax
+
+See [docs/SYNTAX.md](docs/SYNTAX.md) for the complete syntax specification, rules, and examples.
+
+### Frontmatter (optional)
+YAML frontmatter at the top of the file configures the workflow name and description:
+```markdown
+---
+name: deploy
+description: Production release workflow
+---
+```
+
+### Workflow Preamble (Context)
+Any text between the H1 title and the first step heading is treated as top-level workflow context. It is injected into every step under `CONTEXT:`:
+```markdown
+# Production Deployment
+
+Ensure DATABASE_URL is pointing to staging replica before running checks.
+All commands must be executed from repository root.
+```
+
+### Steps (`##`)
+Any H2 heading that does not match a keyword (`if`, `gate`) creates a step. Heading numbers or prefixes are supported:
+```markdown
+## 1. Run migrations
+Run `./scripts/migrate.sh` and verify all tables migrate cleanly.
+```
+
+### Conditions (`## If:` / `### No`)
+Condition headings create binary branching points evaluated dynamically by the model:
+- **Condition Instruction**: Body text directly beneath `## If:` tells the agent how to evaluate the condition.
+- **YES Branch (0..N steps)**: Child `###` subheadings are executed when the condition evaluates to YES.
+- **NO Branch**: A child heading `### No` (or `### Else`) is executed when the condition evaluates to NO.
+
+The agent concludes its evaluation with `[DECISION: YES]` or `[DECISION: NO]`:
+
+```markdown
+## 2. If: Any migrations pending?
+Run `npx prisma migrate status` to check the database state.
+
+### Run dry-run
+Run migration dry-run and save output.
+
+### No: Skip verification
+Skip to schema verification.
+```
+
+### Gates (`## Gate:`)
+Pauses execution for human review. Resumes when you run `/wf-next`:
+```markdown
+## Gate: Confirm schema changes
+Review the schema diff above. Run `/wf-next` to continue or `/wf-stop` to abort.
+```
+
+## Development
+
+```bash
+npm install
+npm run verify      # runs tests and tsc
+npm run build       # builds dist/wf.cjs
+npm run test:watch  # test watcher
+```
+
+## License
+
+[MIT](LICENSE) © 2026 Lukas Steinbrecher