open-workflow

A lightweight agentic workflow framework for GitHub Actions.

The agent does real engineering work — edits files, runs tests, fixes the build — on a branch. It opens a PR. You merge when you're happy. That's the entire safety model.

You:   /agent fix the failing integration test
AI:    [runs on GitHub Actions]
       [checks out repo, runs agent CLI, pushes to branch agent/42-issue-fix]
       [opens PR #43: "[agent] Fix failing integration test"]
You:   [reviews diff, merges]

No compiler. No lock files. No proprietary frontmatter. Just plain GitHub Actions YAML that you can read, edit, and own.

Get started in three commands

1. Install the CLI

npm install -g @an-lee/owf

2. Initialise your repo — installs skills and slash commands into your AI tool(s)

cd your-repo
owf init

3. Bootstrap a maintenance suite — scan the repo and install fitted workflows

/owf:bootstrap

That's it. Your repo now has agentic workflows that work 24/7.

What it ships

Two composite actions (the runtime surface we own)

| Action | What it does | |---|---| | open-workflow/[email protected] | Gates workflow execution by GitHub author role and bot identity. The one security primitive we provide. | | open-workflow/[email protected] | Commits agent changes to a working branch (agent/<run-id>-<slug>) and opens or updates a PR. The only write path. |

Five slash commands (the coaching layer)

| Command | What it does | |---|---| | /owf:bootstrap | Scan repo, install a fitted starter suite of agentic workflows | | /owf:new | Design a fresh agentic workflow from a description | | /owf:audit | Review existing workflows against open-workflow conventions | | /owf:improve | Refactor an existing workflow | | /owf:explore | Think about what work to automate (read-only) |

~12 recipes (the catalog)

Ready-to-install workflow files covering:

• Daily work — /agent <task>, /fix on a failing PR, AI code review
• Scheduled maintenance — CI doctor, Dependabot bundler, test improver, docs updater
• Quality & insight — code simplifier, perf improver, daily repo status
• Triage — issue labeler + triage comment
• Meta — /optimize a workflow

See recipes/ or run owf list for the full catalog.

How it works

The safety story

Agent runs on GitHub Actions runner
          │
          ▼
Reads .agent-memory/ (cached, per-repo markdown notes)
          │
          ▼
Does work (edits files, runs tests, etc.)
          │
          ▼
open-workflow/[email protected]
  → commits to branch agent/<run-id>-<slug>
  → opens or updates PR
  → NEVER touches main
          │
          ▼
Human reviews and merges

Branch protection on main is your backstop. GITHUB_TOKEN (the only credential any recipe uses) cannot push to .github/workflows/*. The worst-case outcome of a misbehaving agent is a weird PR you don't merge.

Conversation continuation

Issue #100: "Add a dark-mode toggle"
  └─ /agent let's build this
       → creates branch agent/42-issue-100
       → opens PR #101

PR #101 comments:
  └─ /agent rename the button to Submit
       → pushes new commit to agent/42-issue-100
       → PR #101 updated, no new PR opened
  └─ /agent fix the failing test
       → same branch, new commit, PR #101 updated
  └─ You merge → done

Agent memory

A persistent context that survives between runs. Stored as plain markdown files under .agent-memory/, cached via actions/cache@v4, scoped per repo. The agent reads its prior notes before each run and appends new learnings after. Commit a snapshot to a memory branch for auditability.

Docs

• Getting started — end-to-end walkthrough
• Recipes — catalog reference with copy-paste examples
• Skills — what each /owf:* command does
• Actions — gate-by-role and agent-pr reference
• Conventions — branch naming, memory layout, safety story
• Comparison — vs gh-aw, Copilot Coding Agent, Cursor Background Agents
• Releasing — npm, action tags, and GitHub Releases

Design philosophy

→ the agent does real work, not just comments
→ branch + PR is the safety boundary, not output allowlists
→ plain workflows you own, not compiled artifacts we generate
→ lean on GitHub's platform protections, not ours
→ engine-agnostic — bring your own CLI
→ two actions, not twenty

Inspired by OpenSpec's distribution model and githubnext/agentics's workflow taxonomy, built for indie maintainers and small teams.

License

MIT