5-phase-workflow 3.2.0 → 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/README.md +1 -1
- package/docs/workflow-guide.md +4 -4
- package/package.json +1 -1
- package/src/agents/step-executor-agent.md +17 -10
- package/src/agents/step-orchestrator-agent.md +14 -6
- package/src/agents/verification-agent.md +1 -1
- package/src/commands/5/address-review-findings.md +5 -4
- package/src/commands/5/configure.md +1 -1
- package/src/commands/5/implement.md +43 -15
- package/src/commands/5/review.md +18 -6
- package/src/workflows/5-implement.js +417 -48
package/README.md
CHANGED
|
@@ -33,7 +33,7 @@ This adds the foifi rules to `AGENTS.md` as one marked block, links your existin
|
|
|
33
33
|
|
|
34
34
|
1. **Plan** — use Claude Code's plan mode (shift+tab). Plans include a mermaid diagram where it helps.
|
|
35
35
|
2. **Approve** — Claude runs `/5:implement` on its own: small plans directly, larger ones with parallel agents. It checks that the build and tests pass.
|
|
36
|
-
3. **Review** — runs automatically after the implementation: correctness, security, and
|
|
36
|
+
3. **Review** — runs automatically after the implementation: correctness, security, your standards, and — for install, update, and ordering changes — the flows across files. Claude fixes every clear finding itself and asks you only about real decisions, one question at a time.
|
|
37
37
|
|
|
38
38
|
On Codex, start with `$5-plan`; the rest is the same.
|
|
39
39
|
|
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.
|
|
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.
|
|
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
|
|
|
@@ -76,7 +76,7 @@ On Claude Code, review delegates to the built-in `code-review` skill. Effort def
|
|
|
76
76
|
.5/features/{feature-name}/review-findings-{timestamp}.md
|
|
77
77
|
```
|
|
78
78
|
|
|
79
|
-
When findings exist
|
|
79
|
+
When findings exist, `/5:review` hands them straight to `/5:address-review-findings`, also when you started the review yourself. It fixes clear findings on its own — confirmed bugs, security issues, breaches of a repository standard, style findings, and clearly better ways to do the same thing — checks uncertain findings against the code before it would ask, skips obsolete or out-of-scope ones, and asks you only about real decisions, one question at a time. Then it runs build, tests, and lint, and reports what it fixed, what it skipped, and what you decided. To go through saved findings again, or to decide on every finding yourself:
|
|
80
80
|
|
|
81
81
|
```text
|
|
82
82
|
/5:address-review-findings {feature-name} [--interactive]
|
package/package.json
CHANGED
|
@@ -12,26 +12,31 @@ 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.
|
|
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.
|
|
21
23
|
|
|
22
24
|
## Advisor (opt-in)
|
|
23
25
|
|
|
24
|
-
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.
|
|
25
29
|
|
|
26
30
|
## Simplicity
|
|
27
31
|
|
|
28
|
-
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`.
|
|
29
33
|
|
|
30
34
|
End with exactly:
|
|
31
35
|
|
|
32
36
|
```text
|
|
33
37
|
---RESULT---
|
|
34
|
-
STATUS: success | failed
|
|
38
|
+
STATUS: success | failed | blocked
|
|
39
|
+
BLOCKED_BY: none | {the missing project file or symbol}
|
|
35
40
|
FILES_CREATED: [comma-separated paths]
|
|
36
41
|
FILES_MODIFIED: [comma-separated paths]
|
|
37
42
|
VERIFY: passed | failed | skipped
|
|
@@ -47,7 +52,9 @@ Keep the result block concise. Do not include command logs, diffs, or long expla
|
|
|
47
52
|
|
|
48
53
|
**Fix and note** in deviations: imports, type mismatches, or lint you caused; a nearby existing convention that contradicts the plan (follow the convention).
|
|
49
54
|
|
|
50
|
-
**Stop and report** as failed: a required
|
|
55
|
+
**Stop and report** as failed: a required package is absent; a database/schema/auth/API contract change not in the plan.
|
|
56
|
+
|
|
57
|
+
**Stop and report** as blocked: a project file or symbol the component needs has not been created yet.
|
|
51
58
|
|
|
52
59
|
**Report the exact evidence, but do not mark the component failed**, when verify fails only from pre-existing unrelated issues (your change is complete and correct; record the failure as a deviation so verification can treat it as pre-existing).
|
|
53
60
|
|
|
@@ -10,21 +10,25 @@ 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
|
+
- 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.
|
|
20
21
|
- Prefer fewer steps when dependencies allow.
|
|
21
22
|
- Tests normally run after the components they validate.
|
|
22
23
|
- Choose `model: "haiku"` for mechanical work: localized UI changes, tests, docs, config edits, and simple single-file changes.
|
|
23
24
|
- Choose `model: "sonnet"` for ordinary logic.
|
|
24
|
-
- 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.
|
|
25
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.
|
|
26
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.
|
|
27
30
|
- Preserve user decisions exactly. Exclude work the plan defers or rules out.
|
|
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.
|
|
28
32
|
|
|
29
33
|
## Output
|
|
30
34
|
|
|
@@ -32,6 +36,9 @@ Return this shape:
|
|
|
32
36
|
|
|
33
37
|
```json
|
|
34
38
|
{
|
|
39
|
+
"summary": "short approach summary",
|
|
40
|
+
"securitySensitive": false,
|
|
41
|
+
"lifecycleSensitive": false,
|
|
35
42
|
"steps": [
|
|
36
43
|
{
|
|
37
44
|
"number": 1,
|
|
@@ -48,9 +55,10 @@ Return this shape:
|
|
|
48
55
|
"step": 1,
|
|
49
56
|
"mode": "parallel|sequential",
|
|
50
57
|
"model": "haiku|sonnet|opus",
|
|
51
|
-
"
|
|
58
|
+
"files": ["path/to/file"],
|
|
52
59
|
"sourceFile": null,
|
|
53
60
|
"description": "one sentence",
|
|
61
|
+
"acceptanceCriteria": ["checkable statement"],
|
|
54
62
|
"dependsOn": [],
|
|
55
63
|
"patternRefs": [
|
|
56
64
|
{
|
|
@@ -71,7 +79,7 @@ Return this shape:
|
|
|
71
79
|
Before returning:
|
|
72
80
|
|
|
73
81
|
- Every piece of planned work is represented once unless the plan defers it.
|
|
74
|
-
- Every non-first-step dependency refers to an existing component name.
|
|
82
|
+
- Every non-first-step dependency refers to an existing component name in an earlier step.
|
|
75
83
|
- Every component has 1-2 high-signal `patternRefs`, or a note explaining why no pattern exists.
|
|
76
84
|
- Every component has at least one verify command or a note explaining why verification is manual.
|
|
77
|
-
- 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.
|
|
@@ -19,7 +19,7 @@ You are a Review Fix Coordinator. You fix what is clear, ask the user only what
|
|
|
19
19
|
## Options
|
|
20
20
|
|
|
21
21
|
- `--interactive` — ask about every finding, one at a time, instead of deciding the clear ones yourself.
|
|
22
|
-
- `dirty: {paths}` — files that held the user's own uncommitted work before the run (`/5:implement` passes this). A finding in one of them may sit in that earlier work, so it is
|
|
22
|
+
- `dirty: {paths}` — files that held the user's own uncommitted work before the run (`/5:implement` passes this). A finding in one of them may sit in that earlier work, so it is never fixed on your own and never asked about: record it as `wait` with the reason "pre-run dirty file" and list it in the report.
|
|
23
23
|
|
|
24
24
|
## Process
|
|
25
25
|
|
|
@@ -31,9 +31,10 @@ You are a Review Fix Coordinator. You fix what is clear, ask the user only what
|
|
|
31
31
|
- Find the latest `.5/features/{feature}/review-findings-*.md`. If missing, tell the user to run `/5:review` and stop.
|
|
32
32
|
- Parse each finding into compact records with `id`, `file`, `line`, `category`, `severity`, `description`, `suggestedFix`, and `originalReviewerMessage`.
|
|
33
33
|
- Sort each finding into one group:
|
|
34
|
-
- **fix** — a confirmed bug, security issue, breach of a repository standard,
|
|
35
|
-
- **wont_fix** — obsolete, a duplicate, outside the feature scope,
|
|
36
|
-
- **ask** —
|
|
34
|
+
- **fix** — a confirmed bug, security issue, breach of a repository standard, style finding, or a clearly better way to do the same thing (simpler, reuses existing code, more robust), with a concrete fix. Spanning several files is no reason to ask.
|
|
35
|
+
- **wont_fix** — obsolete, a duplicate, outside the feature scope, based on an incorrect premise, or a marginal gain.
|
|
36
|
+
- **ask** — only when the right fix depends on a product, API, data, or security trade-off the plan does not settle, or would contradict the plan. Before asking about a `Question` finding or a fix you are unsure of, read the code: confirmed → **fix**, refuted → **wont_fix**. Ask only what is still open after that.
|
|
37
|
+
- The user wants to be involved as little as possible. When in doubt between **fix** and **ask**, and the fix is reversible and inside the reviewed files, choose **fix**.
|
|
37
38
|
- Record `fix` and `wont_fix` yourself, each with a one-line reason.
|
|
38
39
|
- For each **ask** finding, ask the user — **one finding per question, one question at a time**. Show `Decision {current}/{total}`, file and line, a concise description, the suggested fix, and your recommendation. Options: `fix`, `wont_fix`, `wait`, or textual instructions. Treat textual instructions as `fix` with `customInstructions` unless the text clearly says to defer or reject the finding.
|
|
39
40
|
- With `--interactive`, ask about every finding this way instead.
|
|
@@ -138,7 +138,7 @@ If "Cancel": Exit immediately with message "Configuration unchanged."
|
|
|
138
138
|
2. "Yes - commit after each implementation step" → `git.autoCommit: true`
|
|
139
139
|
|
|
140
140
|
**2f2. Advisor during implementation (Claude Code only — skip on Codex and set `advisor: false`):**
|
|
141
|
-
- "Let `/5:implement` executors consult Claude Code's advisor tool at hard decisions, and retry a failed component once on its planned model before escalating to opus? Needs the advisor turned on in Claude Code (`/advisor opus`); it is experimental and Anthropic-API only."
|
|
141
|
+
- "Let `/5:implement` executors consult Claude Code's advisor tool at hard decisions, and retry a failed component once on its planned model before escalating to opus? Needs the advisor turned on in Claude Code (`/advisor opus`); it is experimental and Anthropic-API only. Without the tool in the session, `/5:implement` warns and runs without it."
|
|
142
142
|
- Options:
|
|
143
143
|
1. "No (recommended)" → `advisor: false`
|
|
144
144
|
2. "Yes" → `advisor: true`
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: 5:implement
|
|
3
|
-
description: Executes a plan from .5/planning/. Compact plans are implemented inline in this session; full plans run through the Workflow tool when available (parallel waves, schema-validated agents), otherwise an equivalent prose loop. Codex always uses the prose loop. Verifies that the plan was built and works, then
|
|
3
|
+
description: Executes a plan from .5/planning/. Compact plans are implemented inline in this session; full plans run through the Workflow tool when available (parallel waves, schema-validated agents), otherwise an equivalent prose loop. Codex always uses the prose loop. Verifies that the plan was built and works, then reviews the run's files and fixes the clear findings — inside the workflow on Claude Code, via /5:review otherwise.
|
|
4
4
|
allowed-tools: Agent, Read, Write, Edit, Glob, Grep, Bash, Workflow, Skill, AskUserQuestion
|
|
5
5
|
user-invocable: true
|
|
6
6
|
argument-hint: [feature-name-or-plan-path]
|
|
@@ -23,7 +23,7 @@ Find the plan:
|
|
|
23
23
|
|
|
24
24
|
Plans have no fixed shape. The feature name is the plan's `feature` frontmatter field when it has one, otherwise the file name without `.md`.
|
|
25
25
|
|
|
26
|
-
Read the plan and `.5/config.json` if it exists. The advisor is **enabled** for this run only when `.5/config.json` has `advisor: true
|
|
26
|
+
Read the plan and `.5/config.json` if it exists. The advisor is **enabled** for this run only when `.5/config.json` has `advisor: true`, the runtime is Claude Code, and this session actually has an advisor tool — subagents inherit it from here. When the setting is on but the tool is missing, tell the user once — "Advisor is on in `.5/config.json`, but no advisor tool is available in this session (`/advisor opus`, Anthropic API only); running without it." — and run with the advisor disabled. Codex has no advisor tool and ignores the setting. Nothing is persisted between runs; a rerun starts over, and executors see work that is already done in the files.
|
|
27
27
|
|
|
28
28
|
A plan is **compact** when it changes 1-2 files with no data migration, no security/auth change, and no public API change. Every other plan is **full**.
|
|
29
29
|
|
|
@@ -38,6 +38,8 @@ Record `git rev-parse HEAD` as this run's **fixed point** for the review in Step
|
|
|
38
38
|
|
|
39
39
|
Run build/test commands from `.5/config.json`. Skip commands set to `none`. Keep the results in context for this run — they are what lets verification tell pre-existing failures apart from new ones. If baseline fails, warn and continue.
|
|
40
40
|
|
|
41
|
+
When a command cannot run at all — a tool or dependency is not installed, or a download fails because the network is blocked — say so right away: "Build/test cannot run here ({reason}); this run is verified only by reading the code." Carry the same line into the report, so the user knows CI is the first real check.
|
|
42
|
+
|
|
41
43
|
## Step 3: Run
|
|
42
44
|
|
|
43
45
|
### Compact plan: implement inline
|
|
@@ -60,16 +62,23 @@ It moves orchestration into deterministic JS, fires parallel components concurre
|
|
|
60
62
|
"paths": {"plan": "{plan-path}", "config": ".5/config.json"},
|
|
61
63
|
"standards": {"repo": ["CONTRIBUTING.md"], "styles": ["/abs/path/.claude/skills/fowler-code-smells/SKILL.md"]},
|
|
62
64
|
"baseline": [{"command": "...", "status": "passed|failed|skipped", "summary": "one line"}],
|
|
63
|
-
"advisor": false
|
|
65
|
+
"advisor": false,
|
|
66
|
+
"fixedPoint": "{fixed-point}",
|
|
67
|
+
"dirty": ["{pre-run dirty file}"]
|
|
64
68
|
}
|
|
65
69
|
```
|
|
66
70
|
|
|
67
71
|
- `standards` holds the repository standards and style skill paths from Step 1. Executors follow them while writing code.
|
|
68
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.
|
|
69
|
-
- `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
|
+
- `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.
|
|
70
75
|
- The workflow reads the config **file** at `paths.config` itself; do not pass build/test/commit settings inline.
|
|
71
76
|
|
|
72
|
-
|
|
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`.
|
|
80
|
+
|
|
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.
|
|
73
82
|
3. Continue with Step 4.
|
|
74
83
|
|
|
75
84
|
### Full plan, without the `Workflow` tool (prose loop)
|
|
@@ -78,7 +87,7 @@ It produces the same outcome.
|
|
|
78
87
|
|
|
79
88
|
#### 3a. Derive the execution graph
|
|
80
89
|
|
|
81
|
-
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`.
|
|
82
91
|
|
|
83
92
|
#### 3b. Execute steps in waves
|
|
84
93
|
|
|
@@ -88,14 +97,16 @@ For each step:
|
|
|
88
97
|
2. Spawn executors with the component's model. Run `opus` at `effort: "medium"`.
|
|
89
98
|
- **Parallel step: emit all of the step's executor Agent calls in a single message so they run concurrently.**
|
|
90
99
|
- Sequential step (same-file or dependency): one executor at a time.
|
|
91
|
-
- 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."
|
|
92
102
|
|
|
93
103
|
```text
|
|
94
|
-
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.
|
|
95
105
|
|
|
96
106
|
End with:
|
|
97
107
|
---RESULT---
|
|
98
|
-
STATUS: success | failed
|
|
108
|
+
STATUS: success | failed | blocked
|
|
109
|
+
BLOCKED_BY: none | {the missing project file or symbol}
|
|
99
110
|
FILES_CREATED: [comma-separated paths]
|
|
100
111
|
FILES_MODIFIED: [comma-separated paths]
|
|
101
112
|
VERIFY: passed | failed | skipped
|
|
@@ -105,7 +116,7 @@ ERROR: none | {error description}
|
|
|
105
116
|
---END---
|
|
106
117
|
```
|
|
107
118
|
|
|
108
|
-
Advisor line (only when the advisor is enabled):
|
|
119
|
+
Advisor line (only when the advisor is enabled, and only for components planned as `opus`):
|
|
109
120
|
|
|
110
121
|
```text
|
|
111
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.
|
|
@@ -113,7 +124,11 @@ Advisor: if an advisor tool is available, consult it before committing to an app
|
|
|
113
124
|
|
|
114
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.
|
|
115
126
|
|
|
116
|
-
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`.
|
|
128
|
+
|
|
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.
|
|
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.
|
|
117
132
|
|
|
118
133
|
#### 3c. Verify
|
|
119
134
|
|
|
@@ -142,13 +157,23 @@ Set `SCOPE: passed | drift`. Drift never changes the verification status; it onl
|
|
|
142
157
|
|
|
143
158
|
## Step 4: Review
|
|
144
159
|
|
|
145
|
-
|
|
160
|
+
Review and fix the run's files before the auto-commit, so fixes land in the same commit. The user should be involved as little as possible: every clear finding — including a clearly better way the review points out — is fixed without asking.
|
|
161
|
+
|
|
162
|
+
**After the Workflow route:** the workflow already reviewed and fixed. If `review` is `null`, verification failed and there is nothing to review yet. Otherwise:
|
|
163
|
+
|
|
164
|
+
1. Write `.5/features/{feature-name}/review-findings-{YYYYMMDD-HHmmss}.md` from `review.findings` using `.claude/templates/workflow/REVIEW-FINDINGS.md`: `action: fix` → **Category:** `Fixable`, `decide` → `Question`, `report` and `skip` → `Manual` with their `reason`; `severity`, `file`, `line`, `description`, and `fix` map to their fields, and the reviewer name goes into **Original Reviewer Message:**.
|
|
165
|
+
2. Findings with `action: decide` are the only ones you ask about — one finding per question, one question at a time, in the format of `/5:address-review-findings` step 2. Apply the chosen fixes and run its post-fix verification (steps 3-4). Also retry each `fix` finding with `status: failed` once yourself; one that still fails goes into the report, not to the user.
|
|
166
|
+
3. Write `.5/features/{feature-name}/review-decisions-{YYYYMMDD-HHmmss}.json` in the format of `/5:address-review-findings`: the workflow's fixes as `decidedBy: claude`, the answers as `decidedBy: user`.
|
|
167
|
+
|
|
168
|
+
The code is **green** when `review.checks` is `null` or `passed` and the post-fix verification of step 2, if any ran, passed.
|
|
169
|
+
|
|
170
|
+
**Every other route** (compact plan, prose loop, Codex): Run `/5:review since {fixed-point} files: {run-files} feature: {feature-name} dirty: {dirty-files}` with the fixed point and the pre-run dirty files from Step 2 (`dirty: none` when there are none). `{run-files}` lists the files this run created, modified, or deleted, so changes the user already had stay out of the review. `/5:review` runs every quality check exactly once — the built-in `code-review`, `security-review` for security-sensitive files, the flow review for install/update/ordering paths, and `review-style` against the repository standards and the style skills — saves the findings, and hands them to `/5:address-review-findings`, which fixes the clear ones on its own and asks the user only about real decisions. The code is green when no review fix was applied or it reported `Review findings addressed: yes`.
|
|
146
171
|
|
|
147
172
|
## Step 5: Auto-commit
|
|
148
173
|
|
|
149
|
-
If `.5/config.json` `git.autoCommit` is `true`, verification passed, and Step 4 left the code green —
|
|
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:
|
|
150
175
|
|
|
151
|
-
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.
|
|
152
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.
|
|
153
178
|
3. Commit.
|
|
154
179
|
|
|
@@ -158,7 +183,10 @@ When a review fix left build, tests, e2e, or lint failing, do not commit; report
|
|
|
158
183
|
|
|
159
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:
|
|
160
185
|
|
|
161
|
-
- **Review:** the findings count
|
|
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.
|
|
188
|
+
- **Blocked:** components that stayed blocked, with what they were waiting for — a sign the plan's step order is wrong.
|
|
189
|
+
- **Not verified locally:** the line from Step 2, when build/test could not run here.
|
|
162
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.
|
|
163
191
|
- **Skipped:** every non-`none` `SKIPPED` entry from the executors, so deliberate omissions stay visible.
|
|
164
192
|
- **Not committed:** pre-run dirty files the run changed — they also hold the user's earlier work, so the user commits them.
|
package/src/commands/5/review.md
CHANGED
|
@@ -48,6 +48,19 @@ Skill(skill: "security-review")
|
|
|
48
48
|
|
|
49
49
|
Use the vulnerabilities it reports. Skip it for diffs that touch none of these areas.
|
|
50
50
|
|
|
51
|
+
**Flow review** — a diff reviewer reads file by file and misses failures that only show across files and states. When the diff touches install, update, migration, deploy, or bootstrap paths, the order in which files are written, uploaded, or loaded, or is security-sensitive, spawn one agent on `opus` at `effort: "medium"`:
|
|
52
|
+
|
|
53
|
+
```text
|
|
54
|
+
Trace behavior ACROSS the changed files and the states they run in. Read the entry points, then follow each flow end to end:
|
|
55
|
+
- a fresh install with no earlier state: missing directories, files, config, or database rows;
|
|
56
|
+
- an upgrade from the previous version, and an update that stops halfway;
|
|
57
|
+
- the order of operations across files: what is written, uploaded, loaded, or required first, and what breaks when that order changes or one step fails;
|
|
58
|
+
- output, headers, or side effects that happen before guards, error handling, or error suppression are in place;
|
|
59
|
+
- files and helpers the change relies on but does not check, and tests that assert the old order or state.
|
|
60
|
+
Report only failures you can describe as a concrete sequence of states. Do not edit files.
|
|
61
|
+
Output the same blocks as the fallback path below.
|
|
62
|
+
```
|
|
63
|
+
|
|
51
64
|
**Standards review** — then invoke `review-style` in report-only mode. It checks the same changes against the repository's own standards and the style skills it lists, and repository standards win:
|
|
52
65
|
|
|
53
66
|
```text
|
|
@@ -92,7 +105,7 @@ When the findings come from the `code-review` skill, map its reported fields ont
|
|
|
92
105
|
| Reported finding | Template field |
|
|
93
106
|
|---|---|
|
|
94
107
|
| `verdict: CONFIRMED` with a localized, single-file fix | **Category:** `Fixable` |
|
|
95
|
-
| `verdict: PLAUSIBLE` | **Category:** `Question` |
|
|
108
|
+
| `verdict: PLAUSIBLE` | read the code and confirm or refute it yourself: confirmed → as `CONFIRMED`, refuted → leave it out, still open → **Category:** `Question` |
|
|
96
109
|
| `verdict: CONFIRMED` but spanning files or needing a design decision | **Category:** `Manual` |
|
|
97
110
|
| `category: correctness` | **Severity:** `error` (`warning` when `PLAUSIBLE`) |
|
|
98
111
|
| `category: simplification` / `efficiency` / `test-coverage` | **Severity:** `suggestion` |
|
|
@@ -103,7 +116,9 @@ When the findings come from the `code-review` skill, map its reported fields ont
|
|
|
103
116
|
|
|
104
117
|
Findings from `security-review` map to **Category:** `Fixable` when the fix is local, otherwise `Manual`, always with **Severity:** `error`; its explanation of the exploit goes into **Original Reviewer Message:**.
|
|
105
118
|
|
|
106
|
-
Findings from the fallback path map directly: Fixable Issues, Questions, and Manual Review become their matching categories.
|
|
119
|
+
Findings from the fallback path and the flow review map directly: Fixable Issues, Questions, and Manual Review become their matching categories.
|
|
120
|
+
|
|
121
|
+
Use `Question` sparingly: only for a finding whose fix depends on a decision the user must make. A clearly better way to do the same thing is `Fixable`, not a question.
|
|
107
122
|
|
|
108
123
|
Findings from `review-style` map like this. Leave out its Suppressed findings; a repository standard overrides them.
|
|
109
124
|
|
|
@@ -134,7 +149,4 @@ Findings saved at `.5/features/{feature-name}/review-findings-{timestamp}.md`
|
|
|
134
149
|
|
|
135
150
|
If there are no findings, stop here.
|
|
136
151
|
|
|
137
|
-
Otherwise
|
|
138
|
-
|
|
139
|
-
- **Called by `/5:implement`** (the `since … files:` scope): run `/5:address-review-findings {feature-name} dirty: {dirty-paths}` right away. The user approved the plan, and these are the run's own files — except the dirty ones, which also hold the user's earlier work.
|
|
140
|
-
- **Started on its own:** the reviewed code may come from someone else's branch, and the fixes are followed by the project's build and test commands. Ask once: "Fix the clear findings on my own and then run build, test, and lint?" On yes, run it. On no, stop and tell the user they can run `/5:address-review-findings {feature-name}` (or `--interactive`) later.
|
|
152
|
+
Otherwise run `/5:address-review-findings {feature-name}` right away — with `dirty: {dirty-paths}` when `/5:implement` called this review. It fixes the clear findings on its own, asks the user one question at a time only about real decisions, and then runs build, test, and lint. Do not ask before handing off: the user asked for the review, and the findings exist to be fixed. A user who wants to decide every finding runs `/5:address-review-findings {feature-name} --interactive`.
|
|
@@ -1,11 +1,13 @@
|
|
|
1
1
|
export const meta = {
|
|
2
2
|
name: '5-implement',
|
|
3
|
-
description: 'Execute a full plan: derive steps, run executors in parallel waves, verify. Claude Code only; Codex uses the prose loop.',
|
|
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' },
|
|
8
|
-
{ title: 'Verify', detail: 'inline when all passed + mechanical, else one verification agent' }
|
|
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
|
+
{ 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. 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' }
|
|
9
11
|
]
|
|
10
12
|
}
|
|
11
13
|
|
|
@@ -14,14 +16,20 @@ export const meta = {
|
|
|
14
16
|
// inline, schema-validated form of src/agents/*-agent.md. Those .md files remain
|
|
15
17
|
// the canonical human-readable contract; keep these prompts in sync with them.
|
|
16
18
|
//
|
|
19
|
+
// The reviewer prompts are the schema-validated form of src/commands/5/review.md,
|
|
20
|
+
// the fixer prompt and the triage rules that of address-review-findings.md.
|
|
21
|
+
//
|
|
17
22
|
// This script has NO filesystem access. It orchestrates agents and RETURNS the
|
|
18
|
-
// final result. The /5:implement command
|
|
19
|
-
//
|
|
23
|
+
// final result. The /5:implement command writes the findings file, asks the user
|
|
24
|
+
// about the few findings that need a decision, runs the scope check, and
|
|
25
|
+
// auto-commits after this returns. Nothing is persisted: a rerun starts over.
|
|
20
26
|
//
|
|
21
27
|
// Models: haiku for mechanical work, sonnet for ordinary logic, opus at effort
|
|
22
|
-
// medium for complex work
|
|
23
|
-
// .5/config.json
|
|
24
|
-
//
|
|
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.
|
|
25
33
|
// ─────────────────────────────────────────────────────────────────────────────
|
|
26
34
|
|
|
27
35
|
const RESULT_SCHEMA = {
|
|
@@ -29,7 +37,8 @@ const RESULT_SCHEMA = {
|
|
|
29
37
|
additionalProperties: false,
|
|
30
38
|
required: ['status', 'verify', 'skipped'],
|
|
31
39
|
properties: {
|
|
32
|
-
status: { enum: ['success', 'failed'] },
|
|
40
|
+
status: { enum: ['success', 'failed', 'blocked'] },
|
|
41
|
+
blockedBy: { type: 'string', description: 'when blocked: the project file or symbol that does not exist yet' },
|
|
33
42
|
filesCreated: { type: 'array', items: { type: 'string' } },
|
|
34
43
|
filesModified: { type: 'array', items: { type: 'string' } },
|
|
35
44
|
verify: { enum: ['passed', 'failed', 'skipped'] },
|
|
@@ -39,6 +48,98 @@ const RESULT_SCHEMA = {
|
|
|
39
48
|
}
|
|
40
49
|
}
|
|
41
50
|
|
|
51
|
+
const FINDINGS_SCHEMA = {
|
|
52
|
+
type: 'object',
|
|
53
|
+
additionalProperties: false,
|
|
54
|
+
required: ['findings'],
|
|
55
|
+
properties: {
|
|
56
|
+
findings: {
|
|
57
|
+
type: 'array',
|
|
58
|
+
items: {
|
|
59
|
+
type: 'object',
|
|
60
|
+
additionalProperties: false,
|
|
61
|
+
required: ['file', 'description', 'action'],
|
|
62
|
+
properties: {
|
|
63
|
+
file: { type: 'string' },
|
|
64
|
+
line: { type: 'integer' },
|
|
65
|
+
severity: { enum: ['error', 'warning', 'suggestion'] },
|
|
66
|
+
description: { type: 'string' },
|
|
67
|
+
fix: { type: 'string', description: 'the concrete change to make' },
|
|
68
|
+
action: { enum: ['fix', 'decide', 'skip'] },
|
|
69
|
+
reason: { type: 'string', description: 'one line: why skip, or which decision the user must make' }
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
const FIX_SCHEMA = {
|
|
77
|
+
type: 'object',
|
|
78
|
+
additionalProperties: false,
|
|
79
|
+
required: ['items'],
|
|
80
|
+
properties: {
|
|
81
|
+
items: {
|
|
82
|
+
type: 'array',
|
|
83
|
+
items: {
|
|
84
|
+
type: 'object',
|
|
85
|
+
additionalProperties: false,
|
|
86
|
+
required: ['id', 'status'],
|
|
87
|
+
properties: {
|
|
88
|
+
id: { type: 'string' },
|
|
89
|
+
status: { enum: ['applied', 'rejected', 'failed'] },
|
|
90
|
+
note: { type: 'string', description: 'one line: what changed, or why rejected/failed' }
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
},
|
|
94
|
+
filesModified: { type: 'array', items: { type: 'string' } }
|
|
95
|
+
}
|
|
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
|
+
|
|
119
|
+
const CHECKS_SCHEMA = {
|
|
120
|
+
type: 'object',
|
|
121
|
+
additionalProperties: false,
|
|
122
|
+
required: ['status', 'commands'],
|
|
123
|
+
properties: {
|
|
124
|
+
status: { enum: ['passed', 'failed'] },
|
|
125
|
+
commands: {
|
|
126
|
+
type: 'array',
|
|
127
|
+
items: {
|
|
128
|
+
type: 'object',
|
|
129
|
+
additionalProperties: false,
|
|
130
|
+
required: ['command', 'status'],
|
|
131
|
+
properties: {
|
|
132
|
+
category: { enum: ['build', 'test', 'e2e', 'lint'] },
|
|
133
|
+
command: { type: 'string' },
|
|
134
|
+
status: { enum: ['passed', 'failed', 'skipped', 'pre-existing'] },
|
|
135
|
+
summary: { type: 'string' }
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
},
|
|
139
|
+
filesModified: { type: 'array', items: { type: 'string' } }
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
|
|
42
143
|
const VERIFICATION_SCHEMA = {
|
|
43
144
|
type: 'object',
|
|
44
145
|
additionalProperties: false,
|
|
@@ -69,8 +170,11 @@ const VERIFICATION_SCHEMA = {
|
|
|
69
170
|
const STATE_SCHEMA = {
|
|
70
171
|
type: 'object',
|
|
71
172
|
additionalProperties: false,
|
|
72
|
-
required: ['steps', 'pendingComponents'],
|
|
173
|
+
required: ['summary', 'steps', 'pendingComponents'],
|
|
73
174
|
properties: {
|
|
175
|
+
summary: { type: 'string', description: 'short summary of the approach' },
|
|
176
|
+
securitySensitive: { type: 'boolean', description: 'the change touches auth, authorization, user input, secrets, crypto, or SQL/shell/path construction' },
|
|
177
|
+
lifecycleSensitive: { type: 'boolean', description: 'the change touches install, update, migration, deploy, or bootstrap paths, or ordering across files' },
|
|
74
178
|
steps: {
|
|
75
179
|
type: 'array',
|
|
76
180
|
items: {
|
|
@@ -91,16 +195,17 @@ const STATE_SCHEMA = {
|
|
|
91
195
|
items: {
|
|
92
196
|
type: 'object',
|
|
93
197
|
additionalProperties: false,
|
|
94
|
-
required: ['name', 'action', 'step', 'mode', 'model', '
|
|
198
|
+
required: ['name', 'action', 'step', 'mode', 'model', 'files'],
|
|
95
199
|
properties: {
|
|
96
200
|
name: { type: 'string' },
|
|
97
201
|
action: { enum: ['create', 'modify', 'delete', 'rename'] },
|
|
98
202
|
step: { type: 'integer' },
|
|
99
203
|
mode: { enum: ['parallel', 'sequential'] },
|
|
100
204
|
model: { enum: ['haiku', 'sonnet', 'opus'] },
|
|
101
|
-
|
|
102
|
-
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' },
|
|
103
207
|
description: { type: 'string' },
|
|
208
|
+
acceptanceCriteria: { type: 'array', items: { type: 'string' } },
|
|
104
209
|
dependsOn: { type: 'array', items: { type: 'string' } },
|
|
105
210
|
patternRefs: {
|
|
106
211
|
type: 'array',
|
|
@@ -132,25 +237,40 @@ Feature: ${a.feature}
|
|
|
132
237
|
Plan: ${a.paths.plan}
|
|
133
238
|
Config: ${a.paths.config} (read only if present)
|
|
134
239
|
|
|
135
|
-
The plan has no fixed shape. Derive the components from whatever it describes
|
|
136
|
-
-
|
|
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.
|
|
137
243
|
- Prefer fewer steps. Tests run after the components they validate.
|
|
138
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.
|
|
139
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.
|
|
140
246
|
- verifyCommands: narrowest relevant check first, then project build/test.
|
|
141
247
|
- Exclude work the plan defers or rules out. Represent every other component once. dependsOn must reference existing component names.
|
|
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.
|
|
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.
|
|
142
252
|
|
|
143
|
-
Return an object matching the schema (steps[] and pendingComponents[])
|
|
253
|
+
Return an object matching the schema (summary, securitySensitive, lifecycleSensitive, steps[] and pendingComponents[]).${noAdvisorBlock(a)}`
|
|
144
254
|
}
|
|
145
255
|
|
|
146
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.'
|
|
147
257
|
|
|
148
|
-
|
|
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) {
|
|
149
269
|
const failure = previous
|
|
150
270
|
? `status ${previous.status}, verify ${previous.verify}, error: ${previous.error || 'none'}, deviations: ${previous.deviations || 'none'}`
|
|
151
271
|
: 'the agent crashed without returning a result'
|
|
152
|
-
const advisor = a.advisor ? ' Consult the advisor, if available, before your first edit.' : ''
|
|
153
|
-
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}`
|
|
154
274
|
}
|
|
155
275
|
|
|
156
276
|
function executorPrompt(c, a, opts) {
|
|
@@ -159,35 +279,45 @@ function executorPrompt(c, a, opts) {
|
|
|
159
279
|
const standards = a.standards || {}
|
|
160
280
|
const repoStandards = (standards.repo || []).map(f => ` - ${f}`).join('\n') || ' - none found'
|
|
161
281
|
const styles = (standards.styles || []).map(f => ` - ${f}`).join('\n') || ' - none found'
|
|
162
|
-
|
|
163
|
-
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'
|
|
164
287
|
return `You are a Step Executor. Implement EXACTLY this component and nothing more.${retry}
|
|
165
288
|
|
|
289
|
+
Approach (context only): ${a.summary || 'see the plan'}
|
|
290
|
+
|
|
166
291
|
Component: ${c.name}
|
|
167
292
|
Action: ${c.action}
|
|
168
|
-
Target
|
|
293
|
+
Target files: ${(c.files || []).join(', ')}${c.sourceFile ? `\nSource file (rename from): ${c.sourceFile}` : ''}
|
|
169
294
|
Intent: ${c.description || ''}
|
|
295
|
+
Acceptance criteria:
|
|
296
|
+
${criteria}
|
|
170
297
|
|
|
171
|
-
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:
|
|
172
299
|
${refs}
|
|
173
300
|
|
|
174
|
-
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.
|
|
175
302
|
Repository standards:
|
|
176
303
|
${repoStandards}
|
|
177
304
|
Style skills:
|
|
178
305
|
${styles}
|
|
179
306
|
|
|
180
|
-
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}
|
|
181
308
|
|
|
182
309
|
Then run: ${verify}
|
|
183
310
|
|
|
184
|
-
Return structured output: status, 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.`
|
|
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.`
|
|
185
312
|
}
|
|
186
313
|
|
|
187
|
-
function verifyPrompt(a, results) {
|
|
314
|
+
function verifyPrompt(a, results, skippedSteps) {
|
|
188
315
|
const ran = results.flatMap(s => s.items.map(i =>
|
|
189
|
-
` step ${s.step} ${i.component.name}: ${i.result ? i.result.status : 'no result'} (verify ${i.result ? i.result.verify : '?'})${i.escalated ? ' [escalated to opus]' : i.retried ? ' [retried]' : ''}`))
|
|
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]' : ''}`))
|
|
190
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
|
+
: ''
|
|
191
321
|
const repoStandards = ((a.standards && a.standards.repo) || []).join(', ') || 'none found'
|
|
192
322
|
const baseline = (a.baseline && a.baseline.length)
|
|
193
323
|
? a.baseline.map(b => ` ${b.command || b.details && b.details.command || '?'}: ${b.status}${b.summary ? ` — ${b.summary}` : ''}`).join('\n')
|
|
@@ -203,11 +333,97 @@ Baseline (pre-change) command results — treat any failure listed here as PRE-E
|
|
|
203
333
|
${baseline}
|
|
204
334
|
|
|
205
335
|
Component results:
|
|
206
|
-
${summary}
|
|
336
|
+
${summary}${skipped}
|
|
207
337
|
|
|
208
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.
|
|
209
339
|
|
|
210
|
-
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)}`
|
|
341
|
+
}
|
|
342
|
+
|
|
343
|
+
// The user should be asked as little as possible: "decide" is the exception, "fix" the default.
|
|
344
|
+
const TRIAGE_RULE = `Set an action on every finding:
|
|
345
|
+
- fix: you are confident it is real and the fix is concrete — a bug, a security issue, a breach of a repository standard, a style finding, or a clearly better way to do the same thing (simpler, reuses existing code, more robust). This is the default.
|
|
346
|
+
- decide: ONLY when the right fix depends on a product, API, data, or security trade-off the plan does not settle, or the fix would contradict the plan. Say in reason which decision the user must make.
|
|
347
|
+
- skip: you could not confirm it by reading the code, it is outside these files, or the gain is marginal. Say why in reason.
|
|
348
|
+
Check uncertain findings against the code yourself before choosing; never pass uncertainty on as decide. Give line, severity (error for bugs and security, warning for likely problems, suggestion for improvements), description, and the concrete fix. Do not edit any file.`
|
|
349
|
+
|
|
350
|
+
function reviewScope(a, files) {
|
|
351
|
+
return `Review the changes since commit ${a.fixedPoint || 'HEAD'} in exactly these files — they are uncommitted in the working tree; read untracked ones whole, since git diff omits them:
|
|
352
|
+
${files.map(f => ` - ${f}`).join('\n')}
|
|
353
|
+
Ignore every other change in the working tree.`
|
|
354
|
+
}
|
|
355
|
+
|
|
356
|
+
function correctnessPrompt(a, files) {
|
|
357
|
+
return `You are a Code Reviewer. ${reviewScope(a, files)}
|
|
358
|
+
|
|
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).
|
|
360
|
+
|
|
361
|
+
${TRIAGE_RULE}${noAdvisorBlock(a)}`
|
|
362
|
+
}
|
|
363
|
+
|
|
364
|
+
function securityPrompt(a, files) {
|
|
365
|
+
return `You are a Security Reviewer. ${reviewScope(a, files)}
|
|
366
|
+
|
|
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.
|
|
368
|
+
|
|
369
|
+
${TRIAGE_RULE}${noAdvisorBlock(a)}`
|
|
370
|
+
}
|
|
371
|
+
|
|
372
|
+
function standardsPrompt(a, files) {
|
|
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.
|
|
374
|
+
|
|
375
|
+
${TRIAGE_RULE}${noAdvisorBlock(a)}`
|
|
376
|
+
}
|
|
377
|
+
|
|
378
|
+
function flowPrompt(a, files) {
|
|
379
|
+
return `You are a Flow Reviewer. ${reviewScope(a, files)}
|
|
380
|
+
|
|
381
|
+
A diff reviewer reads file by file; you trace behavior ACROSS these files and the states they run in. Read the entry points, then follow each flow end to end:
|
|
382
|
+
- a fresh install with no earlier state: missing directories, files, config, or database rows;
|
|
383
|
+
- an upgrade from the previous version, and an update that stops halfway;
|
|
384
|
+
- the order of operations across files: what is written, uploaded, loaded, or required first, and what breaks when that order changes or one step fails;
|
|
385
|
+
- output, headers, or side effects that happen before guards, error handling, or error suppression are in place;
|
|
386
|
+
- files and helpers the change relies on but does not check, and tests that assert the old order or state.
|
|
387
|
+
Report only failures you can describe as a concrete sequence of states.
|
|
388
|
+
|
|
389
|
+
${TRIAGE_RULE}${noAdvisorBlock(a)}`
|
|
390
|
+
}
|
|
391
|
+
|
|
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')
|
|
406
|
+
const dirty = (a.dirty || []).join(', ') || 'none'
|
|
407
|
+
return `You are a Review Fixer. Apply these review findings:
|
|
408
|
+
${list}
|
|
409
|
+
|
|
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.
|
|
411
|
+
|
|
412
|
+
Return structured output: one item per finding id (applied, rejected, or failed, with a one-line note) and filesModified.${noAdvisorBlock(a)}`
|
|
413
|
+
}
|
|
414
|
+
|
|
415
|
+
function checksPrompt(a, files) {
|
|
416
|
+
const baseline = (a.baseline && a.baseline.length)
|
|
417
|
+
? a.baseline.map(b => ` ${b.command || '?'}: ${b.status}`).join('\n')
|
|
418
|
+
: ' (none recorded)'
|
|
419
|
+
return `You are the final Checks agent. Identify the commands from ${a.paths.config} and, only as needed, the project manifests (package.json, Makefile, pyproject.toml, Cargo.toml, Gradle files). Run every available command in the categories build, test, e2e, and lint; skip a category only when no command exists or it is configured as none.
|
|
420
|
+
|
|
421
|
+
Baseline (pre-change) results — a failure listed here is pre-existing; report it as pre-existing:
|
|
422
|
+
${baseline}
|
|
423
|
+
|
|
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.
|
|
425
|
+
|
|
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)}`
|
|
211
427
|
}
|
|
212
428
|
|
|
213
429
|
// ── Helpers ──────────────────────────────────────────────────────────────────
|
|
@@ -219,15 +435,21 @@ function modelOpts(model) {
|
|
|
219
435
|
|
|
220
436
|
// A crashed agent (null result) counts as failed: an infra error should not be treated more
|
|
221
437
|
// harshly than a clean structured failure. verify "failed" alone is no retry reason: it can come
|
|
222
|
-
// from pre-existing issues, which the verifier separates using the baseline.
|
|
438
|
+
// from pre-existing issues, which the verifier separates using the baseline. "blocked" is no retry
|
|
439
|
+
// reason either: no model can build on a file that does not exist yet, so it waits for the next step.
|
|
223
440
|
function needsRetry(result) {
|
|
224
441
|
return result == null || result.status === 'failed'
|
|
225
442
|
}
|
|
226
443
|
|
|
227
|
-
|
|
228
|
-
|
|
444
|
+
function isBlocked(item) {
|
|
445
|
+
return !!item.result && item.result.status === 'blocked'
|
|
446
|
+
}
|
|
447
|
+
|
|
448
|
+
// Retries escalate to opus. With the advisor available, the first retry stays on the planned model
|
|
449
|
+
// (at least sonnet) and only the second escalates. Only a component planned as opus consults the advisor.
|
|
229
450
|
function retryModel(c, attempt, a) {
|
|
230
|
-
|
|
451
|
+
if (!(a.advisor && attempt === 1)) return 'opus'
|
|
452
|
+
return c.model === 'haiku' || !c.model ? 'sonnet' : c.model
|
|
231
453
|
}
|
|
232
454
|
|
|
233
455
|
// Runs one component and retries it up to twice, handing each retry the previous failure.
|
|
@@ -249,8 +471,8 @@ async function runComponent(c, a) {
|
|
|
249
471
|
return item
|
|
250
472
|
}
|
|
251
473
|
|
|
252
|
-
async function runStep(step,
|
|
253
|
-
const stepComps =
|
|
474
|
+
async function runStep(step, plan, a) {
|
|
475
|
+
const stepComps = plan.pendingComponents.filter(c => step.components.includes(c.name))
|
|
254
476
|
let items
|
|
255
477
|
if (step.mode === 'parallel') {
|
|
256
478
|
// Fire every parallel component together, retries included — true concurrency, one wave.
|
|
@@ -263,20 +485,156 @@ async function runStep(step, components, a) {
|
|
|
263
485
|
return { step: step.number, name: step.name, mode: step.mode, items }
|
|
264
486
|
}
|
|
265
487
|
|
|
488
|
+
// Reruns blocked components in place, once the step that should create what they need has run.
|
|
489
|
+
async function rerunBlocked(items, a, afterStep) {
|
|
490
|
+
log(`rerun ${items.length} blocked component(s): ${items.map(i => `${i.component.name} (${i.result.blockedBy || '?'})`).join(', ')}`)
|
|
491
|
+
await parallel(items.map(item => async () => {
|
|
492
|
+
const again = await runComponent(item.component, a)
|
|
493
|
+
if (again.result) item.result = again.result
|
|
494
|
+
item.retried = item.retried || again.retried
|
|
495
|
+
item.escalated = item.escalated || again.escalated
|
|
496
|
+
item.lastTry = afterStep
|
|
497
|
+
}))
|
|
498
|
+
}
|
|
499
|
+
|
|
500
|
+
const stripDot = f => f.replace(/^\.\//, '')
|
|
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
|
+
|
|
525
|
+
// Review the run's files, triage the findings, fix every clear one, then rerun build/test/lint.
|
|
526
|
+
async function reviewAndFix(a, plan, allItems, verification, usedOpus) {
|
|
527
|
+
const runFiles = [...new Set(allItems.flatMap(i => [
|
|
528
|
+
...(i.component.files || []), i.component.sourceFile,
|
|
529
|
+
...(i.result ? [...(i.result.filesCreated || []), ...(i.result.filesModified || [])] : [])
|
|
530
|
+
]).filter(Boolean).map(stripDot))]
|
|
531
|
+
const dirty = new Set((a.dirty || []).map(stripDot))
|
|
532
|
+
|
|
533
|
+
phase('Review')
|
|
534
|
+
const reviewers = [
|
|
535
|
+
{ key: 'correctness', prompt: correctnessPrompt, model: 'sonnet' },
|
|
536
|
+
{ key: 'standards', prompt: standardsPrompt, model: 'sonnet' }
|
|
537
|
+
]
|
|
538
|
+
if (plan.securitySensitive) reviewers.push({ key: 'security', prompt: securityPrompt, model: 'sonnet' })
|
|
539
|
+
if (plan.lifecycleSensitive || plan.securitySensitive) reviewers.push({ key: 'flow', prompt: flowPrompt, model: 'opus' })
|
|
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
|
+
)
|
|
548
|
+
const missing = reviewers.filter((r, n) => !reports[n]).map(r => r.key)
|
|
549
|
+
if (missing.length) log(`reviewer(s) returned nothing: ${missing.join(', ')}`)
|
|
550
|
+
|
|
551
|
+
// Dedup by file and line, keep only the run's files; findings in pre-run dirty files are reported, never fixed.
|
|
552
|
+
const findings = []
|
|
553
|
+
const seen = new Set()
|
|
554
|
+
let outside = 0
|
|
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) {
|
|
559
|
+
const file = stripDot(f.file)
|
|
560
|
+
if (!runFiles.includes(file)) { outside++; continue }
|
|
561
|
+
const key = `${file}:${f.line || 0}`
|
|
562
|
+
if (f.line && seen.has(key)) continue
|
|
563
|
+
seen.add(key)
|
|
564
|
+
const finding = { ...f, file, id: `R${findings.length + 1}` }
|
|
565
|
+
if (dirty.has(file) && finding.action !== 'skip') {
|
|
566
|
+
finding.action = 'report'
|
|
567
|
+
finding.reason = 'pre-run dirty file: may sit in your own earlier work, left untouched'
|
|
568
|
+
}
|
|
569
|
+
findings.push(finding)
|
|
570
|
+
}
|
|
571
|
+
if (outside) log(`review: dropped ${outside} finding(s) outside the run's files`)
|
|
572
|
+
|
|
573
|
+
phase('Fix')
|
|
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 })
|
|
580
|
+
.catch(() => null)
|
|
581
|
+
for (const f of toFix) {
|
|
582
|
+
const item = out && out.items.find(i => i.id === f.id)
|
|
583
|
+
f.status = item ? item.status : 'failed'
|
|
584
|
+
if (item && item.note) f.note = item.note
|
|
585
|
+
}
|
|
586
|
+
}
|
|
587
|
+
const applied = findings.filter(f => f.status === 'applied').length
|
|
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`)
|
|
589
|
+
|
|
590
|
+
// The inline fast path ran no build/test yet, and applied fixes change what the verifier saw.
|
|
591
|
+
let checks = null
|
|
592
|
+
if (applied || verification.inline) {
|
|
593
|
+
checks = await agent(checksPrompt(a, runFiles), { label: 'checks', phase: 'Fix', ...modelOpts(usedOpus ? 'opus' : 'sonnet'), schema: CHECKS_SCHEMA })
|
|
594
|
+
}
|
|
595
|
+
return { reviewers: reviewers.map(r => r.key), missing, runFiles, findings, checks }
|
|
596
|
+
}
|
|
597
|
+
|
|
266
598
|
// ── Main ─────────────────────────────────────────────────────────────────────
|
|
267
599
|
|
|
268
600
|
const a = args || {}
|
|
269
601
|
|
|
270
602
|
phase('Orchestrate')
|
|
271
|
-
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 })
|
|
272
604
|
const steps = plan.steps
|
|
273
605
|
const components = plan.pendingComponents
|
|
606
|
+
// Executors get the approach summary as context.
|
|
607
|
+
const ctx = { ...a, summary: plan.summary }
|
|
274
608
|
|
|
275
609
|
phase('Execute')
|
|
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.
|
|
276
612
|
const results = []
|
|
277
|
-
|
|
278
|
-
|
|
613
|
+
let waiting = []
|
|
614
|
+
const late = []
|
|
615
|
+
for (let n = 0; n < steps.length; n++) {
|
|
616
|
+
const r = await runStep(steps[n], plan, ctx)
|
|
617
|
+
results.push(r)
|
|
618
|
+
// A blocked component from the previous step that fails on its rerun stops the run too.
|
|
619
|
+
let rerunFailed = []
|
|
620
|
+
if (waiting.length) {
|
|
621
|
+
await rerunBlocked(waiting, ctx, n)
|
|
622
|
+
late.push(...waiting.filter(isBlocked))
|
|
623
|
+
rerunFailed = waiting.filter(i => needsRetry(i.result))
|
|
624
|
+
}
|
|
625
|
+
waiting = r.items.filter(isBlocked)
|
|
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
|
+
}
|
|
279
632
|
}
|
|
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)
|
|
280
638
|
|
|
281
639
|
phase('Verify')
|
|
282
640
|
const allItems = results.flatMap(s => s.items)
|
|
@@ -288,35 +646,46 @@ const mechanical = !usedOpus && !allItems.some(i => i.retried) && components.eve
|
|
|
288
646
|
// Deterministic scope signal: files an executor touched beyond its planned target(s).
|
|
289
647
|
// Tests and import sites are legitimate, so this is reported for the user, never a failure.
|
|
290
648
|
const extraFiles = allItems.flatMap(i => {
|
|
291
|
-
const
|
|
292
|
-
const planned = new Set([i.component.file, i.component.sourceFile].filter(Boolean).map(stripDot))
|
|
649
|
+
const planned = new Set([...(i.component.files || []), i.component.sourceFile].filter(Boolean).map(stripDot))
|
|
293
650
|
const touched = i.result ? [...(i.result.filesCreated || []), ...(i.result.filesModified || [])].map(stripDot) : []
|
|
294
651
|
return touched.filter(f => !planned.has(f)).map(f => ({ component: i.component.name, file: f }))
|
|
295
652
|
})
|
|
296
653
|
if (extraFiles.length) log(`scope: ${extraFiles.length} file(s) touched outside planned targets`)
|
|
297
654
|
let verification
|
|
298
655
|
if (allPassed && mechanical) {
|
|
299
|
-
log('all components passed + mechanical — no verification agent;
|
|
300
|
-
// No shell access here:
|
|
656
|
+
log('all components passed + mechanical — no verification agent; the Checks agent runs build/test, /5:implement the scope check')
|
|
657
|
+
// No shell access here: the Checks agent in reviewAndFix runs build/test, /5:implement the scope check, when it sees inline: true.
|
|
301
658
|
verification = { status: 'passed', completeness: 'passed', infrastructure: 'passed', acceptanceCriteria: 'n/a', commands: [], failures: [], inline: true }
|
|
302
659
|
} else {
|
|
303
|
-
verification = await agent(verifyPrompt(a, results), {
|
|
660
|
+
verification = await agent(verifyPrompt(a, results, skippedSteps), {
|
|
304
661
|
label: 'verify', phase: 'Verify', ...modelOpts(usedOpus ? 'opus' : 'sonnet'), schema: VERIFICATION_SCHEMA
|
|
305
662
|
})
|
|
306
663
|
}
|
|
307
664
|
|
|
308
|
-
//
|
|
665
|
+
// Reviewing a run that did not build wastes the review: the rerun after the fix reviews again.
|
|
666
|
+
let review = null
|
|
667
|
+
if (verification.status === 'failed') {
|
|
668
|
+
log('verification failed — review and fix skipped')
|
|
669
|
+
} else {
|
|
670
|
+
review = await reviewAndFix(a, plan, allItems, verification, usedOpus)
|
|
671
|
+
}
|
|
672
|
+
const checksPassed = !review || !review.checks || review.checks.status === 'passed'
|
|
673
|
+
|
|
674
|
+
// Returned to the /5:implement command for the findings file, the decisions, the scope check, per-step staging, and the report.
|
|
309
675
|
return {
|
|
310
676
|
feature: a.feature,
|
|
677
|
+
summary: plan.summary,
|
|
311
678
|
steps,
|
|
312
679
|
components,
|
|
313
680
|
results: results.map(s => ({
|
|
314
681
|
step: s.step,
|
|
315
682
|
name: s.name,
|
|
316
683
|
mode: s.mode,
|
|
317
|
-
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 }))
|
|
318
685
|
})),
|
|
319
686
|
verification,
|
|
687
|
+
skippedSteps,
|
|
320
688
|
extraFiles,
|
|
321
|
-
|
|
689
|
+
review,
|
|
690
|
+
status: verification.status === 'passed' && checksPassed && !skippedSteps.length ? 'completed' : 'failed'
|
|
322
691
|
}
|