Flipt Agents

A collection of Flue agents for the Flipt organization. It's one pnpm-workspace monorepo: each agent is a workflow in workflows/, and they share common infrastructure — the runtime entry (app.ts), model selection (lib/model.ts), CI patterns, and reusable skills / prompts / personas.

The current agents are PR Review and Issue Health Check. Local builds and runs require Node 22.18.0 or newer (the Flue 0.11.1 runtime floor) and pnpm.

Agents

Agent	What it does	How it runs
PR Review (workflows/pr-review.ts)	Reviews a pull request against the target repo's conventions and posts a verdict + findings.	A composite GitHub Action other repos call — see the PR Review agent.
Issue Health Check (workflows/issue-health.ts)	Checks newly opened issues for actionability, missing information, privacy concerns, and existing target-repo labels.	A composite GitHub Action other repos call — see the Issue Health Check agent.

Adding one is cheap — see Adding an agent.

Layout

agents/                       # pnpm workspace root — a fleet of agents
  workflows/
    pr-review.ts              # one file per agent
    issue-health.ts
  skills/
    code-review/SKILL.md      # skills agents register
    issue-health/SKILL.md
  prompts/
    *.md                      # prompt guidance loaded at runtime
  personas/
    *.ts                      # subagents an agent can delegate to
  AGENTS.md                   # docs for agents working ON this repo (not the reviewer's persona)
  actions/
    pr-review/action.yml      # composite actions consuming repos use
    issue-health/action.yml
  examples/
    consumer-workflow.yml     # copy-paste workflows for consuming repos
    issue-health-workflow.yml
    sample-consumer/.agents/  # example per-repo overrides
  app.ts                      # runtime entry (register extra model providers here)
  flue.config.ts              # default target (node)
  .github/workflows/
    pr-review.yml             # dogfoods the action on this repo's PRs

How an agent is built

Every agent here is assembled the same way — PR Review is the worked example:

• Skills are registered on the agent in createAgent({ skills: [...] }), so they are part of the agent, not the payload. Add one: drop skills/<name>/SKILL.md, import it in workflows/pr-review.ts, add it to the skills array.
• Prompts in prompts/*.md are read by the code-review skill on every run (filename order). Drop a file in — it applies to the next PR, no code change.
• Personas in personas/*.ts are registered as subagents, so the reviewer can delegate focused deep-dives (security, correctness, …) on any PR.
• The reviewer's persona and standing rules live in skills/code-review/SKILL.md — that skill is the agent's behavior.
• AGENTS.md documents this repo for any coding agent working on it. Flue auto-discovers it at runtime, so the review process keeps project context, but it is not the reviewer's persona. Per-review context about the code being reviewed comes from the target repo's own AGENTS.md.
• GitHub mutations are deterministic, done by the workflow — not the model. Skills only analyze and return structured data; workflows render comments, post them with gh, and apply any labels from deterministic code paths. (Smaller models can't be trusted to reliably run mutation steps.)
• MCP tools can be attached at runtime: connectMcpServer(url), then pass the connection's tools to init(agent, { tools }). PR Review connects the Flipt docs MCP so it can ground reviews in the documentation.

The payload only ever carries which artifact to inspect (for example prNumber or issueNumber, plus optional repo) — never the skills or prompts.

Subagents / personas

Flue supports subagents via defineAgentProfile({ name, instructions }), registered in createAgent({ subagents: [...] }) and invoked with session.task(text, { agent: 'name' }). There is no markdown auto-discovery for personas (that exists only for skills), so each persona is a small TS module in personas/ exported through personas/index.ts. Add one and add it to that array.

Models

There is no default model and no default provider. Whoever runs an agent picks a provider-qualified model and supplies that provider's credentials. A missing or malformed model fails at startup (lib/model.ts), not mid-review.

Set it with REVIEW_MODEL / ISSUE_HEALTH_MODEL (locally, via .env) or the action's required model input (CI). Credentials always travel through the environment, never through action inputs:

• cloudflare-workers-ai/@cf/moonshotai/kimi-k2.6 — Kimi K2.6 on Cloudflare Workers AI: 262k context, reasoning, vision, tool calling, at $0.95/$4.00 per M input/output tokens. Set CLOUDFLARE_API_KEY (a token with Workers AI → Read) and CLOUDFLARE_ACCOUNT_ID.
• anthropic/claude-sonnet-4-6 — set ANTHROPIC_API_KEY.

Neither needs an app.ts change: Flue resolves both through pi-ai's built-in catalog. Reasoning models work over cloudflare-workers-ai/* because the openai-completions adapter sends max_completion_tokens automatically when the catalog marks a model as reasoning-capable. To use a provider pi-ai doesn't know, register it in app.ts. See actions/pr-review/README.md.

Versioning

Both actions share one repo-level version — they also share app.ts, lib/, the skills, and the Flue runtime, so they ship together. Releases are semver tags (v1.0.0), and package.json holds the declared version. Changes are logged in CHANGELOG.md.

Pick a ref per what you want:

Ref	What you get
@v1	Latest 1.x. Fixes and improved review guidance arrive automatically; no breaking input or credential changes. Recommended.
@v1.0.0	That exact tree, frozen. Fully reproducible.
@main	Unreleased tip. May break without notice.

Because the action carries its skills and prompts along at the pinned ref, pinning an exact tag freezes the review guidance too, not just the code — a repo on @v1.0.0 keeps reviewing against that release's prompts until it moves. @v1 is the middle ground: stable inputs, current guidance.

The public surface semver covers is the actions' inputs and the environment they expect — including which providers and credentials a consumer must supply. Requiring the model input is a breaking change for exactly that reason.

Cutting a release

1. Bump version in package.json and move the heading in CHANGELOG.md.
2. Merge that to main.
3. git tag v1.2.0 && git push origin v1.2.0.

.github/workflows/release.yml then type-checks, tests, and builds the tagged tree, verifies the tag matches package.json, force-moves the v1 alias onto it, and publishes the GitHub release. Nothing ships if validation fails.

The PR Review agent

Reviews a pull request against the target repo's conventions and posts a verdict + findings. It's packaged as a composite GitHub Action other repos call, and connects the Flipt docs MCP (docs.flipt.io/mcp, no auth) so it can ground findings in the documentation. Override or disable that via REVIEW_DOCS_MCP_URL.

Use it in other repos

Consuming repos opt in with a small workflow that calls the composite action; the review logic, skills, and prompts stay centralized here. See actions/pr-review/README.md and examples/consumer-workflow.yml.

# .github/workflows/pr-review.yml in the consuming repo
permissions:
  contents: read
  pull-requests: write   # required: the workflow posts the review
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: <owner>/agents/actions/pr-review@v1     # latest 1.x; see Versioning
        env:                                          # provider credentials
          CLOUDFLARE_API_KEY: ${{ secrets.CLOUDFLARE_API_KEY }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
        with:
          pr-number: ${{ github.event.pull_request.number }}
          model: cloudflare-workers-ai/@cf/moonshotai/kimi-k2.6   # required

Action visibility: GitHub only lets a private action be consumed by private repos in the org. If the consumer is public (or you just want the simplest setup), make agents public. For fork PRs on a public repo, the consumer must trigger on pull_request_target (so the job gets a writable token and access to the provider secrets) — see examples/consumer-workflow.yml.

Per-repo overrides

A consuming repo can tailor reviews with an .agents/ directory at its root (prompts/, skills/, personas/), so it can hold overrides for every fleet agent, not just this one. The override-mode input controls whether those merge with the central defaults (default) or replace them. Full details in actions/pr-review/README.md.

Run it locally

cp .env.example .env        # REVIEW_MODEL + its provider creds, GH_TOKEN for gh
pnpm install
pnpm exec flue run pr-review --payload '{"prNumber": 123, "repo": "owner/name"}'

flue run builds the project, invokes the workflow, and prints the structured verdict as JSON.

The Issue Health Check agent

Checks newly opened GitHub issues for actionability before a maintainer picks up triage. It fetches the live issue, asks the issue-health skill for structured analysis (issueType, verdict, hidden internal score, summary, missingInfo, suggestedLabels, and redactionWarning), then renders and posts one deterministic health-check/support comment.

Use it in other repos

Consuming repos opt in with an issues.opened workflow that calls the composite action. See actions/issue-health/README.md and examples/issue-health-workflow.yml.

# .github/workflows/issue-health.yml in the consuming repo
on:
  issues:
    types: [opened]
permissions:
  contents: read
  issues: write      # required: the workflow comments and may apply labels
jobs:
  issue-health:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: <owner>/agents/actions/issue-health@v1
        env:                                          # provider credentials
          CLOUDFLARE_API_KEY: ${{ secrets.CLOUDFLARE_API_KEY }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
        with:
          issue-number: ${{ github.event.issue.number }}
          model: cloudflare-workers-ai/@cf/moonshotai/kimi-k2.6   # required

v1 runs only for newly opened issues. It does not respond to edits or reopens, create labels, edit issue bodies, close issues, or assign people. Labeling is existing-only by default: the workflow discovers labels from the target repo at runtime, filters model suggestions against those names, and applies only labels that already exist there. Set label-mode: off to disable labeling.

The default comment-mode is always, so every opened issue gets one combined health-check/support comment. Set comment-mode: needs-improvement to comment only for needs_info / not_actionable results, or comment-mode: off to skip comments. When comments are enabled, the footer links to GitHub Sponsors and Flipt Pro.

Per-repo overrides

Issue Health Check uses the same .agents/ override convention as PR Review. A consuming repo can add local prompts/skills/personas under .agents/, and the action's override-mode controls whether those files merge with the central defaults or replace them. Full details are in actions/issue-health/README.md.

Run it locally

cp .env.example .env        # ISSUE_HEALTH_MODEL + its provider creds, GH_TOKEN for gh
pnpm install
pnpm issue-health -- --payload '{"issueNumber":123,"repo":"owner/name"}'

pnpm issue-health runs the flue run issue-health package script, fetches the issue from repo, posts according to ISSUE_HEALTH_COMMENT_MODE (default always), applies labels according to ISSUE_HEALTH_LABEL_MODE (default existing-only), and prints the structured result as JSON.

Adding an agent

Add workflows/<name>.ts — it shares everything above: the runtime entry in app.ts, required model selection via requireModel(ctx.env.<NAME>_MODEL, …), and the skills / prompts / personas patterns. Give it its own skill(s) under skills/, prompt guidance under prompts/, and personas under personas/ as needed, then register them on the agent. Run it with flue run <name>, and (if it should be consumable by other repos) add an action under actions/<name>/.

For independent builds/deploys, promote an agent into its own package under packages/* and list it in pnpm-workspace.yaml.