5-phase-workflow 3.2.1 → 3.2.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/workflow-guide.md +3 -3
- package/package.json +1 -1
- package/src/agents/step-executor-agent.md +12 -9
- package/src/agents/step-orchestrator-agent.md +9 -5
- package/src/agents/verification-agent.md +1 -1
- package/src/commands/5/implement.md +14 -8
- package/src/workflows/5-implement.js +169 -65
package/docs/workflow-guide.md
CHANGED
|
@@ -55,10 +55,10 @@ A compact plan (1-2 files, no migration, security/auth, or public API change) is
|
|
|
55
55
|
|
|
56
56
|
A full plan goes through four steps:
|
|
57
57
|
|
|
58
|
-
1. `step-orchestrator-agent` derives the execution graph — steps, execution mode, dependency edges, model choice, targeted pattern references, and verify commands. A component that needs a file another component creates goes into a later step.
|
|
59
|
-
2. Executor agents implement the components using an inline executor contract, independent ones in parallel. Each follows the repository standards and style skills that apply to its target. Mechanical work runs on `haiku`, ordinary logic on `sonnet`, complex work and every retry on `opus` at medium effort. With `advisor: true` in `.5/config.json` (opt-in, Claude Code only, off by default),
|
|
58
|
+
1. `step-orchestrator-agent` derives the execution graph on `opus` at medium effort — an approach summary, steps, execution mode, dependency edges, model choice, targeted pattern references, and verify commands. A component groups one coherent change to one or a few tightly coupled files and carries acceptance criteria. A component that needs a file another component creates goes into a later step.
|
|
59
|
+
2. Executor agents implement the components using an inline executor contract, independent ones in parallel. Each follows the repository standards and style skills that apply to its target. Mechanical work runs on `haiku`, ordinary logic on `sonnet`, complex work and every retry on `opus` at medium effort. With `advisor: true` in `.5/config.json` (opt-in, Claude Code only, off by default), only `opus` components consult Claude Code's advisor tool at hard decisions. All other agents are told not to call it. The first retry stays on the planned model (at least `sonnet`); turn the advisor on with `/advisor opus`. When the session has no advisor tool, `/5:implement` says so and runs without it. A component that finds a needed project file missing reports `blocked` instead of failing; it reruns after the next step, not as a retry. If a component still fails after its retries, the remaining steps are skipped and the run goes to verification and the report.
|
|
60
60
|
3. When every component was mechanical and passed, build and tests run once plus the scope check. Otherwise `verification-agent` checks completeness, build/tests, the plan's acceptance criteria when it states any, and scope.
|
|
61
|
-
4. The run's files are reviewed and the findings fixed — `code-review`, `review-style`, `security-review` for security-sensitive plans, and a flow review that traces fresh installs, interrupted updates, missing directories, and ordering across files when the plan touches those paths. On Claude Code this happens inside the workflow:
|
|
61
|
+
4. The run's files are reviewed and the findings fixed — `code-review`, `review-style`, `security-review` for security-sensitive plans, and a flow review that traces fresh installs, interrupted updates, missing directories, and ordering across files when the plan touches those paths. On Claude Code this happens inside the workflow: a Sonnet skeptic per reviewer tries to refute each finding by reading the code. Findings it cannot confirm are marked skip and are not fixed. One fixer then applies every clear finding, including a clearly better way a reviewer points out, and build, tests, e2e, and lint run again with up to two repair attempts. You are asked only about findings that need a product, API, data, or security decision, one at a time, after the workflow. On Codex and for compact plans, `/5:review` and `/5:address-review-findings` do the same. Auto-commit comes after, so the fixes land in the same commit.
|
|
62
62
|
|
|
63
63
|
Nothing is persisted. If a run fails or is interrupted, fix the cause and rerun `/5:implement`; executors see work already in the files.
|
|
64
64
|
|
package/package.json
CHANGED
|
@@ -12,21 +12,24 @@ You follow the plan, your component, and existing codebase patterns. You do not
|
|
|
12
12
|
## Process
|
|
13
13
|
|
|
14
14
|
1. Read only the listed `patternRefs` ranges or symbols before editing. If a component only has legacy `patternFiles`, read the smallest relevant sections of those files instead of the whole file whenever possible.
|
|
15
|
-
2. For `modify`, read the target
|
|
16
|
-
3. For `rename`, read both `sourceFile` and `
|
|
17
|
-
4. For `create`, mirror naming, exports, layout, and test style from the pattern files. Nothing is persisted between runs, so
|
|
18
|
-
5. Follow the standards `/5:implement` assigns: read the parts of the repository standards and style skills that apply to your target. Repository standards win over the style skills. If the target area has a local skill or rule, follow it too.
|
|
19
|
-
6.
|
|
20
|
-
7.
|
|
21
|
-
8.
|
|
15
|
+
2. For `modify`, read the target files first and make the smallest coherent change.
|
|
16
|
+
3. For `rename`, read both `sourceFile` and the destination in `files` first, then move content with the smallest coherent change.
|
|
17
|
+
4. For `create`, mirror naming, exports, layout, and test style from the pattern files. Nothing is persisted between runs, so a target file may exist from an earlier run: read it first; if it already fulfils the intent, report success with no change, otherwise complete it — never overwrite it blindly.
|
|
18
|
+
5. Follow the standards `/5:implement` assigns: read the parts of the repository standards and style skills that apply to your target files. Repository standards win over the style skills. If the target area has a local skill or rule, follow it too.
|
|
19
|
+
6. Read the approach `summary` for context. Meet every item in the component's `acceptanceCriteria`.
|
|
20
|
+
7. Run every verify command assigned to your component. If none is assigned, verify touched files exist and run the narrowest relevant test/build command you can infer.
|
|
21
|
+
8. Fix local mechanical issues you caused. Stop for architectural changes, auth gates, missing external services, or unclear product decisions.
|
|
22
|
+
9. When a project file or symbol your component needs does not exist yet, do not create it: stop with `STATUS: blocked` and name it under `BLOCKED_BY`. `/5:implement` reruns you after the next step instead of retrying.
|
|
22
23
|
|
|
23
24
|
## Advisor (opt-in)
|
|
24
25
|
|
|
25
|
-
Only
|
|
26
|
+
Only components planned as `opus`, and their retries, consult the advisor. Every other executor does not call the advisor tool.
|
|
27
|
+
|
|
28
|
+
The advisor must be enabled by `/5:implement` (`.5/config.json` `advisor: true`, and the session has the advisor tool). Then consult it before committing to an approach when the intent is ambiguous or crosses modules, and when the same verify failure returns after a fix. Do not consult it for mechanical edits or to confirm work that already passes. On a retry, consult it before your first edit.
|
|
26
29
|
|
|
27
30
|
## Simplicity
|
|
28
31
|
|
|
29
|
-
Write the minimum that satisfies the component (the "smallest coherent change"): reuse what already exists in this codebase first, then prefer the standard library, a native framework feature, or an already-installed dependency over anything new. Add no new dependency, no abstraction for single-use code, no unrequested flexibility, and no error handling for impossible cases. Touch only the target
|
|
32
|
+
Write the minimum that satisfies the component (the "smallest coherent change"): reuse what already exists in this codebase first, then prefer the standard library, a native framework feature, or an already-installed dependency over anything new. Add no new dependency, no abstraction for single-use code, no unrequested flexibility, and no error handling for impossible cases. Touch only the target files and what it strictly needs (its test, an import site). Follow `Simplicity First` in the project `AGENTS.md`.
|
|
30
33
|
|
|
31
34
|
End with exactly:
|
|
32
35
|
|
|
@@ -10,21 +10,23 @@ You are a Step Orchestrator. You do not implement code and you do not write file
|
|
|
10
10
|
|
|
11
11
|
## Goal
|
|
12
12
|
|
|
13
|
-
Turn the plan into execution state that `/5:implement` can run without rethinking the plan. The plan has no fixed shape; derive the components from whatever it describes
|
|
13
|
+
Turn the plan into execution state that `/5:implement` can run without rethinking the plan. The plan has no fixed shape; derive the components from whatever it describes. One component is one coherent change to one or a few tightly coupled files, not one per file. The graph is transient — it is derived fresh on every run.
|
|
14
14
|
|
|
15
15
|
## Derivation Rules
|
|
16
16
|
|
|
17
17
|
- Name each component in short kebab-case.
|
|
18
18
|
- Group independent components into the same step with `mode: "parallel"`.
|
|
19
|
-
- Use `mode: "sequential"` when components touch the same
|
|
19
|
+
- Use `mode: "sequential"` when components touch the same files, one imports another, or an explicit dependency exists.
|
|
20
20
|
- For each component, list the project files and symbols it includes, requires, imports, calls, or tests. When another component creates one of them, add it to `dependsOn` and put it in an earlier step — never the same parallel step or a later one.
|
|
21
21
|
- Prefer fewer steps when dependencies allow.
|
|
22
22
|
- Tests normally run after the components they validate.
|
|
23
23
|
- Choose `model: "haiku"` for mechanical work: localized UI changes, tests, docs, config edits, and simple single-file changes.
|
|
24
24
|
- Choose `model: "sonnet"` for ordinary logic.
|
|
25
|
-
- Choose `model: "opus"` only for complex logic, cross-module behavior, security/auth, data migrations, or public API contracts. `/5:implement` runs it at medium effort.
|
|
25
|
+
- Choose `model: "opus"` only for complex logic, cross-module behavior, security/auth, data migrations, or public API contracts. `/5:implement` runs it at medium effort. `/5:implement` also runs this orchestrator on opus at medium effort.
|
|
26
26
|
- Pick `patternRefs` from patterns the plan names, or from nearby existing files found with Glob/Grep. Prefer one primary reference; use a second only when it adds a distinct convention. Include line ranges or symbols when known so executors avoid reading whole files.
|
|
27
27
|
- Pick `verifyCommands` from `.5/config.json`, the plan, package scripts, and target-specific checks. Prefer narrow checks first, then project-level build/test.
|
|
28
|
+
- Return a short `summary` of the overall approach. Executors read it for context.
|
|
29
|
+
- Give each component `acceptanceCriteria`: a few short, checkable statements of what must be true when it is done. Take them from the plan where it states them.
|
|
28
30
|
- Preserve user decisions exactly. Exclude work the plan defers or rules out.
|
|
29
31
|
- Set `securitySensitive` when the plan touches auth, authorization, user input handling, secrets, cryptography, or SQL/shell/path construction, and `lifecycleSensitive` when it touches install, update, migration, deploy, or bootstrap paths, or the order in which files are written, uploaded, or loaded. They decide which reviewers run after the implementation.
|
|
30
32
|
|
|
@@ -34,6 +36,7 @@ Return this shape:
|
|
|
34
36
|
|
|
35
37
|
```json
|
|
36
38
|
{
|
|
39
|
+
"summary": "short approach summary",
|
|
37
40
|
"securitySensitive": false,
|
|
38
41
|
"lifecycleSensitive": false,
|
|
39
42
|
"steps": [
|
|
@@ -52,9 +55,10 @@ Return this shape:
|
|
|
52
55
|
"step": 1,
|
|
53
56
|
"mode": "parallel|sequential",
|
|
54
57
|
"model": "haiku|sonnet|opus",
|
|
55
|
-
"
|
|
58
|
+
"files": ["path/to/file"],
|
|
56
59
|
"sourceFile": null,
|
|
57
60
|
"description": "one sentence",
|
|
61
|
+
"acceptanceCriteria": ["checkable statement"],
|
|
58
62
|
"dependsOn": [],
|
|
59
63
|
"patternRefs": [
|
|
60
64
|
{
|
|
@@ -78,4 +82,4 @@ Before returning:
|
|
|
78
82
|
- Every non-first-step dependency refers to an existing component name in an earlier step.
|
|
79
83
|
- Every component has 1-2 high-signal `patternRefs`, or a note explaining why no pattern exists.
|
|
80
84
|
- Every component has at least one verify command or a note explaining why verification is manual.
|
|
81
|
-
- Rename components must set `sourceFile` to the original path
|
|
85
|
+
- Rename components must set `sourceFile` to the original path. `files` holds the destination path.
|
|
@@ -17,7 +17,7 @@ Read the plan `/5:implement` names and `.5/config.json` if present.
|
|
|
17
17
|
## Checks
|
|
18
18
|
|
|
19
19
|
1. Completeness: every planned component is completed, none remain pending, and any acceptance criteria the plan states are addressed.
|
|
20
|
-
2. Files: every planned
|
|
20
|
+
2. Files: every path in each planned component's `files` exists unless action is `delete`. For `rename`, verify that `sourceFile` is removed and the destination in `files` exists.
|
|
21
21
|
3. Build: run the configured build command unless it is `none` or the baseline and component results already prove its status.
|
|
22
22
|
4. Tests: run the configured test command unless it is `none` or the baseline and component results already prove its status.
|
|
23
23
|
5. Scope: run `git status --short` and `git diff HEAD --stat`, and read untracked (`??`) files directly — `git diff HEAD` omits them. Every changed file traces to a planned component (its target, its test, or an import site it needs) or is a file a repository standard requires, such as a changelog entry. Flag files outside the plan, work the plan rules out or defers, new dependencies no component requires, and abstractions or configurability no acceptance criterion asks for. Report drift only in `SCOPE`; it does not change `STATUS` — the user decides what to revert.
|
|
@@ -70,11 +70,13 @@ It moves orchestration into deterministic JS, fires parallel components concurre
|
|
|
70
70
|
|
|
71
71
|
- `standards` holds the repository standards and style skill paths from Step 1. Executors follow them while writing code.
|
|
72
72
|
- `baseline` is the array from Step 2 (or `[]`); the workflow's verifier treats those failures as pre-existing and reuses passing results instead of rerunning them.
|
|
73
|
-
- `advisor` is `true` only when the advisor is enabled (Step 1). It adds the advisor rule to
|
|
73
|
+
- `advisor` is `true` only when the advisor is enabled (Step 1). It adds the advisor rule only to executors planned as `opus` and keeps their first retry on the planned model. Every other agent is told not to call the advisor tool.
|
|
74
74
|
- `fixedPoint` and `dirty` are the fixed point and the pre-run dirty files from Step 2. The workflow reviews only the run's files since the fixed point and never edits a dirty file.
|
|
75
75
|
- The workflow reads the config **file** at `paths.config` itself; do not pass build/test/commit settings inline.
|
|
76
76
|
|
|
77
|
-
The workflow also reviews and fixes
|
|
77
|
+
The workflow also reviews and fixes. After verification it runs the correctness and standards reviewers. It adds security and flow reviewers when the plan touches security or install/update/ordering paths. One Sonnet skeptic checks each reviewer's findings and marks refuted ones as `skip`. One fixer then fixes every clear finding across files. Then it reruns build, test, e2e, and lint with up to two repair attempts. It skips review and fix when verification failed.
|
|
78
|
+
|
|
79
|
+
The workflow also returns `skippedSteps` when it stopped after a failed step. Each entry has a `number` and a `name`.
|
|
78
80
|
|
|
79
81
|
2. If the returned `verification.inline` is `true` (every component was mechanical and passed, so no verification agent ran), run steps 2-4 of the **fast-path check** (3c) — the scope part. Build and test already ran in `review.checks`; take their result as the verification.
|
|
80
82
|
3. Continue with Step 4.
|
|
@@ -85,7 +87,7 @@ It produces the same outcome.
|
|
|
85
87
|
|
|
86
88
|
#### 3a. Derive the execution graph
|
|
87
89
|
|
|
88
|
-
Spawn `step-orchestrator-agent` with the plan path and config
|
|
90
|
+
Spawn `step-orchestrator-agent` with the plan path and config, on `opus` at `effort: "medium"`. It returns a `summary` of the approach, steps, dependencies, and per component a model, `files`, `acceptanceCriteria`, `patternRefs` (line ranges/symbols), and verify commands. A component is one coherent change to one or a few tightly coupled files. Check the graph: a `summary`, non-empty steps, and each component carrying `step`, `mode`, `model`, `files`, `acceptanceCriteria`, `patternRefs`, and `verifyCommands`.
|
|
89
91
|
|
|
90
92
|
#### 3b. Execute steps in waves
|
|
91
93
|
|
|
@@ -95,10 +97,11 @@ For each step:
|
|
|
95
97
|
2. Spawn executors with the component's model. Run `opus` at `effort: "medium"`.
|
|
96
98
|
- **Parallel step: emit all of the step's executor Agent calls in a single message so they run concurrently.**
|
|
97
99
|
- Sequential step (same-file or dependency): one executor at a time.
|
|
98
|
-
- Give each executor only its component block, required `patternRefs`, verify commands, the standards from Step 1, and the inline contract below
|
|
100
|
+
- Give each executor only the plan `summary`, its component block with its acceptance criteria, required `patternRefs`, verify commands, the standards from Step 1, and the inline contract below. Do not make it read `step-executor-agent.md`.
|
|
101
|
+
- When the advisor is enabled, append the advisor line after the contract of components planned as `opus` only. Tell every other spawned agent: "Do not call the advisor tool."
|
|
99
102
|
|
|
100
103
|
```text
|
|
101
|
-
Implement exactly the assigned component. Read only listed patternRefs ranges/symbols and the target
|
|
104
|
+
Implement exactly the assigned component. Read only listed patternRefs ranges/symbols and the target files. Meet the acceptance criteria you are given. Nothing is persisted between runs, so your work may already be done: for `create`, read the target first when it exists — if it already fulfils the intent, report success with no change; otherwise complete it, never overwrite it blindly. Read the parts of the repository standards and style skills that apply to your target and follow them; repository standards win over the styles. Make the smallest coherent change — reuse existing codebase code first, then stdlib, native platform features, and installed dependencies; touch only the target files and what they strictly need (its test, an import site) — run assigned verify commands. When a project file or symbol your component needs does not exist yet, do not create it: stop with STATUS: blocked and name it under BLOCKED_BY. Stop (STATUS: failed) for a missing package, unplanned auth/schema/API changes, or unclear product decisions. If verify fails only from pre-existing unrelated issues, report it under DEVIATIONS with the exact evidence and keep STATUS: success — your change is complete. Do not make more than three attempts on the same failing issue.
|
|
102
105
|
|
|
103
106
|
End with:
|
|
104
107
|
---RESULT---
|
|
@@ -113,7 +116,7 @@ ERROR: none | {error description}
|
|
|
113
116
|
---END---
|
|
114
117
|
```
|
|
115
118
|
|
|
116
|
-
Advisor line (only when the advisor is enabled):
|
|
119
|
+
Advisor line (only when the advisor is enabled, and only for components planned as `opus`):
|
|
117
120
|
|
|
118
121
|
```text
|
|
119
122
|
Advisor: if an advisor tool is available, consult it before committing to an approach when the intent is ambiguous or crosses modules, and when the same verify failure returns after a fix. Do not consult it for mechanical edits or to confirm work that already passes.
|
|
@@ -121,10 +124,12 @@ Advisor: if an advisor tool is available, consult it before committing to an app
|
|
|
121
124
|
|
|
122
125
|
3. Parse only the `---RESULT---` block from each executor. Trust the executor's report — do not re-read files you did not change to confirm them.
|
|
123
126
|
|
|
124
|
-
Retry a failed component up to twice, right after it fails (in a sequential step, before the next component starts), on `opus` at `effort: "medium"`. When the advisor is enabled, the first retry
|
|
127
|
+
Retry a failed component up to twice, right after it fails (in a sequential step, before the next component starts), on `opus` at `effort: "medium"`. When the advisor is enabled, the first retry of a component planned as `opus` stays on `opus` and asks the executor to consult the advisor before its first edit. For other components the first retry stays on the planned model, at least `sonnet`, with no advisor. Only the second retry escalates to `opus`.
|
|
125
128
|
|
|
126
129
|
`STATUS: blocked` is no retry reason: the component needs a project file or symbol another component has not created yet, and no model can fix that. Rerun it on its planned model once the next step has finished; if it is still blocked, rerun it once more after the last step. Still blocked after that counts as failed. Give every retry the previous attempt's `STATUS`, `VERIFY`, `ERROR`, and `DEVIATIONS` (or that it returned no result). A `STATUS: success` with `VERIFY: failed` is no retry reason: it can come from pre-existing failures, which verification separates using the baseline. Never fix code in the orchestrator context.
|
|
127
130
|
|
|
131
|
+
**Stop after a failed step.** When a component of a step is still failed after its retries, do not run the remaining steps. Note them as skipped, then go to 3c and the report. Blocked reruns stay as they are for the steps that ran.
|
|
132
|
+
|
|
128
133
|
#### 3c. Verify
|
|
129
134
|
|
|
130
135
|
- **Fast path:** when every component reported `success` with `verify` `passed` or `skipped`, every component was planned as `haiku`, and none needed a retry, run the **fast-path check** below and skip `verification-agent`.
|
|
@@ -168,7 +173,7 @@ The code is **green** when `review.checks` is `null` or `passed` and the post-fi
|
|
|
168
173
|
|
|
169
174
|
If `.5/config.json` `git.autoCommit` is `true`, verification passed, and Step 4 left the code green — commit, including the review fixes from Step 4 for those files, once per step for a full plan, once for a compact plan:
|
|
170
175
|
|
|
171
|
-
1. Stage only files that step owns: each component's `
|
|
176
|
+
1. Stage only files that step owns: each component's `files` for create/modify/delete, both `sourceFile` and `files` for rename, plus the executors' reported `FILES_CREATED`/`FILES_MODIFIED`. For a compact plan, stage the files you changed. Do not stage unrelated changes. **Never stage a pre-run dirty file** (Step 2), on any plan: it holds the user's own unfinished work. Leave it uncommitted and list it in the report.
|
|
172
177
|
2. Build the message from `git.commitMessage.pattern`, replacing `{ticket-id}` with the ticket the plan or the branch name gives (or empty) and `{short-description}` with `step {number}: {step-name}` (compact plan: a short summary of the change); trim redundant whitespace/punctuation when the ticket is empty.
|
|
173
178
|
3. Commit.
|
|
174
179
|
|
|
@@ -179,6 +184,7 @@ When a review fix left build, tests, e2e, or lint failing, do not commit; report
|
|
|
179
184
|
Report: completed/failed component counts, verification status, auto-commit count and any failures, and any failed commands, missing tests, or unmet acceptance criteria. When verification failed, tell the user to fix the reported issues and rerun `/5:implement {feature-name}`. Also list, one line each:
|
|
180
185
|
|
|
181
186
|
- **Review:** the findings count, how many were fixed without asking, how many you asked about, and every failed fix.
|
|
187
|
+
- **Skipped steps:** the steps not run because an earlier step failed, with their numbers and names.
|
|
182
188
|
- **Blocked:** components that stayed blocked, with what they were waiting for — a sign the plan's step order is wrong.
|
|
183
189
|
- **Not verified locally:** the line from Step 2, when build/test could not run here.
|
|
184
190
|
- **Scope:** drift findings from verification, plus files an executor touched outside its planned target (the workflow returns these as `extraFiles`). Suggest `/5:lean-check {feature-name}` when there are any.
|
|
@@ -3,11 +3,11 @@ export const meta = {
|
|
|
3
3
|
description: 'Execute a full plan: derive steps, run executors in parallel waves, verify, review, fix the findings. Claude Code only; Codex uses the prose loop.',
|
|
4
4
|
whenToUse: 'Invoked by the /5:implement command for full plans when the Workflow tool is available. Compact plans never reach it; the command implements them inline.',
|
|
5
5
|
phases: [
|
|
6
|
-
{ title: 'Orchestrate', detail: 'one orchestrator agent derives steps + components' },
|
|
7
|
-
{ title: 'Execute', detail: 'one executor agent per component; parallel components fire together per step; blocked components rerun after the next step' },
|
|
6
|
+
{ title: 'Orchestrate', detail: 'one opus orchestrator agent derives the approach summary, steps + components' },
|
|
7
|
+
{ title: 'Execute', detail: 'one executor agent per component; parallel components fire together per step; blocked components rerun after the next step; a failed step stops the run' },
|
|
8
8
|
{ title: 'Verify', detail: 'inline when all passed + mechanical, else one verification agent' },
|
|
9
|
-
{ title: 'Review', detail: 'correctness, standards, and — when the plan calls for them — security and flow reviewers in parallel' },
|
|
10
|
-
{ title: 'Fix', detail: 'one fixer
|
|
9
|
+
{ title: 'Review', detail: 'correctness, standards, and — when the plan calls for them — security and flow reviewers in parallel. One sonnet skeptic per reviewer tries to refute its findings as soon as that reviewer finishes' },
|
|
10
|
+
{ title: 'Fix', detail: 'one fixer for every clear finding across files, then build/test/lint with one repair round' }
|
|
11
11
|
]
|
|
12
12
|
}
|
|
13
13
|
|
|
@@ -25,10 +25,11 @@ export const meta = {
|
|
|
25
25
|
// auto-commits after this returns. Nothing is persisted: a rerun starts over.
|
|
26
26
|
//
|
|
27
27
|
// Models: haiku for mechanical work, sonnet for ordinary logic, opus at effort
|
|
28
|
-
// medium for complex work
|
|
29
|
-
// .5/config.json
|
|
30
|
-
//
|
|
31
|
-
// retry stays on the planned model, at least sonnet.
|
|
28
|
+
// medium for complex work, for every retry, and for the orchestrator.
|
|
29
|
+
// args.advisor is opt-in from .5/config.json. The command sets it only when the
|
|
30
|
+
// advisor tool is available. Then executors planned as opus consult it at decision
|
|
31
|
+
// points, and the first retry stays on the planned model, at least sonnet.
|
|
32
|
+
// Every other agent is told not to call the advisor tool.
|
|
32
33
|
// ─────────────────────────────────────────────────────────────────────────────
|
|
33
34
|
|
|
34
35
|
const RESULT_SCHEMA = {
|
|
@@ -94,6 +95,27 @@ const FIX_SCHEMA = {
|
|
|
94
95
|
}
|
|
95
96
|
}
|
|
96
97
|
|
|
98
|
+
const VERDICTS_SCHEMA = {
|
|
99
|
+
type: 'object',
|
|
100
|
+
additionalProperties: false,
|
|
101
|
+
required: ['verdicts'],
|
|
102
|
+
properties: {
|
|
103
|
+
verdicts: {
|
|
104
|
+
type: 'array',
|
|
105
|
+
items: {
|
|
106
|
+
type: 'object',
|
|
107
|
+
additionalProperties: false,
|
|
108
|
+
required: ['number', 'real', 'reason'],
|
|
109
|
+
properties: {
|
|
110
|
+
number: { type: 'integer', description: 'number of the finding in the list' },
|
|
111
|
+
real: { type: 'boolean' },
|
|
112
|
+
reason: { type: 'string' }
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
|
|
97
119
|
const CHECKS_SCHEMA = {
|
|
98
120
|
type: 'object',
|
|
99
121
|
additionalProperties: false,
|
|
@@ -148,8 +170,9 @@ const VERIFICATION_SCHEMA = {
|
|
|
148
170
|
const STATE_SCHEMA = {
|
|
149
171
|
type: 'object',
|
|
150
172
|
additionalProperties: false,
|
|
151
|
-
required: ['steps', 'pendingComponents'],
|
|
173
|
+
required: ['summary', 'steps', 'pendingComponents'],
|
|
152
174
|
properties: {
|
|
175
|
+
summary: { type: 'string', description: 'short summary of the approach' },
|
|
153
176
|
securitySensitive: { type: 'boolean', description: 'the change touches auth, authorization, user input, secrets, crypto, or SQL/shell/path construction' },
|
|
154
177
|
lifecycleSensitive: { type: 'boolean', description: 'the change touches install, update, migration, deploy, or bootstrap paths, or ordering across files' },
|
|
155
178
|
steps: {
|
|
@@ -172,16 +195,17 @@ const STATE_SCHEMA = {
|
|
|
172
195
|
items: {
|
|
173
196
|
type: 'object',
|
|
174
197
|
additionalProperties: false,
|
|
175
|
-
required: ['name', 'action', 'step', 'mode', 'model', '
|
|
198
|
+
required: ['name', 'action', 'step', 'mode', 'model', 'files'],
|
|
176
199
|
properties: {
|
|
177
200
|
name: { type: 'string' },
|
|
178
201
|
action: { enum: ['create', 'modify', 'delete', 'rename'] },
|
|
179
202
|
step: { type: 'integer' },
|
|
180
203
|
mode: { enum: ['parallel', 'sequential'] },
|
|
181
204
|
model: { enum: ['haiku', 'sonnet', 'opus'] },
|
|
182
|
-
|
|
183
|
-
sourceFile: { type: ['string', 'null'] },
|
|
205
|
+
files: { type: 'array', items: { type: 'string' }, description: 'target files; for rename the destination' },
|
|
206
|
+
sourceFile: { type: ['string', 'null'], description: 'for rename: the origin' },
|
|
184
207
|
description: { type: 'string' },
|
|
208
|
+
acceptanceCriteria: { type: 'array', items: { type: 'string' } },
|
|
185
209
|
dependsOn: { type: 'array', items: { type: 'string' } },
|
|
186
210
|
patternRefs: {
|
|
187
211
|
type: 'array',
|
|
@@ -213,27 +237,40 @@ Feature: ${a.feature}
|
|
|
213
237
|
Plan: ${a.paths.plan}
|
|
214
238
|
Config: ${a.paths.config} (read only if present)
|
|
215
239
|
|
|
216
|
-
The plan has no fixed shape. Derive the components from whatever it describes
|
|
217
|
-
-
|
|
240
|
+
The plan has no fixed shape. Derive the components from whatever it describes, named in short kebab-case, then turn them into steps + components:
|
|
241
|
+
- One component is one coherent change to one or a few tightly coupled files. Do not split such a change into one component per file. List its target files in files. For a rename, sourceFile is the origin and files holds the destination.
|
|
242
|
+
- Group independent components into one step with mode "parallel"; use "sequential" only when components touch the same files, one imports another, or there is an explicit dependency.
|
|
218
243
|
- Prefer fewer steps. Tests run after the components they validate.
|
|
219
244
|
- model "haiku" for mechanical work (UI tweaks, tests, docs, config, simple single-file edits); "sonnet" for ordinary logic; "opus" only for complex logic, cross-module behavior, security/auth, data migrations, or public API contracts.
|
|
220
245
|
- 1-2 high-signal patternRefs per component with line ranges or symbols so executors avoid whole-file reads. Take them from the plan where it names patterns, else find them with Glob/Grep.
|
|
221
246
|
- verifyCommands: narrowest relevant check first, then project build/test.
|
|
222
247
|
- Exclude work the plan defers or rules out. Represent every other component once. dependsOn must reference existing component names.
|
|
223
248
|
- Dependencies: for each component, list the project files and symbols it includes, requires, imports, calls, or tests. When another component creates one of them, add that component to dependsOn and put it in an EARLIER step — never the same parallel step or a later one.
|
|
249
|
+
- acceptanceCriteria: per component, the checkable outcomes it must meet. Take them from the plan where it states them.
|
|
250
|
+
- summary: a short summary of the overall approach. Executors get it as context.
|
|
224
251
|
- securitySensitive: true when the plan touches auth, authorization, user input handling, secrets, cryptography, or SQL/shell/path construction. lifecycleSensitive: true when it touches install, update, migration, deploy, or bootstrap paths, or the order in which files are written, uploaded, or loaded.
|
|
225
252
|
|
|
226
|
-
Return an object matching the schema (securitySensitive, lifecycleSensitive, steps[] and pendingComponents[])
|
|
253
|
+
Return an object matching the schema (summary, securitySensitive, lifecycleSensitive, steps[] and pendingComponents[]).${noAdvisorBlock(a)}`
|
|
227
254
|
}
|
|
228
255
|
|
|
229
256
|
const ADVISOR_RULE = 'Advisor: if an advisor tool is available, consult it before committing to an approach when the intent is ambiguous or crosses modules, and when the same verify failure returns after a fix. Do not consult it for mechanical edits or to confirm work that already passes.'
|
|
230
257
|
|
|
231
|
-
|
|
258
|
+
// The session advisor reaches every subagent. Only executors planned as opus may use it.
|
|
259
|
+
// The advisor line goes at the end of a prompt as its own paragraph, or nothing when the advisor is off.
|
|
260
|
+
function advisorBlock(a, advised) {
|
|
261
|
+
if (!a.advisor) return ''
|
|
262
|
+
return `\n\n${advised ? ADVISOR_RULE : 'Do not call the advisor tool.'}`
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
// For every agent that is not an executor planned as opus.
|
|
266
|
+
const noAdvisorBlock = a => advisorBlock(a, false)
|
|
267
|
+
|
|
268
|
+
function retryContext(previous, a, advised) {
|
|
232
269
|
const failure = previous
|
|
233
270
|
? `status ${previous.status}, verify ${previous.verify}, error: ${previous.error || 'none'}, deviations: ${previous.deviations || 'none'}`
|
|
234
271
|
: 'the agent crashed without returning a result'
|
|
235
|
-
const advisor = a.advisor ? ' Consult the advisor, if available, before your first edit.' : ''
|
|
236
|
-
return `This is a RETRY of a failed attempt (${failure}). Read the target as the previous attempt left
|
|
272
|
+
const advisor = a.advisor && advised ? ' Consult the advisor, if available, before your first edit.' : ''
|
|
273
|
+
return `This is a RETRY of a failed attempt (${failure}). Read the target files as the previous attempt left them, find the root cause, and correct it.${advisor}`
|
|
237
274
|
}
|
|
238
275
|
|
|
239
276
|
function executorPrompt(c, a, opts) {
|
|
@@ -242,35 +279,45 @@ function executorPrompt(c, a, opts) {
|
|
|
242
279
|
const standards = a.standards || {}
|
|
243
280
|
const repoStandards = (standards.repo || []).map(f => ` - ${f}`).join('\n') || ' - none found'
|
|
244
281
|
const styles = (standards.styles || []).map(f => ` - ${f}`).join('\n') || ' - none found'
|
|
245
|
-
|
|
246
|
-
const
|
|
282
|
+
// An executor is advised only when it was planned as opus. That holds for its retries too.
|
|
283
|
+
const advised = c.model === 'opus'
|
|
284
|
+
const retry = opts && opts.retry ? `\n${retryContext(opts.result, a, advised)}` : ''
|
|
285
|
+
const advisor = advisorBlock(a, advised)
|
|
286
|
+
const criteria = (c.acceptanceCriteria || []).map(x => ` - ${x}`).join('\n') || ' - as described in the intent'
|
|
247
287
|
return `You are a Step Executor. Implement EXACTLY this component and nothing more.${retry}
|
|
248
288
|
|
|
289
|
+
Approach (context only): ${a.summary || 'see the plan'}
|
|
290
|
+
|
|
249
291
|
Component: ${c.name}
|
|
250
292
|
Action: ${c.action}
|
|
251
|
-
Target
|
|
293
|
+
Target files: ${(c.files || []).join(', ')}${c.sourceFile ? `\nSource file (rename from): ${c.sourceFile}` : ''}
|
|
252
294
|
Intent: ${c.description || ''}
|
|
295
|
+
Acceptance criteria:
|
|
296
|
+
${criteria}
|
|
253
297
|
|
|
254
|
-
Read only these pattern references (ranges/symbols), plus the target
|
|
298
|
+
Read only these pattern references (ranges/symbols), plus the target files for modify/rename — and for create when they already exist:
|
|
255
299
|
${refs}
|
|
256
300
|
|
|
257
|
-
Standards — read the parts that apply to your target and follow them. Repository standards win over the style skills.
|
|
301
|
+
Standards — read the parts that apply to your target files and follow them. Repository standards win over the style skills.
|
|
258
302
|
Repository standards:
|
|
259
303
|
${repoStandards}
|
|
260
304
|
Style skills:
|
|
261
305
|
${styles}
|
|
262
306
|
|
|
263
|
-
Rules: Nothing is persisted between runs, so your work may already be done: for \`create\`, read
|
|
307
|
+
Rules: Nothing is persisted between runs, so your work may already be done: for \`create\`, read each target first when it exists — if it already fulfils the intent, report success with no change; otherwise complete it, never overwrite it blindly. Smallest coherent change; reuse what already exists in this codebase before writing new code, then prefer stdlib, native platform features, and installed dependencies; touch only the target files and what they strictly need (its test, an import site); mirror existing naming/exports/layout/tests; follow any local skill or rule; add no new dependency; no abstraction or error handling beyond what the intent requires. Fix mechanical issues you cause (imports, types, lint). When a project file or symbol your component needs does not exist yet, do not create it: STOP and report status blocked with blockedBy — /5:implement reruns you after the next step. STOP and report failed for a missing package, unplanned auth/schema/API/contract changes, or unclear product decisions. If verify fails only from pre-existing unrelated issues, report that as a deviation with the exact evidence — do not mark the component failed. Do not make more than three attempts on the same failing issue.${advisor}
|
|
264
308
|
|
|
265
309
|
Then run: ${verify}
|
|
266
310
|
|
|
267
311
|
Return structured output: status, blockedBy (only when blocked), filesCreated, filesModified, verify, deviations (none or brief), skipped (none, or what you deliberately did not build — add when ...), error (none or description). Keep it concise — no logs or diffs unless failed.`
|
|
268
312
|
}
|
|
269
313
|
|
|
270
|
-
function verifyPrompt(a, results) {
|
|
314
|
+
function verifyPrompt(a, results, skippedSteps) {
|
|
271
315
|
const ran = results.flatMap(s => s.items.map(i =>
|
|
272
316
|
` step ${s.step} ${i.component.name}: ${i.result ? i.result.status : 'no result'}${i.result && i.result.blockedBy ? ` by ${i.result.blockedBy}` : ''} (verify ${i.result ? i.result.verify : '?'})${i.escalated ? ' [escalated to opus]' : i.retried ? ' [retried]' : ''}`))
|
|
273
317
|
const summary = ran.join('\n') || ' (no components ran)'
|
|
318
|
+
const skipped = (skippedSteps || []).length
|
|
319
|
+
? `\n\nSkipped steps — not run because an earlier step failed. Their components are not done, so completeness is not passed:\n${skippedSteps.map(s => ` step ${s.number} ${s.name}`).join('\n')}`
|
|
320
|
+
: ''
|
|
274
321
|
const repoStandards = ((a.standards && a.standards.repo) || []).join(', ') || 'none found'
|
|
275
322
|
const baseline = (a.baseline && a.baseline.length)
|
|
276
323
|
? a.baseline.map(b => ` ${b.command || b.details && b.details.command || '?'}: ${b.status}${b.summary ? ` — ${b.summary}` : ''}`).join('\n')
|
|
@@ -286,11 +333,11 @@ Baseline (pre-change) command results — treat any failure listed here as PRE-E
|
|
|
286
333
|
${baseline}
|
|
287
334
|
|
|
288
335
|
Component results:
|
|
289
|
-
${summary}
|
|
336
|
+
${summary}${skipped}
|
|
290
337
|
|
|
291
338
|
Checks — only whether the plan was built and works; code quality and correctness belong to /5:review, which runs next: completeness (every planned component done, and any acceptance criteria the plan states addressed); files exist for create/modify, rename moved correctly, delete removed; build + test pass (reuse the baseline and component results above when they already prove status — rerun only the commands whose inputs changed, not identical passing ones); scope (run \`git status --short\` and \`git diff HEAD --stat\`, and read untracked files directly since \`git diff HEAD\` omits them: every changed file traces to a planned component — its target, its test, an import site, or a file a repository standard requires (such as a changelog entry); flag files outside the plan, work the plan rules out or defers, new dependencies no component requires, and unrequested abstractions — report drift only in scope; it does not change status). Prefer changed files over broad scanning.
|
|
292
339
|
|
|
293
|
-
Return structured output: status, completeness, infrastructure, acceptanceCriteria ("satisfied/total"), scope, commands[], failures[] (one "drift: {path} — {why}" entry per drift finding)
|
|
340
|
+
Return structured output: status, completeness, infrastructure, acceptanceCriteria ("satisfied/total"), scope, commands[], failures[] (one "drift: {path} — {why}" entry per drift finding).${noAdvisorBlock(a)}`
|
|
294
341
|
}
|
|
295
342
|
|
|
296
343
|
// The user should be asked as little as possible: "decide" is the exception, "fix" the default.
|
|
@@ -311,7 +358,7 @@ function correctnessPrompt(a, files) {
|
|
|
311
358
|
|
|
312
359
|
If the built-in code-review skill is available, invoke Skill(skill: "code-review", args: "high") — never with --fix or --comment — and keep only its findings in these files. Otherwise review the diff blind, on its merits: triage files by risk; read full files only for high-risk changes, public API boundaries, security/auth, and data migrations. Report bugs, security, performance, code quality, API design, missing tests, and over-engineering (unnecessary abstractions, single-use indirection, speculative generality, reinventing stdlib or existing dependencies).
|
|
313
360
|
|
|
314
|
-
${TRIAGE_RULE}`
|
|
361
|
+
${TRIAGE_RULE}${noAdvisorBlock(a)}`
|
|
315
362
|
}
|
|
316
363
|
|
|
317
364
|
function securityPrompt(a, files) {
|
|
@@ -319,13 +366,13 @@ function securityPrompt(a, files) {
|
|
|
319
366
|
|
|
320
367
|
If the built-in security-review skill is available, invoke Skill(skill: "security-review") and keep only its findings in these files. Otherwise review them for authentication and authorization gaps, unvalidated input, leaked secrets, weak cryptography, and SQL/shell/path injection. Every security finding has severity error.
|
|
321
368
|
|
|
322
|
-
${TRIAGE_RULE}`
|
|
369
|
+
${TRIAGE_RULE}${noAdvisorBlock(a)}`
|
|
323
370
|
}
|
|
324
371
|
|
|
325
372
|
function standardsPrompt(a, files) {
|
|
326
373
|
return `You are a Standards Reviewer. Invoke Skill(skill: "review-style", args: "${a.fixedPoint || 'HEAD'} files: ${files.join(', ')} report only"); if it cannot be invoked, read .claude/skills/review-style/SKILL.md and follow it with the same arguments. Leave out its Suppressed findings. ⛔️ hard breaches of a repository standard are severity error, ⚠️ judgement calls severity suggestion; a judgement call whose fix is clearly better is fix, otherwise skip.
|
|
327
374
|
|
|
328
|
-
${TRIAGE_RULE}`
|
|
375
|
+
${TRIAGE_RULE}${noAdvisorBlock(a)}`
|
|
329
376
|
}
|
|
330
377
|
|
|
331
378
|
function flowPrompt(a, files) {
|
|
@@ -339,18 +386,30 @@ A diff reviewer reads file by file; you trace behavior ACROSS these files and th
|
|
|
339
386
|
- files and helpers the change relies on but does not check, and tests that assert the old order or state.
|
|
340
387
|
Report only failures you can describe as a concrete sequence of states.
|
|
341
388
|
|
|
342
|
-
${TRIAGE_RULE}`
|
|
389
|
+
${TRIAGE_RULE}${noAdvisorBlock(a)}`
|
|
343
390
|
}
|
|
344
391
|
|
|
345
|
-
|
|
346
|
-
|
|
392
|
+
// One skeptic checks all findings of one reviewer at once. Unsure counts as not real.
|
|
393
|
+
function skepticPrompt(a, findings) {
|
|
394
|
+
const list = findings.map((f, n) => `${n + 1}. ${f.file}${f.line ? `:${f.line}` : ''} — ${f.description}\n Fix: ${f.fix || 'as described'}`).join('\n')
|
|
395
|
+
return `You are a Review Skeptic. Try to refute each of these review findings by reading the code yourself. Do not edit any file.
|
|
396
|
+
|
|
397
|
+
${list}
|
|
398
|
+
|
|
399
|
+
Judge every finding on its own. Do not let one verdict influence the next.
|
|
400
|
+
Set real=false when the finding cannot happen, is already handled, or is not a problem. If unsure, set real=false.
|
|
401
|
+
Return one verdict per finding with its number and a one-line reason.${noAdvisorBlock(a)}`
|
|
402
|
+
}
|
|
403
|
+
|
|
404
|
+
function fixerPrompt(a, findings) {
|
|
405
|
+
const list = findings.map(f => ` - ${f.id} ${f.file}${f.line ? `:${f.line}` : ''}: ${f.description} → ${f.fix || 'fix as described'}`).join('\n')
|
|
347
406
|
const dirty = (a.dirty || []).join(', ') || 'none'
|
|
348
|
-
return `You are a Review Fixer. Apply these review findings
|
|
407
|
+
return `You are a Review Fixer. Apply these review findings:
|
|
349
408
|
${list}
|
|
350
409
|
|
|
351
|
-
Read
|
|
410
|
+
Read each file first, then apply its fixes from the highest line to the lowest. Touch another file only when a fix strictly needs it (its test, a caller), and never one of these, which hold the user's own uncommitted work: ${dirty}. Make no unrelated change. When reading the code shows a finding's premise is wrong, mark it rejected with the reason — do not ask. Follow the repository standards first, then the style skills. Run the narrowest relevant test or build for the changed files.
|
|
352
411
|
|
|
353
|
-
Return structured output: one item per finding id (applied, rejected, or failed, with a one-line note) and filesModified
|
|
412
|
+
Return structured output: one item per finding id (applied, rejected, or failed, with a one-line note) and filesModified.${noAdvisorBlock(a)}`
|
|
354
413
|
}
|
|
355
414
|
|
|
356
415
|
function checksPrompt(a, files) {
|
|
@@ -364,7 +423,7 @@ ${baseline}
|
|
|
364
423
|
|
|
365
424
|
When a command fails because of this run's changes, fix the cause with the smallest change in these files only — ${files.join(', ')} — and rerun it. At most two repair attempts per command. Do not touch any other file.
|
|
366
425
|
|
|
367
|
-
Return structured output: status (passed when every command passed, was skipped, or failed only pre-existing), commands[] with category, command, status, and a one-line summary, and filesModified (repairs only)
|
|
426
|
+
Return structured output: status (passed when every command passed, was skipped, or failed only pre-existing), commands[] with category, command, status, and a one-line summary, and filesModified (repairs only).${noAdvisorBlock(a)}`
|
|
368
427
|
}
|
|
369
428
|
|
|
370
429
|
// ── Helpers ──────────────────────────────────────────────────────────────────
|
|
@@ -387,7 +446,7 @@ function isBlocked(item) {
|
|
|
387
446
|
}
|
|
388
447
|
|
|
389
448
|
// Retries escalate to opus. With the advisor available, the first retry stays on the planned model
|
|
390
|
-
// (at least sonnet) and
|
|
449
|
+
// (at least sonnet) and only the second escalates. Only a component planned as opus consults the advisor.
|
|
391
450
|
function retryModel(c, attempt, a) {
|
|
392
451
|
if (!(a.advisor && attempt === 1)) return 'opus'
|
|
393
452
|
return c.model === 'haiku' || !c.model ? 'sonnet' : c.model
|
|
@@ -412,8 +471,8 @@ async function runComponent(c, a) {
|
|
|
412
471
|
return item
|
|
413
472
|
}
|
|
414
473
|
|
|
415
|
-
async function runStep(step,
|
|
416
|
-
const stepComps =
|
|
474
|
+
async function runStep(step, plan, a) {
|
|
475
|
+
const stepComps = plan.pendingComponents.filter(c => step.components.includes(c.name))
|
|
417
476
|
let items
|
|
418
477
|
if (step.mode === 'parallel') {
|
|
419
478
|
// Fire every parallel component together, retries included — true concurrency, one wave.
|
|
@@ -440,10 +499,33 @@ async function rerunBlocked(items, a, afterStep) {
|
|
|
440
499
|
|
|
441
500
|
const stripDot = f => f.replace(/^\.\//, '')
|
|
442
501
|
|
|
502
|
+
// Hands the fix and decide findings of one reviewer to a sonnet skeptic. A refuted finding becomes skip.
|
|
503
|
+
// A crashed skeptic or a missing verdict leaves the findings unchanged.
|
|
504
|
+
async function refuteFindings(a, key, findings) {
|
|
505
|
+
if (!findings) return findings
|
|
506
|
+
const open = findings.filter(f => f.action === 'fix' || f.action === 'decide')
|
|
507
|
+
if (!open.length) return findings
|
|
508
|
+
const out = await agent(skepticPrompt(a, open), { label: `skeptic:${key}`, phase: 'Review', ...modelOpts('sonnet'), schema: VERDICTS_SCHEMA })
|
|
509
|
+
.catch(() => null)
|
|
510
|
+
if (!out) {
|
|
511
|
+
log(`skeptic:${key} returned nothing, findings kept as they are`)
|
|
512
|
+
return findings
|
|
513
|
+
}
|
|
514
|
+
open.forEach((f, n) => {
|
|
515
|
+
const verdict = out.verdicts.find(v => v.number === n + 1)
|
|
516
|
+
if (verdict && !verdict.real) {
|
|
517
|
+
f.action = 'skip'
|
|
518
|
+
f.reason = `refuted: ${verdict.reason}`
|
|
519
|
+
f.refuted = true
|
|
520
|
+
}
|
|
521
|
+
})
|
|
522
|
+
return findings
|
|
523
|
+
}
|
|
524
|
+
|
|
443
525
|
// Review the run's files, triage the findings, fix every clear one, then rerun build/test/lint.
|
|
444
526
|
async function reviewAndFix(a, plan, allItems, verification, usedOpus) {
|
|
445
527
|
const runFiles = [...new Set(allItems.flatMap(i => [
|
|
446
|
-
i.component.
|
|
528
|
+
...(i.component.files || []), i.component.sourceFile,
|
|
447
529
|
...(i.result ? [...(i.result.filesCreated || []), ...(i.result.filesModified || [])] : [])
|
|
448
530
|
]).filter(Boolean).map(stripDot))]
|
|
449
531
|
const dirty = new Set((a.dirty || []).map(stripDot))
|
|
@@ -455,9 +537,14 @@ async function reviewAndFix(a, plan, allItems, verification, usedOpus) {
|
|
|
455
537
|
]
|
|
456
538
|
if (plan.securitySensitive) reviewers.push({ key: 'security', prompt: securityPrompt, model: 'sonnet' })
|
|
457
539
|
if (plan.lifecycleSensitive || plan.securitySensitive) reviewers.push({ key: 'flow', prompt: flowPrompt, model: 'opus' })
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
540
|
+
// Each reviewer's skeptic starts as soon as that reviewer finishes.
|
|
541
|
+
const reports = await pipeline(
|
|
542
|
+
reviewers,
|
|
543
|
+
r => agent(r.prompt(a, runFiles), { label: `review:${r.key}`, phase: 'Review', ...modelOpts(r.model), schema: FINDINGS_SCHEMA })
|
|
544
|
+
.catch(() => null)
|
|
545
|
+
.then(out => ({ key: r.key, findings: out && out.findings.map(f => ({ ...f, reviewer: r.key })) })),
|
|
546
|
+
report => refuteFindings(a, report.key, report.findings)
|
|
547
|
+
)
|
|
461
548
|
const missing = reviewers.filter((r, n) => !reports[n]).map(r => r.key)
|
|
462
549
|
if (missing.length) log(`reviewer(s) returned nothing: ${missing.join(', ')}`)
|
|
463
550
|
|
|
@@ -465,7 +552,10 @@ async function reviewAndFix(a, plan, allItems, verification, usedOpus) {
|
|
|
465
552
|
const findings = []
|
|
466
553
|
const seen = new Set()
|
|
467
554
|
let outside = 0
|
|
468
|
-
|
|
555
|
+
// Refuted findings come last, so they never take the file:line slot of a live finding.
|
|
556
|
+
const reported = reports.filter(Boolean).flat()
|
|
557
|
+
const ordered = [...reported.filter(f => f.action !== 'skip'), ...reported.filter(f => f.action === 'skip')]
|
|
558
|
+
for (const f of ordered) {
|
|
469
559
|
const file = stripDot(f.file)
|
|
470
560
|
if (!runFiles.includes(file)) { outside++; continue }
|
|
471
561
|
const key = `${file}:${f.line || 0}`
|
|
@@ -481,23 +571,21 @@ async function reviewAndFix(a, plan, allItems, verification, usedOpus) {
|
|
|
481
571
|
if (outside) log(`review: dropped ${outside} finding(s) outside the run's files`)
|
|
482
572
|
|
|
483
573
|
phase('Fix')
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
await parallel([...byFile].map(([file, list]) => async () => {
|
|
491
|
-
const out = await agent(fixerPrompt(a, file, list), { label: `fix:${file}`, phase: 'Fix', ...modelOpts(list.some(f => f.reviewer === 'flow') ? 'opus' : fixModel), schema: FIX_SCHEMA })
|
|
574
|
+
// One fixer applies every clear finding across files.
|
|
575
|
+
const toFix = findings.filter(f => f.action === 'fix')
|
|
576
|
+
if (toFix.length) {
|
|
577
|
+
const needsOpus = plan.securitySensitive || toFix.some(f => f.reviewer === 'flow')
|
|
578
|
+
const fixModel = needsOpus ? 'opus' : 'sonnet'
|
|
579
|
+
const out = await agent(fixerPrompt(a, toFix), { label: 'fix', phase: 'Fix', ...modelOpts(fixModel), schema: FIX_SCHEMA })
|
|
492
580
|
.catch(() => null)
|
|
493
|
-
for (const f of
|
|
581
|
+
for (const f of toFix) {
|
|
494
582
|
const item = out && out.items.find(i => i.id === f.id)
|
|
495
583
|
f.status = item ? item.status : 'failed'
|
|
496
584
|
if (item && item.note) f.note = item.note
|
|
497
585
|
}
|
|
498
|
-
}
|
|
586
|
+
}
|
|
499
587
|
const applied = findings.filter(f => f.status === 'applied').length
|
|
500
|
-
log(`review: ${findings.length} finding(s), ${applied} fixed, ${findings.filter(f => f.action === 'decide').length} need a decision`)
|
|
588
|
+
log(`review: ${findings.length} finding(s), ${findings.filter(f => f.refuted).length} refuted, ${applied} fixed, ${findings.filter(f => f.action === 'decide').length} need a decision`)
|
|
501
589
|
|
|
502
590
|
// The inline fast path ran no build/test yet, and applied fixes change what the verifier saw.
|
|
503
591
|
let checks = null
|
|
@@ -512,27 +600,41 @@ async function reviewAndFix(a, plan, allItems, verification, usedOpus) {
|
|
|
512
600
|
const a = args || {}
|
|
513
601
|
|
|
514
602
|
phase('Orchestrate')
|
|
515
|
-
const plan = await agent(orchestratorPrompt(a), { label: 'orchestrate', phase: 'Orchestrate', schema: STATE_SCHEMA })
|
|
603
|
+
const plan = await agent(orchestratorPrompt(a), { label: 'orchestrate', phase: 'Orchestrate', ...modelOpts('opus'), schema: STATE_SCHEMA })
|
|
516
604
|
const steps = plan.steps
|
|
517
605
|
const components = plan.pendingComponents
|
|
606
|
+
// Executors get the approach summary as context.
|
|
607
|
+
const ctx = { ...a, summary: plan.summary }
|
|
518
608
|
|
|
519
609
|
phase('Execute')
|
|
520
610
|
// A blocked component waits for the next step, then — if still blocked — for the end of the run.
|
|
611
|
+
// A step whose component still fails after its retries stops the run. Later steps would build on it.
|
|
521
612
|
const results = []
|
|
522
613
|
let waiting = []
|
|
523
614
|
const late = []
|
|
524
615
|
for (let n = 0; n < steps.length; n++) {
|
|
525
|
-
const r = await runStep(steps[n],
|
|
616
|
+
const r = await runStep(steps[n], plan, ctx)
|
|
526
617
|
results.push(r)
|
|
618
|
+
// A blocked component from the previous step that fails on its rerun stops the run too.
|
|
619
|
+
let rerunFailed = []
|
|
527
620
|
if (waiting.length) {
|
|
528
|
-
await rerunBlocked(waiting,
|
|
621
|
+
await rerunBlocked(waiting, ctx, n)
|
|
529
622
|
late.push(...waiting.filter(isBlocked))
|
|
623
|
+
rerunFailed = waiting.filter(i => needsRetry(i.result))
|
|
530
624
|
}
|
|
531
625
|
waiting = r.items.filter(isBlocked)
|
|
532
626
|
waiting.forEach(i => { i.lastTry = n })
|
|
627
|
+
const failed = [...r.items.filter(i => needsRetry(i.result)), ...rerunFailed]
|
|
628
|
+
if (failed.length) {
|
|
629
|
+
log(`stopping after step ${steps[n].number}: ${failed.map(i => i.component.name).join(', ')} failed`)
|
|
630
|
+
break
|
|
631
|
+
}
|
|
533
632
|
}
|
|
534
|
-
|
|
535
|
-
|
|
633
|
+
// `results` holds one entry per step that ran. The final rerun covers only those steps.
|
|
634
|
+
const lastRun = results.length - 1
|
|
635
|
+
const skippedSteps = steps.slice(results.length).map(s => ({ number: s.number, name: s.name }))
|
|
636
|
+
const finalRerun = [...late.filter(i => i.lastTry < lastRun), ...waiting]
|
|
637
|
+
if (finalRerun.length) await rerunBlocked(finalRerun, ctx, lastRun + 1)
|
|
536
638
|
|
|
537
639
|
phase('Verify')
|
|
538
640
|
const allItems = results.flatMap(s => s.items)
|
|
@@ -544,7 +646,7 @@ const mechanical = !usedOpus && !allItems.some(i => i.retried) && components.eve
|
|
|
544
646
|
// Deterministic scope signal: files an executor touched beyond its planned target(s).
|
|
545
647
|
// Tests and import sites are legitimate, so this is reported for the user, never a failure.
|
|
546
648
|
const extraFiles = allItems.flatMap(i => {
|
|
547
|
-
const planned = new Set([i.component.
|
|
649
|
+
const planned = new Set([...(i.component.files || []), i.component.sourceFile].filter(Boolean).map(stripDot))
|
|
548
650
|
const touched = i.result ? [...(i.result.filesCreated || []), ...(i.result.filesModified || [])].map(stripDot) : []
|
|
549
651
|
return touched.filter(f => !planned.has(f)).map(f => ({ component: i.component.name, file: f }))
|
|
550
652
|
})
|
|
@@ -555,7 +657,7 @@ if (allPassed && mechanical) {
|
|
|
555
657
|
// No shell access here: the Checks agent in reviewAndFix runs build/test, /5:implement the scope check, when it sees inline: true.
|
|
556
658
|
verification = { status: 'passed', completeness: 'passed', infrastructure: 'passed', acceptanceCriteria: 'n/a', commands: [], failures: [], inline: true }
|
|
557
659
|
} else {
|
|
558
|
-
verification = await agent(verifyPrompt(a, results), {
|
|
660
|
+
verification = await agent(verifyPrompt(a, results, skippedSteps), {
|
|
559
661
|
label: 'verify', phase: 'Verify', ...modelOpts(usedOpus ? 'opus' : 'sonnet'), schema: VERIFICATION_SCHEMA
|
|
560
662
|
})
|
|
561
663
|
}
|
|
@@ -572,16 +674,18 @@ const checksPassed = !review || !review.checks || review.checks.status === 'pass
|
|
|
572
674
|
// Returned to the /5:implement command for the findings file, the decisions, the scope check, per-step staging, and the report.
|
|
573
675
|
return {
|
|
574
676
|
feature: a.feature,
|
|
677
|
+
summary: plan.summary,
|
|
575
678
|
steps,
|
|
576
679
|
components,
|
|
577
680
|
results: results.map(s => ({
|
|
578
681
|
step: s.step,
|
|
579
682
|
name: s.name,
|
|
580
683
|
mode: s.mode,
|
|
581
|
-
items: s.items.map(i => ({ component: i.component.name,
|
|
684
|
+
items: s.items.map(i => ({ component: i.component.name, files: i.component.files, sourceFile: i.component.sourceFile, retried: i.retried, escalated: i.escalated, result: i.result }))
|
|
582
685
|
})),
|
|
583
686
|
verification,
|
|
687
|
+
skippedSteps,
|
|
584
688
|
extraFiles,
|
|
585
689
|
review,
|
|
586
|
-
status: verification.status === 'passed' && checksPassed ? 'completed' : 'failed'
|
|
690
|
+
status: verification.status === 'passed' && checksPassed && !skippedSteps.length ? 'completed' : 'failed'
|
|
587
691
|
}
|