KatalKavya96 commented on issue #62500:
URL: https://github.com/apache/airflow/issues/62500#issuecomment-4102960440
Hello @jason810496, @potiuk,
I’ve been following the discussion closely and built a small PoC to explore
the “executable document” direction with a focus on a **narrow, workflow-level
slice** rather than broad coverage.
PR: #64029
---
## Scope of PoC
The PoC models two core contributor workflows:
- **run_targeted_tests**
- local-first (`uv run --project ... pytest`)
- Breeze fallback (`breeze run pytest`) when system dependencies are
missing
- **setup_breeze_environment**
- host-only workflow
- returns guidance when invoked inside Breeze instead of suggesting
incorrect commands
---
## Pipeline
```text
structured workflow block (markdown)
↓
extractor
↓
skills.json
↓
decision engine
↓
agent-facing response
```
---
## Key Design Point
While building this, one design question stood out:
> Should agent skills return only commands, or **workflow-aware responses**?
Some workflows are not “execute immediately” tasks, but context-sensitive
transitions.
So instead of a command-only API, the PoC uses a response contract:
- `mode: "command"` → executable command
- `mode: "guidance"` → structured message when execution is not appropriate
### Example
- `run_targeted_tests` → returns a command
- `setup_breeze_environment` inside Breeze → returns guidance
(“You are already inside Breeze…”)
This avoids incorrect actions like nesting Breeze shells.
---
## What this PoC demonstrates
- executable-doc style workflow definition
- extraction into machine-readable skill data
- context-aware command selection (host vs Breeze)
- local-first + fallback workflow encoding
- command vs guidance response handling
- unit-tested behaviour (extraction + decision + context)
---
## Question for feedback
Would a **command-or-guidance response model** be a useful abstraction for
agent consumers?
Compared to a pure `get_command()` API, this felt closer to real contributor
workflows where:
- sometimes execution is correct
- sometimes the correct action is to **adjust context first**
---
I intentionally kept the scope small to validate this behaviour before
expanding to more workflows.
Happy to iterate based on feedback.
Thanks!
--
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]
