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.

v0.1.1 — Releases · Feedback thread

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                    # interactive tool picker
# owf init --tools cursor   # CI / non-interactive

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

One composite action (the security primitive we ship)

| Action | What it does | | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | an-lee/open-workflow/actions/[email protected] | Gates workflow execution by GitHub author role and bot identity. The one security primitive. |

Write path (v0.2): the agent runs git and gh on the runner with GITHUB_TOKEN / GH_TOKEN. Recipes pass env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} on the agent step. Branch protection on the default branch and token scope limits are the platform safety boundary.

Agent jobs also use a per-repo setup-agent-runtime file (written by /owf:bootstrap under .github/actions/setup-agent-runtime/) to run npm ci — it is not a published composite from this repo.

Agent runbook (framework-side agent guidance)

Workflow agents receive a short reference in each assembled TASK pointing at .<engine>/skills/agent-runbook/SKILL.md (installed by owf init / owf update from the canonical skills/agent-runbook/SKILL.md). The runbook covers environment setup, duplicate-PR preflight, branch/PR conventions, gh write patterns, self-verification, and communication style — so prompts stay focused on the recipe while conventions stay in one place.

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) |

~15 recipes (the catalog)

Ready-to-install workflow files covering:

• Daily work — /agent <task>, /fix on a failing PR, /ask for repo Q&A, /nit for style nitpicks, AI code review
• Scheduled maintenance — CI doctor, Dependabot bundler, test improver, docs updater, sub-issue closer
• Quality & insight — code simplifier, perf improver, daily repo status, duplicate-code detector
• Triage — issue labeler + triage comment

See recipes/ or run owf list for the full catalog. To refactor a workflow file locally, use /owf:improve (not a CI recipe — GITHUB_TOKEN cannot push .github/workflows/*).

How it works

The safety story

Agent runs on GitHub Actions runner
          │
          ▼
Reads repo context (AGENTS.md, open PRs, recent commits)
          │
          ▼
Does work (edits files, runs tests, etc.)
          │
          ▼
Agent runs git + gh (GH_TOKEN on agent step)
  → commits to branch agent/<run-id>-<slug>
  → opens or updates PR via gh pr create
  → 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

Working memory

Agents use auditable repository state by default: AGENTS.md (standing instructions), open issues and pull requests, recent commits, CI failures, and per-run summary artifacts. Scheduled maintenance workflows gather bounded repo context before each run and skip work when an open PR already covers the same change. An optional .agent-memory/ scratchpad (cache-only, opt-in via AGENT_MEMORY_SCRATCHPAD=1) is not required.

Docs

• Getting started — end-to-end walkthrough
• Recipes — catalog reference with copy-paste examples
• Skills — what each /owf:* command does
• Actions — gate-by-role reference and v0.2 write path
• Conventions — branch naming, memory layout, safety story
• Positioning — permissive workflow, strict platform; setup checklist
• Migrating v0.1 → v0.2 — drop agent-pr and github-script writes
• Comparison — vs gh-aw, Copilot Coding Agent, Cursor Background Agents
• Releasing — npm, action tags, and GitHub Releases
• Dogfooding — validate workflows and smoke-test this repo

Design philosophy

Permissive workflow, strict platform — thin YAML and a capable agent on the runner; branch protection, token scope, and PR review do the safety work. docs/positioning.md explains the principle, comparison to alternatives, and the GitHub setup checklist.

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

License

MIT