Build Your First Plugin

This tutorial walks through the F111 plugin developer kit flow:

1. Scaffold a new plugin repository with awf plugin init
2. Run the generated tests
3. Install the plugin locally
4. Enable it in AWF
5. Run the generated demo workflow

This path is for the MVP plugin scaffold: --kind operation.

Before You Start#

You need:

• AWF installed and available on your PATH
• Go installed
• make installed

Check your environment:

awf --version
go version
make --version

1. Scaffold the Plugin Repository#

Create a new plugin distribution named awf-plugin-example:

awf plugin init awf-plugin-example --kind operation
cd awf-plugin-example

The generated repository includes:

• main.go - plugin entry point and example operation
• main_test.go - operation and manifest validation tests
• plugin.yaml - runtime manifest consumed by AWF
• Makefile - local development, packaging, and checksum targets
• examples/demo.yaml - runnable example workflow
• .github/workflows/release.yml - GitHub Releases packaging workflow
• README.md - generated authoring reference for the scaffold

2. Understand the Two Names#

F111 distinguishes the installable distribution name from the runtime plugin id:

• Distribution name: awf-plugin-example
• Runtime plugin id: example

You install and enable the distribution, but workflows call the runtime operation name:

operation: example.echo

The runtime id lives in plugin.yaml as the manifest name.

3. Run the Generated Checks#

Run the generated test and build loop:

make test
make build

Optional local quality checks:

make lint

4. Install and Enable the Plugin Locally#

Copy the generated binary and manifest into your local AWF plugin directory:

make install-local
awf plugin enable awf-plugin-example

Verify that AWF can see the generated operation:

awf plugin list --operations

You should see an example.echo operation owned by the example plugin.

5. Run the Demo Workflow#

Execute the generated workflow:

awf run examples/demo.yaml

The demo calls example.echo and should complete successfully.

6. Package the Plugin for Releases#

Build an installer-compatible archive and checksum file:

make package
make checksums

The generated GitHub Actions workflow publishes release assets using the naming convention AWF expects for awf plugin install owner/repo[@version].

What the MVP Scaffold Supports#

Today, awf plugin init supports one scaffold kind:

• operation

Future kinds such as canonical-port, adapter, validator, step-type, and event-listener are planned but not yet generated by the CLI.

Next Steps#

• Read Plugins for manifest fields, SDK APIs, packaging rules, and advanced authoring topics.
• Read CLI Commands for the exact awf plugin init flags.
• Read the generated README.md in your scaffolded repository for the command sequence and release workflow that ships with the template.