Add inline examples to major workflow configuration fields

[Copilot]

Schema audit showed only 49% of root properties have examples. The 6 most critical fields (on, engine, tools, steps, safe-outputs, mcp-servers) lacked examples, impacting IDE autocomplete and developer onboarding.

Changes

Added examples arrays to priority fields in pkg/parser/schemas/main_workflow_schema.json:

• on (5 examples): Issues, pull requests, workflow_dispatch, scheduled triggers, slash commands
• engine (5 examples): Simple strings ("copilot", "claude", "codex"), version overrides, model configuration with turn limits
• tools (4 examples): Playwright with version, GitHub (remote/local modes), bash
• steps (enhanced to 3 examples): Prompt-only, mixed (actions + prompts), shell scripts
• safe-outputs (3 examples): create-issue, create-pull-request with labels/prefixes, combined outputs
• mcp-servers (2 examples): stdio (filesystem), http (custom server)

Example

IDEs with JSON Schema support now show inline examples for common patterns:

on:
  issues:
    types: ["opened"]

engine:
  id: claude
  model: claude-3-5-sonnet-20241022
  max-turns: 15

tools:
  github:
    mode: remote

All examples validate against schema constraints and represent production usage patterns.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/user
  • Triggering command: /usr/bin/gh gh api user --jq .login k/gh-aw/gh-aw/.github/workflows rev-parse e/git-remote-https l --others ux-amd64/pkg/too. e/git-remote-htt-v om/h�� om/haskell-actions/setup.git rev-parse (http block)
  • Triggering command: /usr/bin/gh gh api user --jq .login l/linux_amd64/li"mcp-server-play/run/containerd/io.containerd.runtime.v2.task/moby/98272d1741041git git ps tags/93cb6efe182git kiefer <8320933+rev-parse l/linux_amd64/as--show-toplevel ps -dot�� -dotnet.git -s -w -X main.version=843fb29 684444/b413/vet.cfg by/98272d1741041node ./cmd/gh-aw (http block)
  • Triggering command: /usr/bin/gh gh api user --jq .login .git l/linux_amd64/cgo /usr/bin/git by/98272d1741041gh -test.v=true e/git-remote-httlist git rev-�� b/workflows e/git-remote-htt--others 0/x64/bin/npm l config /usr/bin/infocmpuser 0/x64/bin/npm (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[plan] Add inline examples to major workflow configuration fields</issue_title>
<issue_description>## Objective

Add examples fields to the most important workflow configuration properties to improve IDE autocomplete and developer onboarding.

Context

This is Issue #3 (Medium) from the schema audit. Only 49% of root properties have examples, and critically, the most important fields (on, engine, tools, steps, safe-outputs, mcp-servers) lack examples.

Approach

Add examples array to each priority field with 1-2 realistic usage examples. Focus on common use cases that developers will encounter first.

Files to Modify

• pkg/parser/schemas/main_workflow_schema.json

Priority Fields (in order)

1. on - Workflow trigger events (highest priority)

   "examples": [
     {"issues": {"types": ["opened"]}},
     {"pull_request": {"types": ["opened", "synchronize"]}}
   ]

2. engine - AI engine selection

   "examples": ["copilot", "claude", "codex"]

3. tools - Tool configuration

   "examples": [
     {"playwright": {"version": "v1.41.0"}},
     {"github": {"mode": "remote"}}
   ]

4. steps - Workflow steps

   "examples": [
     [{"prompt": "Analyze the issue and create a plan"}],
     [{"uses": "actions/checkout@v4"}, {"prompt": "Review the code"}]
   ]

5. safe-outputs - Safe output configuration

   "examples": [
     {"create_issue": {"title": "Bug Report", "body": "Description"}},
     {"create_pull_request": {"title": "Fix", "body": "Changes"}}
   ]

6. mcp-servers - MCP server configuration

   "examples": [
     {"filesystem": {"stdio": {"command": "npx", "args": ["-y", "`@modelcontextprotocol/server-filesystem`"]}}},
     {"custom-server": {"http": {"url": "(redacted)
   ]

Acceptance Criteria

• All 6 priority fields have examples arrays
• Examples demonstrate common/realistic use cases
• Examples are valid according to schema constraints
• Schema validation still passes
• Run make build to verify embedded schemas compile

Estimated Effort

2-3 hours (includes testing examples for validity)

AI generated by Plan Command for discussion #8130

Comments on the Issue (you are @copilot in this section)

• Fixes [plan] Add inline examples to major workflow configuration fields #8135

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.