beflow 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Islam Nofl
+
+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,121 @@
+# beflow
+
+**An AI-agent orchestration CLI that drives your issue tracker's backlog to
+shipped PRs.**
+
+beflow turns work items on a project board ([Plane](https://plane.so) or
+[Linear](https://linear.app)) into agent-driven pull requests. You stay the
+captain — decide, review, merge; beflow runs the crew — investigate, spec,
+build, open PRs — and keeps the board in sync.
+
+The agent is **tracker-blind**. All tracker I/O happens at the boundaries of a
+run: beflow resolves a task + a repo + a contract, hands them to a coding-agent
+CLI, and writes the structured result back to the board. The agent never knows
+which tracker it's serving, so the same agent works across Plane and Linear.
+
+```
+   Tracker adapter           beflow core              Agent adapter
+  (Plane | Linear)  ──fetch──▶  resolve repo+agent  ──run──▶  (claude | …)
+        ▲                       +job kind+run mode              │
+        └────────────────── write back report ◀────────────────┘
+```
+
+---
+
+## Requirements
+
+- **[Bun](https://bun.sh)** ≥ 1.0 — beflow runs on the Bun runtime.
+- A **coding-agent CLI** that speaks [ACP](https://agentclientprotocol.com)
+  (e.g. `claude`) plus [`acpx`](https://www.npmjs.com/package/acpx) (fetched
+  automatically via `bunx`).
+- **`git`** and the **`gh`** CLI (for the PR step).
+- A **Plane** or **Linear** workspace and a personal API token.
+
+## Install
+
+```bash
+bun add -g beflow      # or: npm i -g beflow
+```
+
+beflow is invoked with the Bun runtime, so Bun must be on your PATH. To run from
+source instead:
+
+```bash
+git clone https://github.com/corrm/beflow.git
+cd beflow
+bun install
+bun run build          # optional: compile a standalone ./dist/beflow binary
+```
+
+## Quickstart
+
+```bash
+# 1. Create your config from the template and edit it
+cp config.example.json config.json
+
+# 2. Put your tracker API token in a gitignored .env
+cp .env.example .env        # then fill in PLANE_API_KEY or LINEAR_API_KEY
+
+# 3. Check your environment
+beflow doctor
+
+# 4. Provision the project's board (states, labels, types, modules)
+beflow setup APP
+
+# 5. Run a work item, or let the daemon drive the queue
+beflow run APP-42 --auto
+beflow watch APP
+```
+
+See the [config reference](docs/config.md) for every setting and
+[`config.example.json`](config.example.json) for a complete starting point.
+
+## Run modes
+
+| Mode       | Flag                         | What it is                                                                                             |
+| ---------- | ---------------------------- | ------------------------------------------------------------------------------------------------------ |
+| Autonomous | `beflow run APP-42 --auto`   | Headless. Isolated git worktree; for an implement job, opens a PR and moves the item to **In Review**. |
+| Supervised | `beflow run APP-42 --attend` | Interactive via acpx — you approve actions as they happen.                                             |
+| Open       | `beflow run APP-42 --open`   | Runs in the agent's own native TUI; you're present for a multi-turn session.                           |
+
+Runs are **resumable**: each persists a run record and keeps its worktree until
+the item is Done, so an interrupted run picks up where it left off.
+
+## The board is the control center
+
+beflow drives a simple board and you steer from it:
+
+```
+Backlog → Todo → In Progress → In Review → Done   (+ Needs Input, Cancelled)
+```
+
+`beflow watch` polls the queue and dispatches Todo items up to your WIP limit,
+advances merged PRs to **Done**, reworks items you label `changes-requested`,
+and answers items in **Needs Input** when you reply. See the
+[lifecycle](docs/lifecycle.md) and [operating model](docs/OPERATING-MODEL.md).
+
+## Commands
+
+`run` · `watch` · `setup`/`update` · `new` · `accept` · `review` · `queue` ·
+`runs` · `doctor` · `gc`
+
+Full details — flags, examples, behavior — in the
+**[command reference](docs/commands.md)**. Every command also supports `--help`.
+
+## Documentation
+
+- [Command reference](docs/commands.md) — every command and flag
+- [Config reference](docs/config.md) — every `config.json` setting
+- [Design](docs/DESIGN.md) — architecture and the run pipeline
+- [Lifecycle](docs/lifecycle.md) — the board as the control center
+- [Operating model](docs/OPERATING-MODEL.md) — the queue-based workflow
+- [Resolution](docs/resolution.md) — how agent / mode / repo / job kind are chosen
+- [Prompts](docs/prompts.md) — prompt templates and overrides
+- [Issue templates](docs/issue-templates.md) — authoring work items with `beflow new`
+- [Adapters](docs/adapters.md) — writing a tracker adapter
+- [MCP](docs/mcp.md) — per-run MCP servers
+- [ACP events](docs/acp-events.md) — the agent event stream beflow consumes
+
+## License
+
+[MIT](LICENSE)

package/config.example.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "./config.schema.json",
+  "tracker": "plane",
+  "trackers": {
+    "plane": {
+      "baseUrl": "https://api.plane.so",
+      "workspaceSlug": "your-workspace",
+      "apiKeyEnv": "PLANE_API_KEY"
+    }
+  },
+  "defaults": {
+    "agent": "claude",
+    "runMode": "supervised"
+  },
+  "worktrees": {
+    "dir": "~/.beflow/worktrees"
+  },
+  "runs": {
+    "dir": "~/.beflow/runs"
+  },
+  "tools": {
+    "acpx": ["bunx", "acpx"]
+  },
+  "prompts": {
+    "dir": "~/.beflow/prompts"
+  },
+  "agents": {
+    "claude": {
+      "command": "claude",
+      "args": ["--dangerously-skip-permissions"],
+      "acpCommand": "bunx",
+      "acpArgs": ["@agentclientprotocol/claude-agent-acp"],
+      "model": "claude-opus-4-8"
+    },
+    "omp": {
+      "command": "omp",
+      "acpArgs": ["acp"]
+    }
+  },
+  "workspace": {
+    "id": "<workspace-uuid>",
+    "slug": "your-workspace"
+  },
+  "projects": {
+    "APP": {
+      "name": "My App",
+      "plane_project_id": "<project-uuid>",
+      "root": "/path/to/project",
+      "default_repo": "main_repo",
+      "limits": {
+        "inReview": 5,
+        "inProgress": 3
+      },
+      "repos": {
+        "main_repo": "/path/to/project/main_repo",
+        "website": "/path/to/project/website"
+      },
+      "module_repo_map": {
+        "GUI": "main_repo",
+        "Website": "website"
+      },
+      "defaults": {
+        "agent": "claude",
+        "runMode": "supervised"
+      }
+    }
+  }
+}

package/config.schema.json

@@ -0,0 +1,413 @@
+{
+  "$ref": "#/definitions/BeflowConfig",
+  "definitions": {
+    "BeflowConfig": {
+      "type": "object",
+      "properties": {
+        "$schema": {
+          "type": "string"
+        },
+        "_comment": {
+          "type": "string"
+        },
+        "tracker": {
+          "type": "string",
+          "enum": ["plane", "linear"]
+        },
+        "trackers": {
+          "type": "object",
+          "properties": {
+            "linear": {
+              "type": "object",
+              "properties": {
+                "apiKeyEnv": {
+                  "type": "string"
+                }
+              },
+              "required": ["apiKeyEnv"],
+              "additionalProperties": false
+            },
+            "plane": {
+              "type": "object",
+              "properties": {
+                "baseUrl": {
+                  "type": "string"
+                },
+                "workspaceSlug": {
+                  "type": "string"
+                },
+                "apiKeyEnv": {
+                  "type": "string"
+                }
+              },
+              "required": ["baseUrl", "workspaceSlug", "apiKeyEnv"],
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false
+        },
+        "defaults": {
+          "type": "object",
+          "properties": {
+            "agent": {
+              "type": "string"
+            },
+            "runMode": {
+              "type": "string",
+              "enum": ["autonomous", "supervised"]
+            },
+            "assignee": {
+              "type": "string"
+            },
+            "deadLetter": {
+              "type": "object",
+              "properties": {
+                "maxAttempts": {
+                  "type": "number"
+                }
+              },
+              "additionalProperties": false
+            },
+            "inputQuality": {
+              "type": "object",
+              "properties": {
+                "minBodyChars": {
+                  "type": "number"
+                }
+              },
+              "additionalProperties": false
+            },
+            "linkedContext": {
+              "type": "boolean"
+            },
+            "onManualMove": {
+              "type": "string",
+              "enum": ["yield", "abort"],
+              "default": "yield"
+            },
+            "qualityGate": {
+              "type": "object",
+              "properties": {
+                "commands": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "additionalProperties": false
+            },
+            "review": {
+              "type": "object",
+              "properties": {
+                "enabled": {
+                  "type": "boolean"
+                },
+                "postToPr": {
+                  "type": "boolean"
+                }
+              },
+              "additionalProperties": false
+            },
+            "routing": {
+              "type": "object",
+              "properties": {
+                "implement": {
+                  "type": "string"
+                },
+                "spec": {
+                  "type": "string"
+                },
+                "triage": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            "sla": {
+              "type": "object",
+              "properties": {
+                "inReviewMinutes": {
+                  "type": "number"
+                },
+                "needsInputMinutes": {
+                  "type": "number"
+                }
+              },
+              "additionalProperties": false
+            },
+            "telemetry": {
+              "type": "object",
+              "properties": {
+                "inComment": {
+                  "type": "boolean"
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "required": ["agent", "runMode"],
+          "additionalProperties": false
+        },
+        "worktrees": {
+          "type": "object",
+          "properties": {
+            "dir": {
+              "type": "string"
+            }
+          },
+          "required": ["dir"],
+          "additionalProperties": false
+        },
+        "mcp": {
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": false
+            }
+          },
+          "additionalProperties": false
+        },
+        "runs": {
+          "type": "object",
+          "properties": {
+            "dir": {
+              "type": "string"
+            }
+          },
+          "required": ["dir"],
+          "additionalProperties": false
+        },
+        "tools": {
+          "type": "object",
+          "properties": {
+            "acpx": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          },
+          "additionalProperties": false
+        },
+        "prompts": {
+          "type": "object",
+          "properties": {
+            "dir": {
+              "type": "string"
+            }
+          },
+          "required": ["dir"],
+          "additionalProperties": false
+        },
+        "workspace": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "slug": {
+              "type": "string"
+            }
+          },
+          "required": ["id", "slug"],
+          "additionalProperties": false
+        },
+        "projects": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "default_repo": {
+                "type": "string"
+              },
+              "defaults": {
+                "type": "object",
+                "properties": {
+                  "agent": {
+                    "type": "string"
+                  },
+                  "runMode": {
+                    "type": "string",
+                    "enum": ["autonomous", "supervised"]
+                  }
+                },
+                "additionalProperties": false
+              },
+              "ci": {
+                "type": "object",
+                "properties": {
+                  "autoReworkOnRed": {
+                    "type": "boolean"
+                  }
+                },
+                "additionalProperties": false
+              },
+              "deadLetter": {
+                "type": "object",
+                "properties": {
+                  "maxAttempts": {
+                    "type": "number"
+                  }
+                },
+                "additionalProperties": false
+              },
+              "inputQuality": {
+                "type": "object",
+                "properties": {
+                  "minBodyChars": {
+                    "type": "number"
+                  }
+                },
+                "additionalProperties": false
+              },
+              "limits": {
+                "type": "object",
+                "properties": {
+                  "inReview": {
+                    "type": "number"
+                  },
+                  "inProgress": {
+                    "type": "number"
+                  },
+                  "maxRunMinutes": {
+                    "type": "number"
+                  }
+                },
+                "additionalProperties": false
+              },
+              "module_repo_map": {
+                "type": "object",
+                "additionalProperties": {
+                  "type": "string"
+                }
+              },
+              "name": {
+                "type": "string"
+              },
+              "plane_project_id": {
+                "type": "string"
+              },
+              "qualityGate": {
+                "type": "object",
+                "properties": {
+                  "commands": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                },
+                "additionalProperties": false
+              },
+              "repos": {
+                "type": "object",
+                "additionalProperties": {
+                  "type": "string"
+                }
+              },
+              "review": {
+                "type": "object",
+                "properties": {
+                  "enabled": {
+                    "type": "boolean"
+                  },
+                  "postToPr": {
+                    "type": "boolean"
+                  }
+                },
+                "additionalProperties": false
+              },
+              "root": {
+                "type": "string"
+              },
+              "routing": {
+                "type": "object",
+                "properties": {
+                  "implement": {
+                    "type": "string"
+                  },
+                  "spec": {
+                    "type": "string"
+                  },
+                  "triage": {
+                    "type": "string"
+                  }
+                },
+                "additionalProperties": false
+              },
+              "scheduling": {
+                "type": "object",
+                "properties": {
+                  "activeCycleOnly": {
+                    "type": "boolean"
+                  }
+                },
+                "additionalProperties": false
+              },
+              "sla": {
+                "type": "object",
+                "properties": {
+                  "inReviewMinutes": {
+                    "type": "number"
+                  },
+                  "needsInputMinutes": {
+                    "type": "number"
+                  }
+                },
+                "additionalProperties": false
+              },
+              "telemetry": {
+                "type": "object",
+                "properties": {
+                  "inComment": {
+                    "type": "boolean"
+                  }
+                },
+                "additionalProperties": false
+              }
+            },
+            "required": ["default_repo", "module_repo_map", "name", "repos", "root"],
+            "additionalProperties": false
+          }
+        },
+        "agents": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "command": {
+                "type": "string"
+              },
+              "args": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "acpCommand": {
+                "type": "string"
+              },
+              "acpArgs": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "model": {
+                "type": "string"
+              },
+              "permissionPolicy": {}
+            },
+            "required": ["command"],
+            "additionalProperties": false
+          }
+        }
+      },
+      "required": ["tracker", "trackers", "defaults", "workspace", "projects"],
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "beflow",
+  "version": "0.1.0",
+  "description": "An AI-agent orchestration CLI that drives your issue tracker's backlog to shipped PRs.",
+  "keywords": [
+    "acp",
+    "agent",
+    "ai",
+    "automation",
+    "bun",
+    "cli",
+    "issue-tracker",
+    "linear",
+    "orchestration",
+    "plane"
+  ],
+  "homepage": "https://github.com/corrm/beflow#readme",
+  "bugs": {
+    "url": "https://github.com/corrm/beflow/issues"
+  },
+  "license": "MIT",
+  "author": "CorrM (Islam Nofl)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/corrm/beflow.git"
+  },
+  "bin": {
+    "beflow": "./src/cli.ts"
+  },
+  "files": [
+    "src",
+    "config.example.json",
+    "config.schema.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "module": "src/index.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "check": "oxfmt --check . && oxlint && tsc --noEmit && bun test",
+    "test": "bun test",
+    "start": "bun src/cli.ts",
+    "build": "bun build --compile --outfile dist/beflow ./src/cli.ts",
+    "gen:schema": "bun scripts/gen-config-schema.ts"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.5.1",
+    "@linear/sdk": "^86.0.0",
+    "citty": "^0.2.2",
+    "yaml": "^2.9.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "bun-types": "^1.1.0",
+    "oxfmt": "^0.54.0",
+    "oxlint": "^1.69.0",
+    "oxlint-tsgolint": "^0.23.0",
+    "typescript": "^6.0.3",
+    "zod-to-json-schema": "^3.25.2"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}