[rig-sampler] docs(rig): add JSDoc to all AgentSpec fields

[github-actions]

Sample run

Ran src/samples/15-api-diff-summary.ts through the stub runner (RIG_SAMPLE=15 npm run sample).

Result: Succeeded in 1 turn — no repair loops. The stub emitted the full rendered prompt, which showed the agent spec clearly:

{
  "model": "mini",
  "output": { "category": "s.enum(...)", "entry": "s.string" },
  "instructions": "Convert the change description to Keep a Changelog style."
}

What the run revealed

While the sample itself ran cleanly, reading the rendered prompt alongside the AgentSpec type definition highlighted a usability gap: the AgentSpec type has no JSDoc on any of its fields. A developer writing a new agent must infer from context what model, maxTurns, addons, agents, systemMessage, and tools each do — and what the defaults are.

For example, model: "mini" appears in the sample but the type signature gives no hint about what model identifiers are accepted or what the default fallback is ("gpt-4.1"). Similarly, maxTurns has no documented default (4) and addons has no indication of built-in options like repair or steering.

Change

Added JSDoc comments to all ten AgentSpec fields documenting:

• Purpose of each field
• Default values where applicable (model → "gpt-4.1", maxTurns → 4, input/output → s.string)
• Example identifiers for model

No behavior change — documentation only. All 141 tests pass.

Generated by Daily Rig Sampler · 61.8 AIC · ⌖ 7.94 AIC · ⊞ 5.2K · ◷

[pelikhan]

@copilot do not use gpt-4.1 as example it's deprecated.

[Copilot]

@copilot do not use gpt-4.1 as example it's deprecated.

Replaced "gpt-4.1" in the example with "o3" in 1d51c68.

[pelikhan]

@copilot do not use o models, use gpt-5* level models

[Copilot]

@copilot do not use o models, use gpt-5* level models

Replaced "o3" with "gpt-5" in the example in the latest commit.

[github-actions]

🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅

[github-actions]

Skills-Based Review 🧠

Applied /grill-with-docs — no blocking issues. The JSDoc additions are accurate and complete.

📋 Key Themes & Highlights

Positive Highlights

• ✅ All ten AgentSpec fields documented
• ✅ Default values ("gpt-4.1", 4, s.string, "agent") verified against the implementation
• ✅ model comment gives concrete example identifiers ("mini", "gpt-5", "claude-sonnet")
• ✅ output comment notes the harness validates and retries — useful context for new users
• ✅ Documentation-only change; no behavioral risk

🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · sonnet46 20.6 AIC · ⌖ 4.98 AIC · ⊞ 6.3K
_{Comment /matt to run again}