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

[github-actions[bot]]

Summary

• Inconsistencies Found: 3
• Categories Analyzed: Schema, Parser, Documentation, Workflows
• Strategy Used: Engine sub-object key coverage (engineObj vs engine_config branches)
• New Strategy: No

Critical Issues

1. antigravity is implemented but missing from primary engine docs

   • Runtime/catalog support exists in pkg/constants/engine_constants.go, embedded engine definitions under pkg/workflow/data/engines/antigravity.md, and workflow/runtime code such as pkg/workflow/antigravity_logs.go.
   • However docs/src/content/docs/reference/engines.md omits Antigravity from the “Available Coding Agents” table and related version/examples, so the main user-facing engine reference understates supported engines.
   • Impact: valid workflows using engine: antigravity look undocumented even though the compiler/runtime support them.

2. engine.driver schema/docs are narrower than parser/runtime behavior

   • Parser/runtime support:
     • pkg/workflow/engine.go parses engine.driver.
     • pkg/workflow/copilot_engine_execution.go supports Copilot SDK drivers in .js/.cjs/.mjs, .py, .ts/.mts, .rb, and bare command names.
     • docs/src/content/docs/reference/engines.md documents Copilot SDK usage of engine.driver.
   • But the schema description for engine.driver in pkg/parser/schemas/main_workflow_schema.json says it is for engines “e.g. pi” and only mentions .js/.cjs/.mjs plus a setup-action-local bare filename.
   • Impact: schema-generated docs (frontmatter-full.md) misdescribe a broader supported feature and may mislead validation/tooling consumers.

3. Built-in engine catalog comments in Go source are stale

   • pkg/workflow/engine_definition.go comments say built-ins are claude, codex, copilot, gemini, opencode, crush.
   • Real runtime/catalog sources include pi and antigravity as well (pkg/constants/engine_constants.go, pkg/workflow/data/engines/*.md).
   • Impact: maintainers reading source comments get an outdated model of the engine catalog.

Documentation Gaps

• docs/src/content/docs/reference/engines.md needs Antigravity added to the engine availability and version guidance sections.
• docs/src/content/docs/reference/frontmatter-full.md inherits the too-narrow engine.driver schema description, so generated reference output does not match runtime behavior.
• The generated frontmatter reference documents engine.extensions, but the higher-level engine docs only explain it as Pi-specific later in the page; that’s acceptable, though the driver/extension sections would benefit from clearer engine-scoping language.

Schema Improvements Needed

1. Update $defs.engine_config.oneOf[1].properties.driver.description to reflect actual supported engines and file types.
2. Consider constraining or documenting engine IDs more explicitly where built-in IDs are described, since runtime support now includes antigravity and pi but several schema/examples still highlight only older engines.
3. Revisit generated examples under properties.engine.examples so they better reflect the current built-in engine set.

Parser Updates Required

• No parser bug was required to explain these findings; the parser/runtime was more capable than the schema/docs in this run.
• Low-priority cleanup: align pkg/workflow/engine_definition.go comments with the actual built-in registration set.

Workflow Violations

• No invalid workflow frontmatter was confirmed in sampled repo workflows for the targeted fields.
• Instead, the main workflow-facing inconsistency is that valid runtime-supported engine capabilities are under-documented.

Recommendations

1. Add antigravity to docs/src/content/docs/reference/engines.md engine tables and examples.
2. Expand the engine.driver schema description to cover Copilot SDK driver mode and the full supported extension set (.js, .cjs, .mjs, .py, .ts, .mts, .rb, bare commands where applicable).
3. Regenerate docs/src/content/docs/reference/frontmatter-full.md after schema updates so generated reference text matches runtime behavior.
4. Fix stale built-in-engine comments in pkg/workflow/engine_definition.go.

Strategy Performance

• Strategy Used: Engine sub-object key coverage (engineObj vs engine_config branches)
• Findings: 3
• Effectiveness: High
• Should Reuse: Yes

Next Steps

• Fix schema definitions for engine.driver descriptions/examples
• Update engine documentation to include Antigravity
• Refresh generated frontmatter reference docs
• Correct stale built-in-engine source comments

Generated by ✅ Schema Consistency Checker · 32.4 AIC · ⌖ 10 AIC · ⊞ 5.9K · ◷

• expires on Jul 5, 2026, 10:35 PM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-07-06T06:35:50.018Z.

Closed by Workflow