Abhishekmishra2808 commented on issue #62500: URL: https://github.com/apache/airflow/issues/62500#issuecomment-4028494629
@jason810496 One approach that I am thinking of is introducing a small structured workflow specification that lives alongside the contributing documentation and captures only the actionable parts of the workflow. For example, a YAML file could describe the execution steps for something like running tests, including the preferred local execution path and the Breeze fallback when dependencies are missing. This idea came from reading kubernetes docs on how they structure some of their task documentation while still relying on machine-readable definitions for automation, and also resembles the way GitHub Actions workflows describe steps declaratively in YAML. For instance, a workflow definition could describe that tests should first attempt local execution using something like uv run --project distribution_folder pytest, and only fall back to Breeze commands such as breeze exec pytest when the local environment does not satisfy the dependencies. In practice the YAML would only capture the command, conditions, and step ordering, while the contributing guide would remain the place where the workflow is explained to humans. To keep everything synchronized, the contributing docs could include a small reference to the workflow identifier (for example a comment marker or short tag), and a generator script could scan those references and validate that the corresponding workflow definitions exist. The same script could then generate the agent skill definitions from the workflow specifications. This is similar in spirit to “executable documentation” approaches used in projects like Bazel’s documentation tooling or Rust’s doc tests, where the documentation remains the human-facing interface but automation ensures the underlying definitions stay consistent. In that model the flow would effectively be: the contributing documentation describes the workflow for humans, the workflow specification provides a structured representation of the same process, and a generator produces the agent skill definitions used by tools. CI (potentially via a prek hook or similar validation step) could then verify that the generated skill definitions match the committed ones and that all workflows referenced in the documentation have a corresponding specification. This keeps the documentation readable while giving agents a deterministic structure to follow, and it also avoids tightly coupling the skill layer to Breeze itself since the workflow spec can reference both local commands and Breeze commands depending on the execution context. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
