[Schema Consistency] 🔍 Schema Consistency Check - 2026-07-13

[github-actions[bot]]

Summary

• Inconsistencies Found: 4
• Categories Analyzed: Schema, Parser/Compiler, Documentation, Workflows
• Strategy Used: Cross-doc schema drift using non-frontmatter references
• New Strategy: No

Critical Issues

1. antigravity is implemented and used, but omitted from public engine docs and schema text

   • Runtime/workflow evidence: .github/workflows/smoke-antigravity.md uses engine.id: antigravity; generated compiler artifacts also include .antigravity folders and model routing entries.
   • Documentation drift: docs/src/content/docs/reference/engines.md lists Copilot, Claude, Codex, Gemini, Crush, OpenCode, and Pi, but not Antigravity.
   • Schema drift: pkg/parser/schemas/main_workflow_schema.json does not contain the string antigravity, so schema descriptions/examples for engine IDs are stale relative to runtime behavior.
   • Impact: users can successfully use a built-in engine that the schema/docs do not advertise, and schema-guided editors will under-document a supported value.

2. Top-level frontmatter docs omit engine.driver and engine.extensions despite schema/runtime support

   • Missing from docs/src/content/docs/reference/frontmatter.md: no occurrences of engine.driver, driver:, engine.extensions, or extensions:.
   • Present elsewhere: docs/src/content/docs/reference/engines.md documents both, and pkg/parser/schemas/main_workflow_schema.json contains "driver" and "extensions" engine properties.
   • Parser/runtime evidence: pkg/workflow/engine_validation.go contains validateEngineDriver, confirming compiler-side handling.
   • Impact: the concise frontmatter reference is incomplete for users who rely on it as the main entry point.

3. Built-in engine catalog comment in code is stale

   • pkg/workflow/engine_definition.go says: NewEngineCatalog registers the built-in engines: claude, codex, copilot, gemini, opencode, crush.
   • But runtime/workflows also support pi and antigravity.
   • Impact: maintainers reading code comments get an incorrect engine catalog, which increases the chance of future drift and incorrect follow-on docs/tests.

Documentation Gaps

4. frontmatter-full.md still surfaces deprecated safe-outputs.dispatch_repository alias
   • Canonical parser behavior: pkg/workflow/dispatch_repository.go treats dispatch-repository as canonical and logs a warning when dispatch_repository is used: safe-outputs.dispatch_repository is deprecated; rename to dispatch-repository or run \gh aw fix``.
   • Schema contains both keys, but docs/src/content/docs/reference/frontmatter-full.md still includes a dedicated deprecated alias section (dispatch_repository:), making the old form highly visible.
   • Impact: generated docs continue nudging users toward a deprecated spelling, prolonging migration and naming inconsistency.

Schema Improvements Needed

• Add antigravity to engine ID descriptions/examples anywhere the schema enumerates or describes built-in engine values.
• Consider strengthening engine ID schema constraints if runtime supports a known built-in catalog plus explicit extension cases.
• Consider reducing visibility of deprecated aliases in generated reference output, or clearly mark them as migration-only.

Parser / Compiler Notes

• No parser bug was found in these spots; the main issue is cross-surface drift.
• Parser/compiler behavior appears ahead of docs/schema text for engines and ahead of reference examples for dispatch-repository.

Workflow Violations

• No invalid workflow usage was found in the sampled workflow. Instead, .github/workflows/smoke-antigravity.md demonstrates a valid real-world configuration that current docs/schema text fail to describe fully.

Recommendations

1. Update docs/src/content/docs/reference/engines.md to list antigravity alongside the other built-in engines.
2. Update engine-related schema descriptions/examples in pkg/parser/schemas/main_workflow_schema.json to mention antigravity.
3. Add a short engine.driver / engine.extensions pointer section to docs/src/content/docs/reference/frontmatter.md, linking to the detailed engines reference.
4. Fix the stale built-in engine comment in pkg/workflow/engine_definition.go to include pi and antigravity.
5. De-emphasize or remove the deprecated dispatch_repository example block from frontmatter-full.md, leaving the canonical dispatch-repository form as the primary surface.

Strategy Performance

• Strategy Used: Cross-doc schema drift using non-frontmatter references
• Findings: 4
• Effectiveness: High
• Should Reuse: Yes

Next Steps

• Fix engine catalog docs
• Refresh schema descriptions for built-in engine IDs
• Add missing concise frontmatter docs for advanced engine keys
• Remove or further demote deprecated alias examples

References:

• §29228992706

Generated by ✅ Schema Consistency Checker · 8.96 AIC · ⌖ 6.55 AIC · ⊞ 7.3K · ◷

• expires on Jul 13, 2026, 10:31 PM UTC-08:00