Skip to content

Commit b630e04

Browse files
Copilotpelikhan
andauthored
Tighten Rig guidance for schema/prompt discoverability and enforce addon ordering (#274)
* Initial plan * Add addon-order lint rule and clarify rig guidance Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
1 parent 59426c8 commit b630e04

8 files changed

Lines changed: 276 additions & 5 deletions

File tree

‎skills/rig/SKILL.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -44,12 +44,13 @@ Defaults: `name: "agent"`, `model: "small"`, `maxTurns: 4`, string input/output,
4444
| Need | Choose |
4545
|------|--------|
4646
| Known required/optional file | `p.read(path)` / `p.readOptional(path, fallback?)` (prefer this over `cat ... || echo ...`) |
47-
| Several known files | `p.readAll(paths)` |
47+
| Several known files | `p.readAll(["path/a.ts", "path/b.ts"])` (explicit array of literal paths) |
4848
| Static shell command | `p.bash(command)`; use ``p.bashRaw`...` `` for literal backslashes |
4949
| Caller-supplied path(s) | `p.readInput(field)` / `p.readAllInput(field)` with `s.path` schemas |
50-
| Discover workspace paths | `p.glob(pattern)` returns paths only; follow with a read intent for contents (prefer over `p.bash("find ...")` for static discovery) |
50+
| Discover workspace paths | `p.glob(pattern)` returns paths only; then delegate one path at a time to a subagent using `p.readInput("path")` (there is no `p.readAll(globPattern)` overload) |
5151
| Persist generated output | `p.writeOutput(field, path)` or `p.writeInput(pathField, outputField)` |
5252
| String-keyed map | `s.record(value)`; keys are always `string` — do not wrap in `s.object`; use `s.record(s.int)` for count maps |
53+
| URL and file-path fields | `s.url` for URIs, `s.path` for paths, and wrappers like `s.array(s.path)` for path lists |
5354
| Numeric schema choice | `s.int` for counts/line numbers; `s.number` for measurements and ratios |
5455
| Optional versus nullable | `s.optional(shape)` for omission; `s.nullable(shape)` for explicit `null` |
5556
| Deterministic TypeScript fan-out | `workflow({ meta, input?, body })` + `export default`; use `call`, `pipeline`, `parallel`, `until` inside `body` |
@@ -64,10 +65,10 @@ Prompt intents are declarative instructions, not in-process operations. Prefer f
6465
- `agents` is a named object, never an array; every subagent must be reachable from the exported root.
6566
- There is no chain or loop primitive. Tell the coordinator what to delegate, in what order, and what combined output to return.
6667
- `defineTool` uses the two-argument config form. Use `s.object({ ... })` for object-shaped parameters — plain `{ key: s.string }` loses handler arg type inference. Arrow callbacks in handlers must have explicit type annotations: `.map((line: string) => ...)`.
67-
- `repair()` takes no arguments. Turn budgets belong on the agent spec or invocation.
68+
- `repair()` takes no arguments. Turn budgets belong on the agent spec or invocation. Repair turns are parse/schema retry turns; a steering turn is only the last warning prepended to the final repair retry.
6869
- Stable settings belong in `agent({ ... })`; per-run `model`, `maxTurns`, `timeout`, and `signal` belong on invocation; `agent.use()` accepts only addons.
6970
- Valid `agent()` fields: `name`, `instructions`, `input`, `output`, `model`, `maxTurns`, `addons`, `agents`, `systemMessage`, `tools`. Misspelled keys (e.g. `instructions2`) are silently dropped; the linter flags them.
70-
- Handler functions that return string literals must use `as const` to preserve the literal type for enum schema comparison.
71+
- Handler functions that return string literals must use `as const` to preserve the literal type for enum schema comparison. Example: `return "stable" as const`.
7172

7273
## Runnable output
7374

‎skills/rig/eslint/index.js‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import defineToolArgCount from "./rules/define-tool-arg-count.js";
22
import agentsMustBeObject from "./rules/agents-must-be-object.js";
33
import noObjectLiteralRecord from "./rules/no-object-literal-record.js";
44
import repairNoArgs from "./rules/repair-no-args.js";
5+
import addonOrder from "./rules/addon-order.js";
56
import noImplicitAnyInToolHandler from "./rules/no-implicit-any-in-tool-handler.js";
67
import preferPGlobOverBashFind from "./rules/prefer-p-glob-over-bash-find.js";
78
import noInvalidAgentFields from "./rules/no-invalid-agent-fields.js";
@@ -16,6 +17,7 @@ export default {
1617
"agents-must-be-object": agentsMustBeObject,
1718
"no-object-literal-record": noObjectLiteralRecord,
1819
"repair-no-args": repairNoArgs,
20+
"addon-order": addonOrder,
1921
"no-implicit-any-in-tool-handler": noImplicitAnyInToolHandler,
2022
"prefer-p-glob-over-bash-find": preferPGlobOverBashFind,
2123
"no-invalid-agent-fields": noInvalidAgentFields,

‎skills/rig/eslint/lint.js‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,13 @@ import { scanTokens as scanDefineToolArgCount } from "./rules/define-tool-arg-co
77
import { scanTokens as scanAgentsMustBeObject } from "./rules/agents-must-be-object.js";
88
import { scanTokens as scanNoObjectLiteralRecord } from "./rules/no-object-literal-record.js";
99
import { scanTokens as scanRepairNoArgs } from "./rules/repair-no-args.js";
10+
import { scanTokens as scanAddonOrder } from "./rules/addon-order.js";
1011
import { scanTokens as scanNoImplicitAnyInToolHandler } from "./rules/no-implicit-any-in-tool-handler.js";
1112
import { scanTokens as scanPreferPGlobOverBashFind } from "./rules/prefer-p-glob-over-bash-find.js";
1213
import { scanTokens as scanNoInvalidAgentFields } from "./rules/no-invalid-agent-fields.js";
1314

1415
const ignoredDirectories = new Set([".git", "node_modules"]);
15-
const tokenRules = [scanDefineToolArgCount, scanAgentsMustBeObject, scanNoObjectLiteralRecord, scanRepairNoArgs, scanNoImplicitAnyInToolHandler, scanPreferPGlobOverBashFind, scanNoInvalidAgentFields];
16+
const tokenRules = [scanDefineToolArgCount, scanAgentsMustBeObject, scanNoObjectLiteralRecord, scanRepairNoArgs, scanAddonOrder, scanNoImplicitAnyInToolHandler, scanPreferPGlobOverBashFind, scanNoInvalidAgentFields];
1617

1718
function tokenize(source) {
1819
const tokens = [];
Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
function closingBracket(tokens, openingIndex) {
2+
let depth = 0;
3+
for (let index = openingIndex; index < tokens.length; index += 1) {
4+
if (tokens[index].value === "[") depth += 1;
5+
if (tokens[index].value === "]") depth -= 1;
6+
if (depth === 0) return index;
7+
}
8+
return undefined;
9+
}
10+
11+
function parseTopLevelEntries(tokens, source, startIndex, endIndex) {
12+
const entries = [];
13+
let currentStart = startIndex;
14+
let parenDepth = 0;
15+
let bracketDepth = 0;
16+
let braceDepth = 0;
17+
18+
for (let index = startIndex; index < endIndex; index += 1) {
19+
const token = tokens[index];
20+
if (token.value === "(") parenDepth += 1;
21+
if (token.value === ")") parenDepth -= 1;
22+
if (token.value === "[") bracketDepth += 1;
23+
if (token.value === "]") bracketDepth -= 1;
24+
if (token.value === "{") braceDepth += 1;
25+
if (token.value === "}") braceDepth -= 1;
26+
27+
if (
28+
token.value === ","
29+
&& parenDepth === 0
30+
&& bracketDepth === 0
31+
&& braceDepth === 0
32+
) {
33+
const start = tokens[currentStart].start;
34+
const end = token.start;
35+
entries.push({ start, end, text: source.slice(start, end).trim() });
36+
currentStart = index + 1;
37+
}
38+
}
39+
40+
if (currentStart < endIndex) {
41+
const start = tokens[currentStart].start;
42+
const end = tokens[endIndex - 1].end;
43+
entries.push({ start, end, text: source.slice(start, end).trim() });
44+
}
45+
46+
return entries.filter((entry) => entry.text.length > 0);
47+
}
48+
49+
function isRepairCall(text) {
50+
return /^repair\s*\(/.test(text);
51+
}
52+
53+
function isSteeringCall(text) {
54+
return /^steering\s*\(/.test(text);
55+
}
56+
57+
export function scanTokens(tokens, source = "") {
58+
const problems = [];
59+
60+
for (let index = 0; index <= tokens.length - 3; index += 1) {
61+
const [key, colon, openBracket] = tokens.slice(index, index + 3);
62+
if (
63+
key.value !== "addons"
64+
|| colon.value !== ":"
65+
|| openBracket.value !== "["
66+
) {
67+
continue;
68+
}
69+
70+
const closeIndex = closingBracket(tokens, index + 2);
71+
if (closeIndex === undefined) continue;
72+
73+
const entries = parseTopLevelEntries(tokens, source, index + 3, closeIndex);
74+
if (entries.length !== 2) continue;
75+
76+
const repairIndex = entries.findIndex((entry) => isRepairCall(entry.text));
77+
const steeringIndex = entries.findIndex((entry) => isSteeringCall(entry.text));
78+
if (repairIndex === -1 || steeringIndex === -1 || repairIndex > steeringIndex) {
79+
continue;
80+
}
81+
82+
const fixedText = `[${entries[steeringIndex].text}, ${entries[repairIndex].text}]`;
83+
problems.push({
84+
start: openBracket.start,
85+
end: tokens[closeIndex].end,
86+
message: "Use addons: [steering(), repair()] so steering can wrap repair retries.",
87+
kind: "addon-order",
88+
edits: [{ start: openBracket.start, end: tokens[closeIndex].end, text: fixedText }],
89+
});
90+
}
91+
92+
return problems;
93+
}
94+
95+
export default {
96+
meta: {
97+
type: "problem",
98+
docs: {
99+
description: "Enforce addons order as [steering(), repair()]",
100+
},
101+
fixable: "code",
102+
schema: [],
103+
messages: {
104+
order: "Use addons: [steering(), repair()] so steering can wrap repair retries.",
105+
},
106+
},
107+
create(context) {
108+
return {
109+
Property(node) {
110+
if (
111+
node.key.type !== "Identifier"
112+
|| node.key.name !== "addons"
113+
|| node.value.type !== "ArrayExpression"
114+
|| node.value.elements.length !== 2
115+
) {
116+
return;
117+
}
118+
119+
const [first, second] = node.value.elements;
120+
if (
121+
first?.type !== "CallExpression"
122+
|| second?.type !== "CallExpression"
123+
|| first.callee.type !== "Identifier"
124+
|| second.callee.type !== "Identifier"
125+
|| first.callee.name !== "repair"
126+
|| second.callee.name !== "steering"
127+
) {
128+
return;
129+
}
130+
131+
context.report({
132+
node: node.value,
133+
messageId: "order",
134+
fix(fixer) {
135+
const sourceCode = context.sourceCode;
136+
const steeringText = sourceCode.getText(second);
137+
const repairText = sourceCode.getText(first);
138+
return fixer.replaceText(node.value, `[${steeringText}, ${repairText}]`);
139+
},
140+
});
141+
},
142+
};
143+
},
144+
};

‎skills/rig/references/composition.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -160,6 +160,8 @@ export default summarize;
160160

161161
`repair()` takes no options. The budget includes the initial attempt and all retries — for example, `maxTurns: 3` means one initial attempt plus two repair retries. Configure `maxTurns` on the agent spec; a call-time value can override it.
162162

163+
A repair turn is a parse/schema retry attempt after invalid output; steering does not add extra retries, it only injects a stronger warning on the final repair retry.
164+
163165
```ts
164166
// wrong: repair() does not accept maxTurns
165167
addons: repair({ maxTurns: 3 });

‎skills/rig/references/linting.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,20 @@ addons: repair()
7272

7373
The rule removes arguments from `repair(...)` automatically.
7474

75+
### `rig/addon-order`
76+
77+
When both addons are present, order them as `[steering(), repair()]` so steering can augment the final repair retry prompt:
78+
79+
```ts
80+
// Invalid
81+
addons: [repair(), steering()]
82+
83+
// Valid
84+
addons: [steering(), repair()]
85+
```
86+
87+
The rule swaps the entries automatically.
88+
7589
### `rig/no-implicit-any-in-tool-handler`
7690

7791
Arrow function callbacks passed to array iteration methods (`.map`, `.filter`, `.forEach`, `.find`, `.findIndex`, `.every`, `.some`, `.flatMap`) must use parenthesized parameters so that an explicit type annotation can be added.

‎skills/rig/references/prompt-intents.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,12 @@ instructions: p`Analyze these files: ${p.glob("src/**/*.ts")}`
8686
instructions: p`Line counts: ${p.bash("wc -l src/**/*.ts")}`
8787
```
8888

89+
Inline discovery + follow-up read pattern:
90+
91+
```ts
92+
instructions: p`Find files with ${p.glob("src/**/*.ts")}. For each discovered path, call fileAnalyzer with { path } so it can read ${p.readInput("path")}.`
93+
```
94+
8995
## Inputs versus context
9096

9197
Only introduce an input field for caller-supplied data. Known workspace files and commands belong directly in the instructions:
@@ -161,6 +167,35 @@ const report = agent({
161167
export default report;
162168
```
163169

170+
```ts
171+
// p.write with async defineTool — collect structured data, then write known content
172+
import { agent, defineTool, p, s } from "rig";
173+
174+
const collectKeys = defineTool("collectKeys", {
175+
description: "Extract env variable names from dotenv content.",
176+
parameters: s.object({ content: s.string }),
177+
handler: async ({ content }) => {
178+
return {
179+
keys: content
180+
.split("\n")
181+
.map((line: string) => line.trim())
182+
.filter((line: string) => line && !line.startsWith("#"))
183+
.map((line: string) => line.split("=")[0]),
184+
};
185+
},
186+
});
187+
188+
// Agent role: collect env keys and write a starter template.
189+
const dotenvTemplate = agent({
190+
model: "mini",
191+
instructions: p`Read ${p.readOptional(".env.example")}, call collectKeys, then write ${p.write(".env.template", "# Generated template\n")}.`,
192+
tools: [collectKeys],
193+
output: s.object({ keys: s.array(s.string) }),
194+
});
195+
196+
export default dotenvTemplate;
197+
```
198+
164199
Do not rely on `p.writeOutput` to create an output field.
165200

166201
`p.writeInput` is like `p.writeOutput` but accepts a **dynamic destination path** from a caller-supplied input field. Use it when the path to write to is not known at definition time:

‎src/eslint-rules.test.js‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import { fixSource, lintSource } from "../skills/rig/eslint/lint.js";
44
import agentsMustBeObjectRule from "../skills/rig/eslint/rules/agents-must-be-object.js";
55
import rule from "../skills/rig/eslint/rules/no-object-literal-record.js";
66
import repairNoArgsRule from "../skills/rig/eslint/rules/repair-no-args.js";
7+
import addonOrderRule from "../skills/rig/eslint/rules/addon-order.js";
78
import noImplicitAnyRule from "../skills/rig/eslint/rules/no-implicit-any-in-tool-handler.js";
89
import preferPGlobRule from "../skills/rig/eslint/rules/prefer-p-glob-over-bash-find.js";
910
import noInvalidAgentFieldsRule from "../skills/rig/eslint/rules/no-invalid-agent-fields.js";
@@ -313,6 +314,77 @@ describe("repair-no-args", () => {
313314
});
314315
});
315316

317+
describe("addon-order", () => {
318+
it.each([
319+
"addons: [steering(), repair()]",
320+
"addons: [steering({ message: \"Final turn\" }), repair()]",
321+
"addons: repair()",
322+
"addons: [repair()]",
323+
"const text = 'addons: [repair(), steering()]';",
324+
])("accepts %s", (source) => {
325+
const problems = lintSource(source).filter((p) => p.kind === "addon-order");
326+
expect(problems).toEqual([]);
327+
});
328+
329+
it.each([
330+
[
331+
"addons: [repair(), steering()]",
332+
"addons: [steering(), repair()]",
333+
],
334+
[
335+
"addons: [repair(), steering({ message: \"Final turn\" })]",
336+
"addons: [steering({ message: \"Final turn\" }), repair()]",
337+
],
338+
])("fixes %s", (source, expected) => {
339+
const problems = lintSource(source).filter((p) => p.kind === "addon-order");
340+
expect(problems).toHaveLength(1);
341+
expect(fixSource(source, problems)).toBe(expected);
342+
});
343+
344+
it("is idempotent", () => {
345+
const source = "addons: [repair(), steering()]";
346+
const once = fixSource(source);
347+
const twice = fixSource(once);
348+
expect(twice).toBe(once);
349+
expect(lintSource(once).filter((p) => p.kind === "addon-order")).toEqual([]);
350+
});
351+
352+
it("keeps the ESLint rule aligned", () => {
353+
const reports = [];
354+
const visitor = addonOrderRule.create({
355+
sourceCode: {
356+
getText: (node) => node.text,
357+
},
358+
report: (problem) => reports.push(problem),
359+
});
360+
361+
const repairCall = {
362+
type: "CallExpression",
363+
callee: { type: "Identifier", name: "repair" },
364+
arguments: [],
365+
text: "repair()",
366+
};
367+
const steeringCall = {
368+
type: "CallExpression",
369+
callee: { type: "Identifier", name: "steering" },
370+
arguments: [],
371+
text: "steering()",
372+
};
373+
374+
visitor.Property({
375+
type: "Property",
376+
key: { type: "Identifier", name: "addons" },
377+
value: { type: "ArrayExpression", elements: [repairCall, steeringCall] },
378+
});
379+
380+
expect(reports).toHaveLength(1);
381+
expect(reports[0].messageId).toBe("order");
382+
expect(reports[0].fix({
383+
replaceText: (_node, text) => text,
384+
})).toBe("[steering(), repair()]");
385+
});
386+
});
387+
316388
describe("no-implicit-any-in-tool-handler", () => {
317389
it.each([
318390
// Already parenthesized — no flag

0 commit comments

Comments
 (0)