Skip to content

Commit cb1b34e

Browse files
corrmcorrm
committed
docs: unify per-run resolution reference + fill config.md gaps + picking-properties guide (BEFLOW-6, BEFLOW-7, BEFLOW-8)
BEFLOW-6: add one authoritative resolution table in resolution.md covering all eight per-run-resolved properties (agent, runMode, jobKind, repo, pr.owner, pr.baseBranch, policy.evaluator, policy.onBlock) with precedence, builtins, and fallbacks — pulling the pr/policy cascade out of code comments and calling out the field-level-cascade vs block-level-wholesale-replace distinction. The duplicated precedence prose in pr-ownership-and-policy.md now points here. BEFLOW-7: document the under-covered config.md keys (limits sub-keys, global policy default, telemetry.inComment, tools) and clarify that only triage/spec/ implement are job kinds (review is its own command; task/continuation are not selectable names). BEFLOW-8: new docs/picking-properties.md how-to — label vs body-meta syntax, the Plane HTML-comment caveat, fallbacks, and 3 examples; linked from README. Docs only; no schema or code change.
1 parent 47ccfeb commit cb1b34e

5 files changed

Lines changed: 201 additions & 29 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -216,6 +216,7 @@ never in `config.json`.
216216
- [Lifecycle](docs/lifecycle.md) — the board as the control center
217217
- [Operating model](docs/OPERATING-MODEL.md) — the queue-based workflow
218218
- [Resolution](docs/resolution.md) — how agent / mode / repo / job kind are chosen
219+
- [Picking properties](docs/picking-properties.md) — set agent / jobKind / runMode / repo on a single issue via labels
219220
- [Prompts](docs/prompts.md) — prompt templates and overrides
220221
- [Issue templates](docs/issue-templates.md) — authoring work items with `beflow new`
221222
- [Adapters](docs/adapters.md) — writing a tracker adapter

‎docs/config.md‎

Lines changed: 46 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -52,18 +52,28 @@ These top-level keys set the defaults a run resolves against; every project may
5252
override any of them under `projects.<KEY>.<same-key>`. `agent` and `runMode` are
5353
the two required ones (listed in [Top level](#top-level)); the rest are optional.
5454

55-
| Key | Required | Description |
56-
| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
57-
| `assignee` | no | Tracker user id; beflow assigns the item to this user when it picks it up. |
58-
| `onManualMove` | no | `yield` (default) lets a live run finish but skips writeback if a human moved the card; `abort` also cancels the agent. |
59-
| `linkedContext` | no | Inline parent-epic + attachment context into the agent task. Default on. |
60-
| `deadLetter` | no | `{ maxAttempts }` — failed attempts (crash-resume + CI-rework combined) before an item is quarantined to **Needs Input**. Default 3. |
61-
| `inputQuality` | no | `{ minBodyChars }` — a fresh autonomous dispatch of a too-thin issue is parked to **Needs Input** instead of running. Off when 0/absent. |
62-
| `qualityGate` | no | `{ commands, maxRework, baselineTestGlobs }` — check command(s) run in the worktree before an implement `done` opens a PR. On red, beflow auto-reworks the agent up to `maxRework` times (integer, default 1; `0` = no auto-rework), then fails. `baselineTestGlobs` pins matching changed test files to the target branch so a change cannot self-grade against tests it weakened (beflow-owned runs only). |
63-
| `review` | no | `{ enabled, postToPr }` — opt-in PR review assist in `watch`. |
64-
| `routing` | no | `{ triage, spec, implement }` — route a job kind to a specific agent name. |
65-
| `sla` | no | `{ needsInputMinutes, inReviewMinutes }` — re-ping the escalation channel when an item ages past the threshold. |
66-
| `telemetry` | no | `{ inComment }` — append a compact token/cost line to the writeback comment. Default off. |
55+
| Key | Required | Description |
56+
| --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
57+
| `assignee` | no | Tracker user id; beflow assigns the item to this user when it picks it up. |
58+
| `onManualMove` | no | `yield` (default) lets a live run finish but skips writeback if a human moved the card; `abort` also cancels the agent. |
59+
| `linkedContext` | no | Inline parent-epic + attachment context into the agent task. Default on. |
60+
| `deadLetter` | no | `{ maxAttempts }` — failed attempts (crash-resume + CI-rework combined) before an item is quarantined to **Needs Input**. Default 3. |
61+
| `inputQuality` | no | `{ minBodyChars }` — a fresh autonomous dispatch of a too-thin issue is parked to **Needs Input** instead of running. Off when 0/absent. |
62+
| `qualityGate` | no | `{ commands, maxRework, baselineTestGlobs }` — check command(s) run in the worktree before an implement `done` opens a PR. On red, beflow auto-reworks the agent up to `maxRework` times (integer, default 1; `0` = no auto-rework), then fails. `baselineTestGlobs` pins matching changed test files to the target branch so a change cannot self-grade against tests it weakened (beflow-owned runs only). |
63+
| `review` | no | `{ enabled, postToPr }` — opt-in PR review assist in `watch`. |
64+
| `routing` | no | `{ triage, spec, implement }` — route a job kind to a specific agent name. |
65+
| `sla` | no | `{ needsInputMinutes, inReviewMinutes }` — re-ping the escalation channel when an item ages past the threshold. |
66+
| `telemetry` | no | `{ inComment }` — `inComment: true` appends a compact token/cost line to the writeback comment. Default off. |
67+
| `policy` | no | Global default policy gate (see [PR ownership and policy](pr-ownership-and-policy.md#policy)). A present `projects.<KEY>.policy` **replaces** this block wholesale for that project. Sub-keys: `evaluator` (`"globs"` \| `"command"` \| `"agentowners"` \| `"off"`; default `"off"`), `rules`, `agentownersPath`, `command`, `onBlock` (`"comment"`; default). Builtin: evaluator `"off"`, onBlock `"comment"`. |
68+
69+
> **Selectable job kinds:** only `triage`, `spec`, and `implement` exist
70+
> (`JobKind = "triage" | "spec" | "implement"`). The `routing` keys map these
71+
> same three values to agent names. `review` is a separate top-level command
72+
> (`beflow review <key>`), not a job kind — it cannot be set via a label or
73+
> meta block. `task` and `continuation` do not exist in the schema; they are
74+
> not internal names either. When no CLI flag or per-issue meta sets `jobKind`,
75+
> `autoDetectJobKind` derives it from the issue type and state group (see
76+
> [resolution](resolution.md#job-kind)).
6777
6878
## Projects
6979

@@ -90,20 +100,30 @@ or a Linear team) and the local repos its work lands in.
90100
}
91101
```
92102

93-
| Key | Required | Description |
94-
| ------------------ | -------- | --------------------------------------------------------------------------------------------- |
95-
| `name` | yes | Human-readable project name. |
96-
| `default_repo` | yes | Repo key (from `repos`) used when a run resolves no specific repo. |
97-
| `repos` | yes | Map of repo key → absolute path on disk. |
98-
| `module_repo_map` | yes | Map of board module name → repo key. Modules become Plane modules; they route work to a repo. |
99-
| `root` | yes | Absolute path to the project root. |
100-
| `plane_project_id` | no | The Plane project UUID (Plane only; Linear maps the key to a team). |
101-
| `limits` | no | `{ inReview, inProgress, maxRunMinutes }` — WIP caps and a per-run wall-clock limit. |
102-
| `agent` | no | Agent name overriding the global default for this project. |
103-
| `runMode` | no | Run mode overriding the global default for this project. |
104-
| `ci` | no | `{ autoReworkOnRed }` — re-dispatch rework when an In-Review PR's CI goes red. |
105-
| `routing` | no | Per-project job-kind → agent routing. |
106-
| `scheduling` | no | `{ activeCycleOnly }` — only dispatch Todo items in the active cycle. |
103+
| Key | Required | Description |
104+
| ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
105+
| `name` | yes | Human-readable project name. |
106+
| `default_repo` | yes | Repo key (from `repos`) used when a run resolves no specific repo. |
107+
| `repos` | yes | Map of repo key → absolute path on disk. |
108+
| `module_repo_map` | yes | Map of board module name → repo key. Modules become Plane modules; they route work to a repo. |
109+
| `root` | yes | Absolute path to the project root. |
110+
| `plane_project_id` | no | The Plane project UUID (Plane only; Linear maps the key to a team). |
111+
| `limits` | no | WIP caps and a per-run time limit (see sub-keys below). |
112+
| `agent` | no | Agent name overriding the global default for this project. |
113+
| `runMode` | no | Run mode overriding the global default for this project. |
114+
| `ci` | no | `{ autoReworkOnRed }` — re-dispatch rework when an In-Review PR's CI goes red. |
115+
| `routing` | no | Per-project job-kind → agent routing. |
116+
| `scheduling` | no | `{ activeCycleOnly }` — only dispatch Todo items in the active cycle. |
117+
| `pr` | no | Project-level PR mechanics. Replaces the global `pr` block wholesale. Same sub-keys as the global `pr` (`owner`, `baseBranch`). See [PR ownership and policy](pr-ownership-and-policy.md#project-level-overrides). |
118+
| `policy` | no | Project-level policy gate. Replaces the global `policy` block wholesale. Same sub-keys as the global `policy`. See [PR ownership and policy](pr-ownership-and-policy.md#project-level-overrides). |
119+
120+
#### `limits` sub-keys
121+
122+
| Sub-key | Type | Description |
123+
| --------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------- |
124+
| `inReview` | number | Maximum number of items allowed in **In Review** simultaneously for this project. Watch skips dispatch when the cap is reached. |
125+
| `inProgress` | number | Maximum number of items allowed **In Progress** simultaneously. Watch skips dispatch when the cap is reached. |
126+
| `maxRunMinutes` | number | Wall-clock limit per agent run in minutes. beflow terminates the run and parks the issue as failed if this threshold is exceeded. |
107127

108128
Per-project `deadLetter`, `inputQuality`, `qualityGate`, `review`, `sla`, and
109129
`telemetry` mirror their [Run defaults](#run-defaults) counterparts and override them.

0 commit comments

Comments
 (0)