diff --git a/.agents/PROJECT.md b/.agents/PROJECT.md index 26591cad..8be07c51 100644 --- a/.agents/PROJECT.md +++ b/.agents/PROJECT.md @@ -83,7 +83,7 @@ content/ The skills implement a multi-phase agentic development pipeline. Entry points: -- **`/orchestrate-dev`** — full workflow: architecture (optional) -> planning (optional) -> implementation -> review cycle +- **`/orchestrate-dev`** — full workflow (default), lightweight (`--mode=vibe`), or thorough (`--mode=strict`) - **`/orchestrate-review`** — review-only workflow for manually written code The `orchestrate` skill is the internal pipeline engine. It: diff --git a/packages/agents/content/skills/orchestrate-dev/SKILL.md b/packages/agents/content/skills/orchestrate-dev/SKILL.md index fca77d5f..cd4293c8 100644 --- a/packages/agents/content/skills/orchestrate-dev/SKILL.md +++ b/packages/agents/content/skills/orchestrate-dev/SKILL.md @@ -15,14 +15,44 @@ Run a full development workflow by invoking the `orchestrate` engine with the co ## Arguments - Task description (required): what to implement +- `--mode=`: select a mode preset (default: no mode, preserving current behavior) - `--max-review-rounds=N`: maximum iterative review rounds (default: 3) - `--diff-base=`: reference to diff against for reviews (default: project's default branch) -- `--fix-low` / `--no-fix-low`: whether to fix `low`-criticality findings (default: true) +- `--approval-threshold=`: findings at this level or above must be fixed for code approval (default: `low`) +- `--budget-threshold=`: remaining review-round budget is spent only on findings at this level or above (default: `low`) +- `--fix-low` / `--no-fix-low`: backward-compatible aliases. `--fix-low` is equivalent to `--approval-threshold=low --budget-threshold=low`. `--no-fix-low` is equivalent to `--approval-threshold=medium --budget-threshold=medium`. -## Pipeline +## Mode presets + +Each mode is a preset bundle of settings. When `--mode` is specified, its preset values apply as defaults. Any setting can be individually overridden via explicit CLI arguments (e.g., `--mode=vibe --approval-threshold=medium`). + +| Setting | `vibe` | (default) | `strict` | +| ------------------- | ------ | --------- | -------- | +| architecture | absent | optional | required | +| planning | absent | optional | required | +| approval-threshold | high | low | low | +| budget-threshold | high | low | low | +| holistic_reviewer\* | sonnet | opus | opus | +| max-review-rounds | 1 | 3 | 4 | + +\* `holistic_reviewer` uses snake_case because it is a `--models` key (passed as `--models=holistic_reviewer:sonnet`), not a standalone argument. See the engine's [model resolution](../orchestrate/SKILL.md#resolving-models) for details. + +### Resolution cascade + +For all mode-affected settings, values are resolved in this order (highest priority first): + +1. Explicit CLI argument +2. Mode preset (if `--mode` specified) +3. `orchestration.` in preferences.yaml +4. Legacy alias (`fix_low_findings` mapped to thresholds) +5. Engine default + +### Pipeline per mode + +**Default** (no `--mode`): ``` -architecture (optional) → planning (optional) → implementation (required) → review-cycle (required) +architecture (optional) -> planning (optional) -> implementation (required) -> review-cycle (required) ``` | Phase | Requirement | Description | @@ -32,9 +62,36 @@ architecture (optional) → planning (optional) → implementation (required) | `implementation` | `required` | Write code | | `review-cycle` | `required` | Parallel review, code-simplifier, holistic review | +**`--mode=vibe`**: + +``` +implementation (required) -> review-cycle (required) +``` + +| Phase | Requirement | Description | +| ---------------- | ----------- | ------------------------------------------------- | +| `implementation` | `required` | Write code | +| `review-cycle` | `required` | Parallel review, code-simplifier, holistic review | + +**`--mode=strict`**: + +``` +architecture (required) -> planning (required) -> implementation (required) -> review-cycle (required) +``` + +| Phase | Requirement | Description | +| ---------------- | ----------- | ------------------------------------------------- | +| `architecture` | `required` | Assess impact; always runs | +| `planning` | `required` | Create implementation plan; always runs | +| `implementation` | `required` | Write code | +| `review-cycle` | `required` | Parallel review, code-simplifier, holistic review | + ## Process -Invoke the `orchestrate` skill with the pipeline specification above and pass through all arguments unchanged. The agent reads both this wrapper and the orchestrate engine instructions in the same conversation context. The pipeline table above **is** the pipeline specification — the engine reads the table entries (phase name + requirement level) and uses them directly to determine which phases to execute and in what order. No additional structured format is needed beyond this table. +1. **Resolve mode**: if `--mode` is provided, look up the mode preset from the table above. +2. **Apply overrides**: for each setting, apply the resolution cascade — explicit CLI arguments override mode presets, which override preferences, which override engine defaults. For model-related settings (like `holistic_reviewer`), pass the resolved value to the engine via `--models` (e.g., `--models=holistic_reviewer:sonnet`). +3. **Select pipeline**: use the pipeline table corresponding to the resolved mode. +4. **Invoke the engine**: invoke the `orchestrate` skill with the selected pipeline specification and all resolved arguments. The agent reads both this wrapper and the orchestrate engine instructions in the same conversation context. The pipeline table for the resolved mode **is** the pipeline specification — the engine reads the table entries (phase name + requirement level) and uses them directly to determine which phases to execute and in what order. No additional structured format is needed beyond this table. ## After the run diff --git a/packages/agents/content/skills/orchestrate-review/SKILL.md b/packages/agents/content/skills/orchestrate-review/SKILL.md index 33797d38..7509d651 100644 --- a/packages/agents/content/skills/orchestrate-review/SKILL.md +++ b/packages/agents/content/skills/orchestrate-review/SKILL.md @@ -26,7 +26,9 @@ Use `orchestrate-dev` instead when you need the full development workflow (archi - Task description (required): what the branch changes accomplish - `--max-review-rounds=N`: maximum iterative review rounds (default: 3) - `--diff-base=`: reference to diff against for reviews (default: project's default branch) -- `--fix-low` / `--no-fix-low`: whether to fix `low`-criticality findings (default: true) +- `--approval-threshold=`: findings at this level or above must be fixed for code approval (default: `low`) +- `--budget-threshold=`: remaining review-round budget is spent only on findings at this level or above (default: `low`) +- `--fix-low` / `--no-fix-low`: backward-compatible aliases. `--fix-low` is equivalent to `--approval-threshold=low --budget-threshold=low`. `--no-fix-low` is equivalent to `--approval-threshold=medium --budget-threshold=medium`. ## Pipeline diff --git a/packages/agents/content/skills/orchestrate/SKILL.md b/packages/agents/content/skills/orchestrate/SKILL.md index 97c29851..80eaea80 100644 --- a/packages/agents/content/skills/orchestrate/SKILL.md +++ b/packages/agents/content/skills/orchestrate/SKILL.md @@ -8,7 +8,7 @@ user-invocable: false You are a pipeline execution engine for multi-phase development workflows. You delegate ALL work to specialized subagents via the **Task tool** and use their structured output for flow control. You never write project code directly — only orchestration artifacts (run-manifest, run-index.json, run-summary). -Wrapper skills (`orchestrate-dev`, `orchestrate-review`) configure which phases to run and invoke this engine with a pipeline specification. +Wrapper skills (`orchestrate-dev` with optional `--mode=vibe|strict`, `orchestrate-review`) configure which phases to run and invoke this engine with a pipeline specification. ## Arguments @@ -28,8 +28,10 @@ Wrapper skills (`orchestrate-dev`, `orchestrate-review`) configure which phases 2. **Task description** (required): what to implement 3. `--max-review-rounds=N`: maximum iterative review rounds before marking needs_manual_review (default: 3) 4. `--diff-base=`: reference to diff against for reviews (default: project's default branch via `get-default-branch`) -5. `--fix-low` / `--no-fix-low`: whether to fix `low`-criticality findings when review budget remains (default: true) -6. `--models=`: model assignment overrides, comma-separated (e.g., `--models=coder:opus,default:sonnet`) +5. `--approval-threshold=`: findings at this level or above must be fixed for code approval (default: `low`) +6. `--budget-threshold=`: remaining review-round budget is spent only on findings at this level or above (default: `low`) +7. `--fix-low` / `--no-fix-low`: backward-compatible aliases. `--fix-low` is equivalent to `--approval-threshold=low --budget-threshold=low`. `--no-fix-low` is equivalent to `--approval-threshold=medium --budget-threshold=medium`. +8. `--models=`: model assignment overrides, comma-separated (e.g., `--models=coder:opus,default:sonnet`) ### Resolving max-review-rounds @@ -37,11 +39,15 @@ Wrapper skills (`orchestrate-dev`, `orchestrate-review`) configure which phases 2. Fall back to `orchestration.max_review_rounds` in `.agents/preferences.yaml` then `~/.agents/preferences.yaml` 3. Default: `3` -### Resolving fix-low +### Resolving thresholds -1. Skill argument: `--fix-low` or `--no-fix-low` -2. Preference: `orchestration.fix_low_findings` in `.agents/preferences.yaml` then `~/.agents/preferences.yaml` -3. Default: `true` +The wrapper skill (e.g., `orchestrate-dev`) resolves modes and applies the resolution cascade before invoking this engine. The engine receives already-resolved threshold values as explicit arguments. Within the engine, threshold resolution is: + +1. Explicit CLI argument: `--approval-threshold=` or `--budget-threshold=` +2. Legacy alias: `--fix-low` (sets both to `low`) or `--no-fix-low` (sets both to `medium`) +3. Preference: `orchestration.approval_threshold` / `orchestration.budget_threshold` in `.agents/preferences.yaml` then `~/.agents/preferences.yaml` +4. Legacy preference: `orchestration.fix_low_findings` in `.agents/preferences.yaml` then `~/.agents/preferences.yaml` (`true` maps to both thresholds `low`; `false` maps to both thresholds `medium`) +5. Default: both `low` ### Resolving models @@ -88,6 +94,9 @@ Invalid model names (e.g., `gpt4`) are rejected by the Task tool at dispatch tim ```yaml orchestration: + approval_threshold: low # or medium, high + budget_threshold: low # or medium, high + # fix_low_findings: true # legacy alias — mapped to both thresholds (true -> low, false -> medium) models: default: sonnet coder: opus @@ -177,7 +186,8 @@ Prefix the status line with a colored emoji for visual distinction: "mergeBaseSha": "{merge-base-sha}", "diffBase": "{diff-base}", "maxReviewRounds": {N}, - "fixLowFindings": {true|false}, + "approvalThreshold": "{low|medium|high}", + "budgetThreshold": "{low|medium|high}", "mode": "orchestrated", "model": "{model identifier}", "models": { diff --git a/packages/agents/content/skills/orchestrate/modules/review-cycle.md b/packages/agents/content/skills/orchestrate/modules/review-cycle.md index 760df111..00dab38c 100644 --- a/packages/agents/content/skills/orchestrate/modules/review-cycle.md +++ b/packages/agents/content/skills/orchestrate/modules/review-cycle.md @@ -6,16 +6,17 @@ Orchestrate the parallel review, code-simplifier, and holistic review phases as The orchestrate engine must provide these context variables before entering this module: -| Variable | Description | -| ----------------------- | -------------------------------------------------------------------- | -| `{task}` | Task description | -| `{ticket-content}` | GitHub issue body (empty string if unavailable) | -| `{artifact-dir}` | Full path to the run artifact directory | -| `{merge-base-sha}` | Concrete merge-base SHA for diffing | -| `{change-summary-path}` | Path to the most recent `coder_change-summary.md` | -| `{max-review-rounds}` | Maximum iterative review rounds before `needs_manual_review` | -| `{fix-low-findings}` | Whether to fix `low`-criticality findings when review budget remains | -| `{models}` | Resolved model assignments map (see "Resolving models" in SKILL.md) | +| Variable | Description | +| ----------------------- | ----------------------------------------------------------------------------------------------------------- | +| `{task}` | Task description | +| `{ticket-content}` | GitHub issue body (empty string if unavailable) | +| `{artifact-dir}` | Full path to the run artifact directory | +| `{merge-base-sha}` | Concrete merge-base SHA for diffing | +| `{change-summary-path}` | Path to the most recent `coder_change-summary.md` | +| `{max-review-rounds}` | Maximum iterative review rounds before `needs_manual_review` | +| `{approval-threshold}` | Findings at this level or above must be fixed for code approval (`low`, `medium`, or `high`) | +| `{budget-threshold}` | Remaining review-round budget is spent only on findings at this level or above (`low`, `medium`, or `high`) | +| `{models}` | Resolved model assignments map (see "Resolving models" in SKILL.md) | ## Exit state @@ -141,13 +142,13 @@ After all dispatched reviewers complete, aggregate findings from all sources int ### Flow control -Before applying these rules, check the iteration budget. If N iterations have been reached, exit with `needs_manual_review` regardless of criticality. Otherwise, use the aggregated criticality to determine next steps: +Before applying these rules, check the iteration budget. If N iterations have been reached, exit with `needs_manual_review` regardless of criticality. Otherwise, use the aggregated criticality and the two thresholds to determine next steps: -- **`none`** (no actionable findings from any reviewer): proceed to Phase 4a (code-simplifier). -- **`low`**: - - If `fix_low_findings` is true AND review rounds remain: delegate fixes to coder, then run selective re-review. - - Otherwise: proceed to Phase 4a. -- **`medium` or `high`**: delegate fixes to coder, then run selective re-review. +- **criticality >= approval_threshold** AND review rounds remain: delegate fixes to coder, then run selective re-review. These findings must be fixed for code approval. +- **criticality >= approval_threshold** AND no review rounds remain: exit with `needs_manual_review`. These findings block approval and cannot be left unresolved. +- **criticality >= budget_threshold** (but below approval_threshold) AND review rounds remain: delegate fixes to coder, then run selective re-review. These findings are opportunistic — worth fixing if budget allows. +- **criticality >= budget_threshold** (but below approval_threshold) AND no review rounds remain: proceed to Phase 4a. These findings do not block approval, so exhausting budget is acceptable. +- **criticality < budget_threshold**: proceed to Phase 4a (report only, no fix attempt). This includes `none` (no actionable findings from any reviewer). ### Consolidated coder fixes @@ -183,7 +184,7 @@ If re-review is warranted, send re-review Task calls in a single message (parall If a re-reviewer fails or times out, treat its original findings as unverified and include them in the aggregated criticality at their original severity. Record the failure in run-index.json. -After re-reviews complete, aggregate findings again using the same rules. If new actionable findings emerge and review rounds remain (< N), loop back: run another coder fix cycle, then selective re-review. Repeat until convergence (aggregated criticality is `none`, or `low` with `fix_low_findings` false) or the iteration budget is exhausted. +After re-reviews complete, aggregate findings again using the same rules. If new actionable findings emerge and review rounds remain (< N), loop back: run another coder fix cycle, then selective re-review. Repeat until convergence (aggregated criticality is `none`, or below both thresholds, or below approval_threshold with no remaining budget) or the iteration budget is exhausted. ### Loop termination @@ -208,7 +209,7 @@ Write run-index.json at every state transition within Phase 4: ## Phase 4a: Code simplifier -After all reviewers converge (aggregated criticality is `none` or `low`, or after fix cycles complete), run code-simplifier as a sequential final pass. Code-simplifier operates on code that has passed all reviews — its purpose is polish, not correctness. Skip Phase 4a if Phase 4 exited with `needs_manual_review`. Code-simplifier failure should be recorded in run-index.json but should NOT block progression to Phase 4b or fail the run. +After Phase 4 converges (aggregated criticality is below both thresholds, or after fix cycles reduce criticality below the approval threshold, or when the review budget is exhausted with remaining findings below the approval threshold), run code-simplifier as a sequential final pass. Code-simplifier operates on code that has passed all reviews — its purpose is polish, not correctness. Skip Phase 4a if Phase 4 exited with `needs_manual_review`. Code-simplifier failure should be recorded in run-index.json but should NOT block progression to Phase 4b or fail the run. Before dispatching code-simplifier, recompute the changed-file list: `git diff --name-only {merge-base-sha}..HEAD`. Store as `{changed-files}` (replaces the value computed at Phase 4 start, which may be stale after fix cycles). @@ -278,12 +279,10 @@ Call Task with `subagent_type: orchestrated-reviewer`, `max_turns: 30`, `model: Extract `Criticality` using Task return parsing (see SKILL.md). -- **`none`**: set `{review-status}` to `converged`. -- **`low`**: - - If `fix_low_findings` is true AND review rounds remain: delegate fixes to coder, re-review using remaining budget. - - If `fix_low_findings` is true AND no review rounds remain: delegate one coder fix round (no re-review), then set `{review-status}` to `converged`. - - If `fix_low_findings` is false: set `{review-status}` to `converged`. -- **`medium` or `high`** with review rounds remaining: delegate fixes to coder, then re-review using remaining budget — apply the same flow-control rules as Phase 4. If the budget is exhausted without resolution, set `{review-status}` to `needs_manual_review`. -- **`medium` or `high`** with no review rounds remaining: delegate one coder fix round (no re-review), then set `{review-status}` to `needs_manual_review`. +- **criticality >= approval_threshold** AND review rounds remain: delegate fixes to coder, then re-review using remaining budget — apply the same threshold-based flow-control rules as Phase 4. If the budget is exhausted without resolution, set `{review-status}` to `needs_manual_review`. +- **criticality >= approval_threshold** AND no review rounds remain: delegate one coder fix round (no re-review), then set `{review-status}` to `converged`. These findings warranted a fix attempt but do not justify blocking approval when the budget is exhausted — the holistic review is a final sanity check, not a gating review. +- **criticality >= budget_threshold** (but below approval_threshold) AND review rounds remain: delegate fixes to coder, then re-review using remaining budget (opportunistic). +- **criticality >= budget_threshold** (but below approval_threshold) AND no review rounds remain: set `{review-status}` to `converged` (findings do not block approval). +- **criticality < budget_threshold**: set `{review-status}` to `converged` (report only). This includes `none` (no actionable findings). After: record `context.phaseDecisions.holisticReview` with `{ "run": true, "disposition": "executed" }` (or `{ "run": false, "disposition": "skipped", "reason": "Phase 4 exited with needs_manual_review" }` if skipped) and update `context.phases.holisticReview` in run-index.json with `status: "completed"` (or `"failed"` / `"needs_manual_review"`), `completedAt: {ISO timestamp}`, and the holistic review outcome (criticality and whether a coder fix round was needed).