[Code Quality] Add schema examples for security-critical and commonly-used fields

[github-actions]

Description

The JSON schema files have only 11% example coverage (74 of 677 fields), making it harder for developers to discover correct usage patterns. Security-critical fields and commonly-used configuration options are missing examples.

Current State

• Schema files: pkg/parser/schemas/*.json
• Example coverage: 11% (74/677 fields have examples)
• Critical fields missing examples: github-token, roles, bots, timeout-minutes, cache, environment

Suggested Changes

Add examples to Priority 1 fields (security-critical and commonly-used):

Security-Critical Fields

{
  "github-token": {
    "type": "string",
    "description": "GitHub token for API access",
    "example": "${{ secrets.GITHUB_TOKEN }}"
  },
  "roles": {
    "type": "array",
    "description": "Allowed GitHub roles",
    "example": ["admin", "maintainer", "write"]
  },
  "bots": {
    "type": "array", 
    "description": "Bot trigger patterns",
    "example": ["dependabot", "github-actions[bot]"]
  }
}

Commonly-Used Fields

{
  "cache": {
    "type": "string",
    "description": "GitHub Actions cache key pattern",
    "example": "npm-${{ hashFiles('**/package-lock.json') }}"
  },
  "timeout-minutes": {
    "type": "integer",
    "description": "Workflow timeout in minutes",
    "example": 20
  },
  "environment": {
    "type": "string",
    "description": "GitHub environment name",
    "example": "production"
  }
}

Benefits

• Better IDE integration: Autocomplete suggestions show realistic examples
• Faster onboarding: Developers can see correct usage patterns
• Fewer configuration errors: Examples reduce trial-and-error
• Improved discoverability: Security features are more visible

Files Affected

• pkg/parser/schemas/workflow-frontmatter.json
• pkg/parser/schemas/campaign-frontmatter.json
• Note: Schema files are embedded via //go:embed, so make build required after changes

Success Criteria

• ✅ All security-critical fields have examples (github-token, roles, bots)
• ✅ All commonly-used fields have examples (cache, timeout-minutes, environment)
• ✅ Example coverage increases from 11% to > 20%
• ✅ Examples validated against actual workflow usage
• ✅ Schema validation tests pass

Source

Extracted from Schema Completeness & Metadata Quality Audit - February 2026

Priority 1: Developer Experience (High Impact, Low Effort)

Example coverage remains the most critical gap (11%)
Add examples to security-critical and commonly-used fields
Impact: Better IDE integration, faster onboarding, fewer errors

Priority

Medium - High impact on developer experience, relatively low effort (documentation changes only). Marked as Priority 1 in schema audit.

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 16, 2026, 5:32 AM UTC