[Code Quality] Add schema examples for security-critical and common fields (11% → 25% coverage)

[github-actions]

Description

The Schema Completeness & Metadata Quality Audit (Discussion #13177) identified that only 11% of schema fields (74 out of 677 fields) have explicit examples, critically impacting IDE autocomplete quality and schema discoverability.

Problem Statement

Security-critical and commonly-used fields lack examples, making it harder for developers to understand proper usage patterns:

Critical Fields Missing Examples:

• github-token (authentication)
• roles (security/access control)
• bots (automation triggers)
• timeout-minutes (workflow timing)
• cache, cache-memory (performance)

Suggested Changes

Add explicit "example" fields to the following priority areas in pkg/parser/schemas/main_workflow_schema.json:

Priority 1: Security-Critical Fields

"github-token": {
  "example": "${{ secrets.GITHUB_TOKEN }}"
}
"roles": {
  "example": ["admin", "maintainer", "write"]
}
"bots": {
  "example": ["dependabot", "renovate"]
}

Priority 2: Commonly-Used Configuration

"timeout-minutes": {
  "example": 20
}
"cache": {
  "example": "node_modules"
}
"cache-memory": {
  "example": "512M"
}
"environment": {
  "example": "production"
}

Success Criteria

• Example coverage increases from 11% to at least 25% (170+ fields with examples)
• All security-critical fields have examples
• All commonly-used configuration fields have examples
• Examples validate against schema patterns
• IDE autocomplete shows examples in frontmatter editing

Files Affected

• pkg/parser/schemas/main_workflow_schema.json (primary schema file)
• Optionally: pkg/parser/schemas/mcp_config_schema.json (if MCP-specific examples needed)

Impact

Developer Experience: Adding examples dramatically improves:

• IDE autocomplete quality
• Schema discoverability for new users
• Understanding of proper usage patterns
• Reduced configuration errors

Effort: Low - Adding examples is a documentation task that doesn't require code changes or testing

Source

Extracted from Schema Completeness & Metadata Quality Audit - February 2026 (Discussion #13177)

Key Finding:

Only 74 of 677 fields (11%) have explicit examples. Critical Fields Missing Examples include github-token, roles, bots, timeout-minutes, cache, cache-memory.

Priority

High - Directly impacts developer experience and schema usability. Low effort with high value return.

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 16, 2026, 1:35 AM UTC