5-phase-workflow 3.1.1 → 3.2.0
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 +0 -1
- package/docs/workflow-guide.md +3 -4
- package/package.json +1 -1
- package/src/agents/step-executor-agent.md +4 -0
- package/src/commands/5/configure.md +24 -25
- package/src/commands/5/implement.md +12 -4
- package/src/references/configure-tables.md +1 -0
- package/src/workflows/5-implement.js +59 -40
package/README.md
CHANGED
|
@@ -25,7 +25,6 @@ Then configure the project once:
|
|
|
25
25
|
|
|
26
26
|
```bash
|
|
27
27
|
/5:configure
|
|
28
|
-
/5:implement CONFIGURE
|
|
29
28
|
```
|
|
30
29
|
|
|
31
30
|
This adds the foifi rules to `AGENTS.md` as one marked block, links your existing standards from it, and makes `CLAUDE.md` include it. Nothing else in your files or settings changes.
|
package/docs/workflow-guide.md
CHANGED
|
@@ -56,7 +56,7 @@ A compact plan (1-2 files, no migration, security/auth, or public API change) is
|
|
|
56
56
|
A full plan goes through four steps:
|
|
57
57
|
|
|
58
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.
|
|
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), executors consult Claude Code's advisor tool at hard decisions and the first retry stays on the planned model; turn the advisor on with `/advisor opus`.
|
|
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
61
|
4. `/5:review` runs once on the files the run changed — `code-review`, `security-review` for security-sensitive files, and `review-style` — and `/5:address-review-findings` then fixes the clear findings on its own and asks you only about real decisions, one question at a time. Auto-commit comes after, so approved fixes land in the same commit.
|
|
62
62
|
|
|
@@ -90,10 +90,9 @@ First-time setup:
|
|
|
90
90
|
|
|
91
91
|
```text
|
|
92
92
|
/5:configure
|
|
93
|
-
/5:implement CONFIGURE
|
|
94
93
|
```
|
|
95
94
|
|
|
96
|
-
`/5:configure` writes `.5/config.json`, sets `plansDirectory` to `.5/planning` in `.claude/settings.json`,
|
|
95
|
+
`/5:configure` writes `.5/config.json`, sets `plansDirectory` to `.5/planning` in `.claude/settings.json`, writes the CONFIGURE plan, and then runs `/5:implement CONFIGURE` itself, which adds the workflow rules to AGENTS.md as one marked block that links the repository's own standards, appends `@AGENTS.md` to CLAUDE.md when it lacks that line, and generates scoped rules. Nothing outside the block changes.
|
|
97
96
|
|
|
98
97
|
Refresh the AGENTS.md block and the rules later with:
|
|
99
98
|
|
|
@@ -135,5 +134,5 @@ v2.0.0 removes old commands during upgrade:
|
|
|
135
134
|
| `/5:review` | Review changes for correctness and standards |
|
|
136
135
|
| `/5:address-review-findings` | Fix clear findings, ask about real decisions |
|
|
137
136
|
| `/5:analyze-feature` | Document a feature with mermaid diagrams |
|
|
138
|
-
| `/5:configure` | Create project config and CONFIGURE plan |
|
|
137
|
+
| `/5:configure` | Create project config and CONFIGURE plan, then implement it |
|
|
139
138
|
| `/5:reconfigure` | Refresh the AGENTS.md block and rules |
|
package/package.json
CHANGED
|
@@ -19,6 +19,10 @@ You follow the plan, your component, and existing codebase patterns. You do not
|
|
|
19
19
|
6. 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.
|
|
20
20
|
7. Fix local mechanical issues you caused. Stop for architectural changes, auth gates, missing external services, or unclear product decisions.
|
|
21
21
|
|
|
22
|
+
## Advisor (opt-in)
|
|
23
|
+
|
|
24
|
+
Only when `/5:implement` says the advisor is enabled (`.5/config.json` `advisor: true`) and 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. On a retry, consult it before your first edit.
|
|
25
|
+
|
|
22
26
|
## Simplicity
|
|
23
27
|
|
|
24
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 file and what it strictly needs (its test, an import site). Follow `Simplicity First` in the project `AGENTS.md`.
|
|
@@ -1,15 +1,15 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: 5:configure
|
|
3
|
-
description: Configures the project. Analyzes project, gathers preferences, writes config.json, points Claude Code plan mode at .5/planning/,
|
|
4
|
-
allowed-tools: Read, Write,
|
|
3
|
+
description: Configures the project. Analyzes project, gathers preferences, writes config.json, points Claude Code plan mode at .5/planning/, creates .5/planning/CONFIGURE.md, then runs /5:implement CONFIGURE itself.
|
|
4
|
+
allowed-tools: Agent, Read, Write, Edit, Glob, Grep, Bash, Workflow, Skill, AskUserQuestion
|
|
5
5
|
user-invocable: true
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
<role>
|
|
9
9
|
You are a Project Configurator. You analyze a project, gather preferences, and write config.json plus a unified plan.
|
|
10
|
-
You do NOT write AGENTS.md, CLAUDE.md, or rules directly — those are /5:implement's job.
|
|
10
|
+
You do NOT write AGENTS.md, CLAUDE.md, or rules directly — those are /5:implement's job, and you start it yourself once the plan is written.
|
|
11
11
|
You write ONLY to: .5/config.json, .5/version.json, .5/planning/CONFIGURE.md, .gitignore, and the `plansDirectory` key of .claude/settings.json (Claude Code only).
|
|
12
|
-
After writing config.json and the unified plan, you
|
|
12
|
+
After writing config.json and the unified plan, you hand off to `/5:implement CONFIGURE`.
|
|
13
13
|
</role>
|
|
14
14
|
|
|
15
15
|
# Configure (Project Setup Plan)
|
|
@@ -18,16 +18,11 @@ Current commit: !`git rev-parse --short HEAD 2>/dev/null || echo "none"`
|
|
|
18
18
|
|
|
19
19
|
## Overview
|
|
20
20
|
|
|
21
|
-
This command prepares project configuration. It analyzes the project, asks preference questions, writes `.5/config.json`, points Claude Code plan mode at `.5/planning/`,
|
|
22
|
-
|
|
23
|
-
After running this command, proceed through the standard phases:
|
|
24
|
-
1. **`/5:configure`** (this command) - Create config and CONFIGURE plan
|
|
25
|
-
2. `/5:implement CONFIGURE` - Execute configuration (uses `configure-agents-md` and `configure-rules`)
|
|
26
|
-
3. `/5:review` - Review generated files if desired
|
|
21
|
+
This command prepares project configuration. It analyzes the project, asks preference questions, writes `.5/config.json`, points Claude Code plan mode at `.5/planning/`, writes a plan at `.5/planning/CONFIGURE.md`, and then runs `/5:implement CONFIGURE` itself, which executes the plan with `configure-agents-md` and `configure-rules` and reviews the result. The user runs only this one command.
|
|
27
22
|
|
|
28
23
|
## ⚠️ CRITICAL SCOPE CONSTRAINT
|
|
29
24
|
|
|
30
|
-
**THIS COMMAND WRITES config.json AND CREATES THE CONFIGURE PLAN
|
|
25
|
+
**THIS COMMAND WRITES config.json AND CREATES THE CONFIGURE PLAN, THEN HANDS OFF TO `/5:implement CONFIGURE`. NOTHING ELSE.**
|
|
31
26
|
|
|
32
27
|
Your job in this command:
|
|
33
28
|
✅ Analyze project (detect type, build commands, etc.)
|
|
@@ -35,7 +30,7 @@ Your job in this command:
|
|
|
35
30
|
✅ Write `.5/config.json` directly
|
|
36
31
|
✅ Set `plansDirectory` in `.claude/settings.json` (Claude Code only)
|
|
37
32
|
✅ Create the plan at `.5/planning/CONFIGURE.md` for remaining work
|
|
38
|
-
✅
|
|
33
|
+
✅ Run `/5:implement CONFIGURE` right after the plan is written
|
|
39
34
|
|
|
40
35
|
Your job is NOT:
|
|
41
36
|
❌ Write AGENTS.md or CLAUDE.md directly (/5:implement does this)
|
|
@@ -43,9 +38,9 @@ Your job is NOT:
|
|
|
43
38
|
❌ Skip user interaction
|
|
44
39
|
❌ Assume project structure
|
|
45
40
|
|
|
46
|
-
**After writing config.json
|
|
41
|
+
**After writing config.json and the unified plan, run `/5:implement CONFIGURE`. The rest is its job.**
|
|
47
42
|
|
|
48
|
-
**If you find yourself writing AGENTS.md, CLAUDE.md, or rules, STOP IMMEDIATELY. You should only be writing config.json, the settings key, and the plan.**
|
|
43
|
+
**If you find yourself writing AGENTS.md, CLAUDE.md, or rules before `/5:implement CONFIGURE` runs, STOP IMMEDIATELY. You should only be writing config.json, the settings key, and the plan.**
|
|
49
44
|
|
|
50
45
|
## Configuration Process
|
|
51
46
|
|
|
@@ -142,6 +137,12 @@ If "Cancel": Exit immediately with message "Configuration unchanged."
|
|
|
142
137
|
1. "No (recommended)" → `git.autoCommit: false`
|
|
143
138
|
2. "Yes - commit after each implementation step" → `git.autoCommit: true`
|
|
144
139
|
|
|
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."
|
|
142
|
+
- Options:
|
|
143
|
+
1. "No (recommended)" → `advisor: false`
|
|
144
|
+
2. "Yes" → `advisor: true`
|
|
145
|
+
|
|
145
146
|
**2g. Commit message pattern:**
|
|
146
147
|
|
|
147
148
|
When the repository already documents a commit convention (step 1e or 1e2), that convention wins and AGENTS.md links it. Skip the question, and derive the closest pattern from the convention with the `{ticket-id}` and `{short-description}` placeholders — for example `feat({ticket-id}): {short-description}` for Conventional Commits — and store it as `git.commitMessage.pattern`, so auto-commits follow the convention too. Otherwise ask:
|
|
@@ -173,6 +174,7 @@ Context7 provides up-to-date, version-specific documentation and code examples d
|
|
|
173
174
|
- "Generate `.claude/rules/` files? These are scoped instruction files that automatically load when the agent works with matching file types (e.g., testing rules load only when editing test files, code-style rules load only for source files)."
|
|
174
175
|
- Options: "Yes (recommended)", "Skip"
|
|
175
176
|
- Note: Rules complement AGENTS.md — they provide focused, file-type-scoped directives derived from your project's actual conventions.
|
|
177
|
+
- On Codex, the rules live in the foifi block of `AGENTS.md`. When the user skipped AGENTS.md in step 2j, do not ask: set `rules.generate` to `false`.
|
|
176
178
|
|
|
177
179
|
**2l. Git-ignore workflow folders:**
|
|
178
180
|
- "`.5/planning/` will hold your plans. `.5/features/` will hold implementation state and review findings. Which should git ignore?"
|
|
@@ -193,7 +195,7 @@ Using the values gathered from Steps 1 and 2, write `.5/config.json` directly.
|
|
|
193
195
|
mkdir -p .5
|
|
194
196
|
```
|
|
195
197
|
|
|
196
|
-
**Schema:** Read `.claude/references/configure-tables.md` section "Config Schema" for the full JSON structure. Fill all values from user responses (including `rules.generate` from step 2j2). Write with pretty-printed JSON. Read back to verify correctness.
|
|
198
|
+
**Schema:** Read `.claude/references/configure-tables.md` section "Config Schema" for the full JSON structure. Fill all values from user responses (including `advisor` from step 2f2 and `rules.generate` from step 2j2). Write with pretty-printed JSON. Read back to verify correctness.
|
|
197
199
|
|
|
198
200
|
**Update `.5/version.json` with configure timestamp:**
|
|
199
201
|
|
|
@@ -227,7 +229,9 @@ Ensure `.5/.reconfig-reminder` is gitignored (it's a transient runtime flag that
|
|
|
227
229
|
|
|
228
230
|
### Step 3: Create Configuration Plan
|
|
229
231
|
|
|
230
|
-
|
|
232
|
+
If the user skipped both AGENTS.md (step 2j) and rules (step 2j2), there is nothing to implement: delete `.5/planning/CONFIGURE.md` if an earlier run left it, so no later `/5:implement` applies what the user just declined. Then skip Steps 3 and 4, tell the user "Configuration saved to `.5/config.json`", and stop.
|
|
233
|
+
|
|
234
|
+
Otherwise write `.5/planning/CONFIGURE.md` containing all gathered data. When the user skipped AGENTS.md in step 2j, leave out everything about AGENTS.md and CLAUDE.md: the `configure agents md` component, Requirement 1, its acceptance criteria and Module Impact row, and the "After configure agents md" ordering. The plan then generates only the rules, and nothing touches `AGENTS.md` or `CLAUDE.md`. The template below shows the plan with both selected:
|
|
231
235
|
|
|
232
236
|
```markdown
|
|
233
237
|
---
|
|
@@ -324,21 +328,16 @@ Only generate rules for patterns that were actually detected:
|
|
|
324
328
|
|
|
325
329
|
## Next Steps
|
|
326
330
|
|
|
327
|
-
1.
|
|
331
|
+
1. `/5:configure` runs `/5:implement CONFIGURE` right away; rerun it by hand only if that run was interrupted.
|
|
328
332
|
```
|
|
329
333
|
|
|
330
334
|
**Important:** Use `mkdir -p .5/planning` before writing the plan.
|
|
331
335
|
|
|
332
|
-
### Step 4:
|
|
336
|
+
### Step 4: Run the Plan
|
|
333
337
|
|
|
334
|
-
Tell the user:
|
|
338
|
+
Tell the user in one line: "Configuration saved to `.5/config.json`, plan written to `.5/planning/CONFIGURE.md` — implementing it now."
|
|
335
339
|
|
|
336
|
-
|
|
337
|
-
2. "Configuration plan written to `.5/planning/CONFIGURE.md`"
|
|
338
|
-
3. "Next steps:"
|
|
339
|
-
- "Run `/clear` to reset context"
|
|
340
|
-
- "Then run `/5:implement CONFIGURE`"
|
|
341
|
-
4. "After that: Run `/5:review` if you want a review of generated files"
|
|
340
|
+
Then run `/5:implement CONFIGURE` right away, without asking: the user already chose what to generate in Step 2. It writes the AGENTS.md block and the rules, verifies them, and runs `/5:review` on the result.
|
|
342
341
|
|
|
343
342
|
## Related Documentation
|
|
344
343
|
- [configure-agents-md skill](../../skills/configure-agents-md/SKILL.md)
|
|
@@ -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. Nothing is persisted between runs; a rerun starts over, and executors see work that is already done in the files.
|
|
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` and the runtime is Claude Code; 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
|
|
|
@@ -59,12 +59,14 @@ It moves orchestration into deterministic JS, fires parallel components concurre
|
|
|
59
59
|
"feature": "{feature-name}",
|
|
60
60
|
"paths": {"plan": "{plan-path}", "config": ".5/config.json"},
|
|
61
61
|
"standards": {"repo": ["CONTRIBUTING.md"], "styles": ["/abs/path/.claude/skills/fowler-code-smells/SKILL.md"]},
|
|
62
|
-
"baseline": [{"command": "...", "status": "passed|failed|skipped", "summary": "one line"}]
|
|
62
|
+
"baseline": [{"command": "...", "status": "passed|failed|skipped", "summary": "one line"}],
|
|
63
|
+
"advisor": false
|
|
63
64
|
}
|
|
64
65
|
```
|
|
65
66
|
|
|
66
67
|
- `standards` holds the repository standards and style skill paths from Step 1. Executors follow them while writing code.
|
|
67
68
|
- `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 the executors and keeps their first retry on the planned model.
|
|
68
70
|
- The workflow reads the config **file** at `paths.config` itself; do not pass build/test/commit settings inline.
|
|
69
71
|
|
|
70
72
|
2. If the returned `verification.inline` is `true` (every component was mechanical and passed, so no verification agent ran), run the **fast-path check** (3c) and take its result as the verification.
|
|
@@ -86,7 +88,7 @@ For each step:
|
|
|
86
88
|
2. Spawn executors with the component's model. Run `opus` at `effort: "medium"`.
|
|
87
89
|
- **Parallel step: emit all of the step's executor Agent calls in a single message so they run concurrently.**
|
|
88
90
|
- Sequential step (same-file or dependency): one executor at a time.
|
|
89
|
-
- Give each executor only its component block, required `patternRefs`, verify commands, the standards from Step 1, and the inline contract below — do not make it read `step-executor-agent.md`.
|
|
91
|
+
- Give each executor only its component block, required `patternRefs`, verify commands, the standards from Step 1, and the inline contract below — do not make it read `step-executor-agent.md`. When the advisor is enabled, append the advisor line after the contract.
|
|
90
92
|
|
|
91
93
|
```text
|
|
92
94
|
Implement exactly the assigned component. Read only listed patternRefs ranges/symbols and the target file. 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 file and what it strictly needs (its test, an import site) — run assigned verify commands, and stop (STATUS: failed) for missing dependencies, 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.
|
|
@@ -103,9 +105,15 @@ ERROR: none | {error description}
|
|
|
103
105
|
---END---
|
|
104
106
|
```
|
|
105
107
|
|
|
108
|
+
Advisor line (only when the advisor is enabled):
|
|
109
|
+
|
|
110
|
+
```text
|
|
111
|
+
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.
|
|
112
|
+
```
|
|
113
|
+
|
|
106
114
|
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.
|
|
107
115
|
|
|
108
|
-
Retry failed
|
|
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 stays on the component's planned model and asks the executor to consult the advisor before its first edit; only the second escalates to `opus`. 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.
|
|
109
117
|
|
|
110
118
|
#### 3c. Verify
|
|
111
119
|
|
|
@@ -19,7 +19,9 @@ export const meta = {
|
|
|
19
19
|
// auto-commit after this returns. Nothing is persisted: a rerun starts over.
|
|
20
20
|
//
|
|
21
21
|
// Models: haiku for mechanical work, sonnet for ordinary logic, opus at effort
|
|
22
|
-
// medium for complex work and for every retry.
|
|
22
|
+
// medium for complex work and for every retry. With args.advisor (opt-in, from
|
|
23
|
+
// .5/config.json) executors consult Claude Code's advisor tool at decision points
|
|
24
|
+
// and the first retry stays on the planned model.
|
|
23
25
|
// ─────────────────────────────────────────────────────────────────────────────
|
|
24
26
|
|
|
25
27
|
const RESULT_SCHEMA = {
|
|
@@ -141,15 +143,24 @@ The plan has no fixed shape. Derive the components from whatever it describes: o
|
|
|
141
143
|
Return an object matching the schema (steps[] and pendingComponents[]).`
|
|
142
144
|
}
|
|
143
145
|
|
|
146
|
+
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
|
+
|
|
148
|
+
function retryContext(previous, a) {
|
|
149
|
+
const failure = previous
|
|
150
|
+
? `status ${previous.status}, verify ${previous.verify}, error: ${previous.error || 'none'}, deviations: ${previous.deviations || 'none'}`
|
|
151
|
+
: '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 it, find the root cause, and correct it.${advisor}`
|
|
154
|
+
}
|
|
155
|
+
|
|
144
156
|
function executorPrompt(c, a, opts) {
|
|
145
157
|
const refs = (c.patternRefs || []).map(r => ` - ${r.file}${r.read ? ` (${r.read})` : ''}${r.reason ? ` — ${r.reason}` : ''}`).join('\n') || ' - none'
|
|
146
158
|
const verify = (c.verifyCommands || []).join(' && ') || 'infer the narrowest relevant test/build command'
|
|
147
159
|
const standards = a.standards || {}
|
|
148
160
|
const repoStandards = (standards.repo || []).map(f => ` - ${f}`).join('\n') || ' - none found'
|
|
149
161
|
const styles = (standards.styles || []).map(f => ` - ${f}`).join('\n') || ' - none found'
|
|
150
|
-
const retry = opts && opts.retry
|
|
151
|
-
|
|
152
|
-
: ''
|
|
162
|
+
const retry = opts && opts.retry ? `\n${retryContext(opts.result, a)}` : ''
|
|
163
|
+
const advisor = a.advisor ? `\n\n${ADVISOR_RULE}` : ''
|
|
153
164
|
return `You are a Step Executor. Implement EXACTLY this component and nothing more.${retry}
|
|
154
165
|
|
|
155
166
|
Component: ${c.name}
|
|
@@ -166,7 +177,7 @@ ${repoStandards}
|
|
|
166
177
|
Style skills:
|
|
167
178
|
${styles}
|
|
168
179
|
|
|
169
|
-
Rules: 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. 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 file and what it strictly needs (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). STOP and report failed for missing dependencies, 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
|
|
180
|
+
Rules: 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. 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 file and what it strictly needs (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). STOP and report failed for missing dependencies, 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}
|
|
170
181
|
|
|
171
182
|
Then run: ${verify}
|
|
172
183
|
|
|
@@ -175,7 +186,7 @@ Return structured output: status, filesCreated, filesModified, verify, deviation
|
|
|
175
186
|
|
|
176
187
|
function verifyPrompt(a, results) {
|
|
177
188
|
const ran = results.flatMap(s => s.items.map(i =>
|
|
178
|
-
` step ${s.step} ${i.component.name}: ${i.result ? i.result.status : 'no result'} (verify ${i.result ? i.result.verify : '?'})${i.escalated ? ' [escalated to opus]' : ''}`))
|
|
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]' : ''}`))
|
|
179
190
|
const summary = ran.join('\n') || ' (no components ran)'
|
|
180
191
|
const repoStandards = ((a.standards && a.standards.repo) || []).join(', ') || 'none found'
|
|
181
192
|
const baseline = (a.baseline && a.baseline.length)
|
|
@@ -206,42 +217,50 @@ function modelOpts(model) {
|
|
|
206
217
|
return model === 'opus' ? { model: 'opus', effort: 'medium' } : { model: model || 'haiku' }
|
|
207
218
|
}
|
|
208
219
|
|
|
220
|
+
// A crashed agent (null result) counts as failed: an infra error should not be treated more
|
|
221
|
+
// 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.
|
|
223
|
+
function needsRetry(result) {
|
|
224
|
+
return result == null || result.status === 'failed'
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
// Retries escalate to opus. With the advisor opted in, the first retry stays on the planned model
|
|
228
|
+
// and consults the advisor instead; only the second escalates.
|
|
229
|
+
function retryModel(c, attempt, a) {
|
|
230
|
+
return a.advisor && attempt === 1 ? c.model : 'opus'
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
// Runs one component and retries it up to twice, handing each retry the previous failure.
|
|
234
|
+
async function runComponent(c, a) {
|
|
235
|
+
const run = (model, label, previous) => agent(executorPrompt(c, a, previous),
|
|
236
|
+
{ label, phase: 'Execute', ...modelOpts(model), schema: RESULT_SCHEMA }).catch(() => null)
|
|
237
|
+
|
|
238
|
+
// `last` is the latest attempt, null when it crashed; `item.result` keeps the latest structured result.
|
|
239
|
+
let last = await run(c.model, `exec:${c.name}`)
|
|
240
|
+
const item = { component: c, result: last, retried: false, escalated: false }
|
|
241
|
+
for (let attempt = 1; attempt <= 2 && needsRetry(item.result); attempt++) {
|
|
242
|
+
const model = retryModel(c, attempt, a)
|
|
243
|
+
log(`retry ${c.name} (attempt ${attempt + 1}) on ${model || 'haiku'}`)
|
|
244
|
+
item.retried = true
|
|
245
|
+
item.escalated = item.escalated || model === 'opus'
|
|
246
|
+
last = await run(model, `retry:${c.name}`, { retry: true, result: last })
|
|
247
|
+
if (last) item.result = last
|
|
248
|
+
}
|
|
249
|
+
return item
|
|
250
|
+
}
|
|
251
|
+
|
|
209
252
|
async function runStep(step, components, a) {
|
|
210
253
|
const stepComps = components.filter(c => step.components.includes(c.name))
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
// Fire every parallel component together — true concurrency, one wave.
|
|
216
|
-
waveResults = await parallel(stepComps.map(c => () =>
|
|
217
|
-
agent(executorPrompt(c, a), { label: `exec:${c.name}`, phase: 'Execute', ...modelOpts(c.model), schema: RESULT_SCHEMA })
|
|
218
|
-
.then(result => ({ component: c, result }))
|
|
219
|
-
.catch(() => ({ component: c, result: null }))))
|
|
254
|
+
let items
|
|
255
|
+
if (step.mode === 'parallel') {
|
|
256
|
+
// Fire every parallel component together, retries included — true concurrency, one wave.
|
|
257
|
+
items = await parallel(stepComps.map(c => () => runComponent(c, a)))
|
|
220
258
|
} else {
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
.catch(() => null)
|
|
225
|
-
waveResults.push({ component: c, result })
|
|
226
|
-
}
|
|
259
|
+
// Sequential components depend on each other, so each one is retried before the next starts.
|
|
260
|
+
items = []
|
|
261
|
+
for (const c of stepComps) items.push(await runComponent(c, a))
|
|
227
262
|
}
|
|
228
|
-
|
|
229
|
-
// Retry failed OR crashed (null) components up to twice, escalating to opus.
|
|
230
|
-
// A crashed agent (null result) is retried too — an infra error should not be
|
|
231
|
-
// treated more harshly than a clean structured failure.
|
|
232
|
-
for (const wr of waveResults) {
|
|
233
|
-
let attempt = 1
|
|
234
|
-
while ((wr.result == null || wr.result.status === 'failed') && attempt <= 2) {
|
|
235
|
-
log(`retry ${wr.component.name} (attempt ${attempt + 1}) on opus`)
|
|
236
|
-
wr.escalated = true
|
|
237
|
-
const retried = await agent(executorPrompt(wr.component, a, { retry: true }),
|
|
238
|
-
{ label: `retry:${wr.component.name}`, phase: 'Execute', ...modelOpts('opus'), schema: RESULT_SCHEMA }).catch(() => null)
|
|
239
|
-
if (retried) wr.result = retried
|
|
240
|
-
attempt++
|
|
241
|
-
}
|
|
242
|
-
}
|
|
243
|
-
|
|
244
|
-
return { step: step.number, name: step.name, mode: step.mode, items: waveResults }
|
|
263
|
+
return { step: step.number, name: step.name, mode: step.mode, items }
|
|
245
264
|
}
|
|
246
265
|
|
|
247
266
|
// ── Main ─────────────────────────────────────────────────────────────────────
|
|
@@ -265,7 +284,7 @@ const allPassed = allItems.length > 0 && allItems.every(i => i.result && i.resul
|
|
|
265
284
|
// Mechanical when every component was planned as haiku and none needed a retry; anything
|
|
266
285
|
// else signals reasoning-level work that warrants the full verification agent.
|
|
267
286
|
const usedOpus = components.some(c => c.model === 'opus') || allItems.some(i => i.escalated)
|
|
268
|
-
const mechanical = !usedOpus && components.every(c => (c.model || 'haiku') === 'haiku')
|
|
287
|
+
const mechanical = !usedOpus && !allItems.some(i => i.retried) && components.every(c => (c.model || 'haiku') === 'haiku')
|
|
269
288
|
// Deterministic scope signal: files an executor touched beyond its planned target(s).
|
|
270
289
|
// Tests and import sites are legitimate, so this is reported for the user, never a failure.
|
|
271
290
|
const extraFiles = allItems.flatMap(i => {
|
|
@@ -295,7 +314,7 @@ return {
|
|
|
295
314
|
step: s.step,
|
|
296
315
|
name: s.name,
|
|
297
316
|
mode: s.mode,
|
|
298
|
-
items: s.items.map(i => ({ component: i.component.name, file: i.component.file, sourceFile: i.component.sourceFile, escalated:
|
|
317
|
+
items: s.items.map(i => ({ component: i.component.name, file: i.component.file, sourceFile: i.component.sourceFile, retried: i.retried, escalated: i.escalated, result: i.result }))
|
|
299
318
|
})),
|
|
300
319
|
verification,
|
|
301
320
|
extraFiles,
|