microsoft · robgruen · Apr 14, 2026 · Apr 14, 2026 · Apr 14, 2026
diff --git a/ts/packages/agents/onboarding/AGENTS.md b/ts/packages/agents/onboarding/AGENTS.md
@@ -0,0 +1,121 @@
+# AGENTS.md — Onboarding Agent
+
+This document is for AI agents (Claude Code, GitHub Copilot, etc.) working with the onboarding agent codebase.
+
+## What this agent does
+
+The onboarding agent automates integrating a new application or API into TypeAgent. It is itself a TypeAgent agent, so its actions are available to AI orchestrators via TypeAgent's MCP interface using `list_commands`.
+
+## Agent structure
+
+```
+src/
+  onboardingManifest.json       ← main manifest, declares 7 sub-action manifests
+  onboardingSchema.ts           ← top-level coordination actions
+  onboardingSchema.agr          ← grammar for top-level actions
+  onboardingActionHandler.ts    ← instantiate(); routes all actions to phase handlers
+  lib/
+    workspace.ts                ← read/write per-integration state on disk
+    llm.ts                      ← aiclient ChatModel factories per phase
+  discovery/                    ← Phase 1: API surface enumeration
+  phraseGen/                    ← Phase 2: natural language phrase generation
+  schemaGen/                    ← Phase 3: TypeScript action schema generation
+  grammarGen/                   ← Phase 4: .agr grammar generation
+  scaffolder/                   ← Phase 5: agent package scaffolding
+  testing/                      ← Phase 6: phrase→action test loop
+  packaging/                    ← Phase 7: packaging and distribution
+```
+
+## How actions are routed
+
+`onboardingActionHandler.ts` exports `instantiate()` which returns a single `AppAgent`. The `executeAction` method receives all actions (from main schema and all sub-schemas) and dispatches by `action.actionName` to the appropriate phase handler module.
+
+## Workspace state
+
+All artifacts are persisted at `~/.typeagent/onboarding/<integration-name>/`. The `workspace.ts` lib provides:
+
+- `createWorkspace(config)` — initialize a new integration workspace
+- `loadState(name)` — load current phase state
+- `saveState(state)` — persist state
+- `updatePhase(name, phase, update)` — update phase status; automatically advances `currentPhase` on approval
+- `readArtifact(name, phase, filename)` — read a phase artifact
+- `writeArtifact(name, phase, filename, content)` — write a phase artifact
+- `listIntegrations()` — list all integration workspaces
+
+## LLM usage
+
+Each phase that requires LLM calls uses `aiclient`'s `createChatModelDefault(tag)`. Tags are namespaced as `onboarding:<phase>` (e.g. `onboarding:schemagen`). This follows the standard TypeAgent pattern — credentials come from `ts/.env`.
+
+## Phase approval model
+
+Each phase has a status: `pending → in-progress → approved`. An `approve*` action locks artifacts and advances to the next phase. The AI orchestrator is expected to review artifacts before calling approve — this is the human-in-the-loop checkpoint.
+
+## Adding a new phase
+
+1. Create `src/<phaseName>/` with `*Schema.ts`, `*Schema.agr`, `*Handler.ts`
+2. Add the sub-action manifest entry to `onboardingManifest.json`
+3. Add `asc:*` and `agc:*` build scripts to `package.json`
+4. Import and wire up the handler in `onboardingActionHandler.ts`
+5. Add the phase to the `OnboardingPhase` type and `phases` object in `workspace.ts`
+
+## Adding a new tool to an existing phase
+
+1. Add the action type to the phase's `*Schema.ts`
+2. Add grammar patterns to the phase's `*Schema.agr`
+3. Implement the handler case in the phase's `*Handler.ts`
+
+## Key dependencies
+
+- `@typeagent/agent-sdk` — `AppAgent`, `ActionContext`, `TypeAgentAction`, `ActionResult`
+- `@typeagent/agent-sdk/helpers/action` — `createActionResultFromTextDisplay`, `createActionResultFromMarkdownDisplay`
+- `aiclient` — `createChatModelDefault`, `ChatModel`
+- `typechat` — `createJsonTranslator` for structured LLM output
+
+## Scaffolder — choosing a pattern
+
+The scaffolder (Phase 5) generates pattern-appropriate boilerplate. Before calling `scaffoldAgent`, determine which pattern fits the integration being onboarded. The discovery phase artifacts should give you enough information to decide.
+
+**Decision guide**
+
+| Signal from discovery                                                    | Pattern to use             |
+| ------------------------------------------------------------------------ | -------------------------- |
+| Integration streams text (chat, code gen, summarization)                 | `llm-streaming`            |
+| Integration is a desktop/browser/Electron app with a JS runtime          | `websocket-bridge`         |
+| Integration is a long-running, multi-step process needing human sign-off | `state-machine`            |
+| API surface has 5+ distinct domains (e.g., files + calendar + mail)      | `sub-agent-orchestrator`   |
+| Integration needs a custom interactive UI                                | `view-ui`                  |
+| Integration has an authenticated REST or OAuth API                       | `external-api`             |
+| Integration is a CLI tool, mobile device, or OS service                  | `native-platform`          |
+| Integration has only a few toggle/config actions                         | `command-handler`          |
+| None of the above                                                        | `schema-grammar` (default) |
+
+**Scaffold with a pattern**
+
+```
+scaffold the <name> agent using the <pattern> pattern
+```
+
+**List all patterns**
+
+```
+list agent patterns
+```
+
+Full pattern reference (file layouts, manifest flags, example code) is in
+[docs/architecture/agent-patterns.md](../../../../docs/architecture/agent-patterns.md).
+
+**What the scaffolder generates per pattern**
+
+- `schema-grammar` — manifest, handler, schema, grammar, tsconfigs, package.json
+- `external-api` — above + `*Bridge.ts` with an API client class stub; adds `aiclient` dependency
+- `llm-streaming` — above + `injected: true / cached: false / streamingActions` in manifest; adds `aiclient` + `typechat` dependencies
+- `sub-agent-orchestrator` — above + `actions/` directory with per-group schema and grammar stubs; `subActionManifests` in manifest
+- `websocket-bridge` — above + `*Bridge.ts` with a `WebSocketServer` + pending-request map; adds `ws` dependency
+- `state-machine` — above + state type definitions and `loadState` / `saveState` helpers
+- `native-platform` — above + `child_process` / platform-branching boilerplate
+- `view-ui` — above + `openLocalView` / `closeLocalView` lifecycle; `localView: true` in manifest
+- `command-handler` — replaces `executeAction` dispatch with a named `handlers` map
+
+## Testing
+
+Run phrase→action tests with the `runTests` action after completing the testing phase setup. Results are saved to `~/.typeagent/onboarding/<name>/testing/results.json`. The `proposeRepair` action uses an LLM to suggest schema/grammar fixes for failing tests.
diff --git a/ts/packages/agents/onboarding/README.md b/ts/packages/agents/onboarding/README.md
@@ -0,0 +1,161 @@
+# Onboarding Agent
+
+A TypeAgent agent that automates the end-to-end process of integrating a new application or API into TypeAgent. Each phase of the onboarding pipeline is a sub-agent with typed actions, enabling AI orchestrators (Claude Code, GitHub Copilot) to drive the process via TypeAgent's MCP interface.
+
+## Overview
+
+Integrating a new application into TypeAgent involves 7 phases:
+
+| Phase | Sub-agent               | What it does                                                       |
+| ----- | ----------------------- | ------------------------------------------------------------------ |
+| 1     | `onboarding-discovery`  | Crawls docs or parses an OpenAPI spec to enumerate the API surface |
+| 2     | `onboarding-phrasegen`  | Generates natural language sample phrases for each action          |
+| 3     | `onboarding-schemagen`  | Generates TypeScript action schemas from the API surface           |
+| 4     | `onboarding-grammargen` | Generates `.agr` grammar files from schemas and phrases            |
+| 5     | `onboarding-scaffolder` | Stamps out the agent package infrastructure                        |
+| 6     | `onboarding-testing`    | Generates test cases and runs a phrase→action validation loop      |
+| 7     | `onboarding-packaging`  | Packages the agent for distribution and registration               |
+
+Each phase produces **artifacts saved to disk** at `~/.typeagent/onboarding/<integration-name>/`, so work can be resumed across sessions.
+
+## Usage
+
+### Starting a new integration
+
+```
+start onboarding for slack
+```
+
+### Checking status
+
+```
+what's the status of the slack onboarding
+```
+
+### Resuming an in-progress integration
+
+```
+resume onboarding for slack
+```
+
+### Running a specific phase
+
+```
+crawl docs at https://api.slack.com/docs for slack
+generate phrases for slack
+generate schema for slack
+run tests for slack
+```
+
+## Workspace layout
+
+```
+~/.typeagent/onboarding/
+  <integration-name>/
+    state.json              ← phase status, config, timestamps
+    discovery/
+      api-surface.json      ← enumerated actions from docs/spec
+    phraseGen/
+      phrases.json          ← sample phrases per action
+    schemaGen/
+      schema.ts             ← generated TypeScript action schema
+    grammarGen/
+      schema.agr            ← generated grammar file
+    scaffolder/
+      agent/                ← stamped-out agent package files
+    testing/
+      test-cases.json       ← phrase → expected action test pairs
+      results.json          ← latest test run results
+    packaging/
+      dist/                 ← final packaged output
+```
+
+Each phase must be **approved** before the next phase begins. Approval locks the phase's artifacts and advances the current phase pointer in `state.json`.
+
+## For Best Results
+
+The onboarding agent is designed to be driven by an AI orchestrator (Claude Code, GitHub Copilot) that can call TypeAgent actions iteratively, inspect artifacts, and guide each phase to completion. For the best experience, set up TypeAgent as an MCP server so your AI client can communicate with it directly.
+
+### Set up TypeAgent as an MCP server
+
+TypeAgent exposes a **Command Executor MCP server** that bridges any MCP-compatible client (Claude Code, GitHub Copilot) to the TypeAgent dispatcher. Full setup instructions are in [packages/commandExecutor/README.md](../../commandExecutor/README.md). The short version:
+
+1. **Build** the workspace (from `ts/`):
+
+   ```bash
+   pnpm run build
+   ```
+
+2. **Add the MCP server** to `.mcp.json` at the repo root (create it if it doesn't exist):
+
+   ```json
+   {
+     "mcpServers": {
+       "command-executor": {
+         "command": "node",
+         "args": ["packages/commandExecutor/dist/server.js"]
+       }
+     }
+   }
+   ```
+
+3. **Start the TypeAgent dispatcher** (in a separate terminal):
+
+   ```bash
+   pnpm run start:agent-server
+   ```
+
+4. **Restart your AI client** (Claude Code or Copilot) to pick up the new MCP configuration.
+
+Once connected, your AI client can drive onboarding phases end-to-end using natural language — e.g. _"start onboarding for Slack"_ — without any manual copy-paste between tools.
+
+## Agent Patterns
+
+The scaffolder supports nine architectural patterns. Use `list agent patterns` at runtime for the full table, or see [docs/architecture/agent-patterns.md](../../../../docs/architecture/agent-patterns.md) for the complete reference including when-to-use guidance, file layouts, and manifest flags.
+
+| Pattern                  | When to use                              | Examples                        |
+| ------------------------ | ---------------------------------------- | ------------------------------- |
+| `schema-grammar`         | Bounded set of typed actions (default)   | `weather`, `photo`, `list`      |
+| `external-api`           | Authenticated REST / cloud API           | `calendar`, `email`, `player`   |
+| `llm-streaming`          | Agent calls an LLM, streams results      | `chat`, `greeting`              |
+| `sub-agent-orchestrator` | API surface too large for one schema     | `desktop`, `code`, `browser`    |
+| `websocket-bridge`       | Automate a host app via a plugin         | `browser`, `code`               |
+| `state-machine`          | Multi-phase workflow with approval gates | `onboarding`, `scriptflow`      |
+| `native-platform`        | OS / device APIs, no cloud               | `androidMobile`, `playerLocal`  |
+| `view-ui`                | Rich interactive web-view UI             | `turtle`, `montage`, `markdown` |
+| `command-handler`        | Simple settings-style direct dispatch    | `settings`, `test`              |
+
+## Building
+
+```bash
+pnpm install
+pnpm run build
+```
+
+## TODO
+
+### Additional discovery crawlers
+
+The discovery phase currently supports web docs and OpenAPI specs. Planned crawlers:
+
+- **CLI `--help` scraping** — invoke a command-line tool with `--help` / `--help <subcommand>` and parse the output to enumerate commands, flags, and arguments
+- **`dumpbin` / PE inspection** — extract exported function names and signatures from Windows DLLs for native library integration
+- **.NET reflection** — load a managed assembly and enumerate public types, methods, and parameters via `System.Reflection`
+- **Man pages** — parse `man` output for POSIX CLI tools
+- **Python `inspect` / `pydoc`** — introspect Python modules and their docstrings
+- **GraphQL introspection** — query a GraphQL endpoint's introspection schema to enumerate types and operations
+- **gRPC / Protobuf** — parse `.proto` files or use server reflection to enumerate services and RPC methods
+
+Each new crawler should implement the same `DiscoveryResult` contract so downstream phases (phrase gen, schema gen) remain crawler-agnostic.
+
+## Architecture
+
+See [AGENTS.md](./AGENTS.md) for details on the agent structure, how to extend it, and how each phase's LLM prompting works.
+
+## Trademarks
+
+This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
+trademarks or logos is subject to and must follow
+[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
+Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
+Any use of third-party trademarks or logos are subject to those third-party's policies.