git:20261006.9e83900 to git:20261010.2be15ee

5 added, 1 removed. Audit A to A.

# AGENTS.md

## Project Overview

Rig is a minimal TypeScript agent harness. The core runtime (`skills/rig/rig.ts`) provides declarative agent construction with typed input/output shapes, prompt intents, and a Copilot SDK runtime.

## Architecture

```

skills/rig/rig.ts — Core runtime (agent, p, copilotEngine, schemas)

- skills/rig/samples/ — 51 sample agents demonstrating patterns

+ skills/rig/samples/ — Markdown sample programs; see skills/rig/samples.md for pattern buckets and task families

+ src/samples/ — TypeScript examples and provider integration fixtures

skills/rig/ — Focused documentation loaded on demand from SKILL.md

src/engines/copilot.test.ts — Copilot engine unit tests (vitest)

src/rig.test.ts — Unit tests (vitest)

scripts/run-sample.test.ts — Sample runner with a stub Copilot SDK client (dry-run)

skills/rig/SKILL.md — Compact skill entry point and reference router

```

All imports use the `"rig"` path alias (resolved via tsconfig paths + vitest alias). `copilotEngine` is exported directly from `rig` for client construction.

## Commands

| Task | Command |

|------|---------|

| Typecheck | `npm run typecheck` |

| Unit tests | `npm test` |

| Run samples (stub) | `npm run sample` |

+ | Refresh sample catalog | `npm run sample:catalog` |

+ | Check catalog and duplicate programs | `npm run sample:check` |

| Run single sample (stub) | `RIG_SAMPLE=02 npm run sample` |

| Run a sample for real | `echo "<input>" \| node skills/rig/rig.ts <program-file>` (`npm run sample:run`) |

## Code Style

- Keep the core (`skills/rig/rig.ts`) self-contained; `@github/copilot-sdk` is imported directly in `skills/rig/rig.ts`

- Minimal comments; code should be self-explanatory

- Use `node:` prefix for Node.js built-in imports

- Types are colocated with the module that defines them, not in separate `.d.ts` files

- Trailing underscore on object keys (`key_`) means optional field

- Use `small` as the model identifier in examples, tests, and defaults

- Do not add legacy compatibility bridges; update callers, samples, and docs to the current API

## Skill Documentation

- Treat `skills/rig/SKILL.md` as prompt context: keep only high-frequency construction rules, decisions, and a minimal canonical example.

- Target roughly 200 lines or fewer. Use line/word/byte counts as regression signals, not as a reason to compress prose until it is unclear.

- Put detailed API tables, edge cases, provider behavior, and scenario-specific patterns in focused files under `skills/rig/`.

- Route every reference from `SKILL.md` with a short “read when” description so an agent can load only the relevant secondary context.

- Prefer one representative example, decision tables, and checklists over repeated prose. Remove duplication before adding guidance.

- Keep each fact canonical. A compact rule may be summarized in `SKILL.md`, but its examples and edge cases should live in one reference file.

- Add new material to `SKILL.md` only when it changes how most Rig programs should be generated; otherwise update or add a focused reference.

- When the API changes, update the affected reference and then audit `SKILL.md`, `README.md`, and samples for stale summaries or links.

- Before finishing documentation changes, verify relative links and compare `wc -l -w -c skills/rig/*.md` with the previous version.

## Testing

- Framework: vitest

- Tests live in `src/rig.test.ts` (agent definition, invocation, validation, and prompt intent coverage)

- Stub the Copilot SDK client with `vi.mock("@github/copilot-sdk", ...)`

- All unit tests must pass before committing

- Samples run via a stub Copilot SDK client that synthesizes shape-conforming output from the prompt's `<output_schema>` block

## Key Concepts

- **Schema helpers (`s.*`)**: `s.string`, `s.number`, `s.boolean`, `s.unknown`, `s.array`, `s.object`, `s.record`, `s.enum`, `s.optional`. Schemas are always built with `s.*`; there is no shape-descriptor promotion.

- **Prompt intents (`p.*`)**: `p.bash(cmd)`, `p.read(path)`, `p.write(path, content)` — declarative placeholders resolved into prompt instructions, not executed in-process

- **Prompts**: `p\`...\`` template tag composes instructions with inline `p.*` helpers

- **Runtime transport**: Copilot SDK sessions are created by the harness; use launcher `--server` to switch to stdio transport.

- **Repair**: built-in addon re-prompts on parse/validation failure up to `maxTurns`, and other addons can still steer retry prompts.

## Sample guide

+ - `skills/rig/samples.md` — generated inventory with pattern buckets, topic clusters, and task families. Retired sample replacements are tracked separately in `skills/rig/sample-retirements.json`. Run `npm run sample:catalog` after adding/removing samples; `npm run sample:check` rejects stale inventory and exact duplicates within a format. Review the nearest family before adding a new lesson.

- `20-issue-reproducer.ts` — chained diagnosis, fix planning, and review

- `36-subagent-delegation.ts` — focused-agent delegation

- `47-prompt-intents.ts` — prompt intent primitives

- `50-end-to-end-release-agent.ts` — end-to-end release workflow orchestration