proposal: source

[pelikhan]

source

Tracking the provenance of an installed workflow to allow seamless updates.

frontmatter

The frontmatter field source contains information about where the current workflow was installed from. It allows to perform updates and detects changes.

---
source: githubnext/agentics <ref> samples/workflows/researcher.md
---

The source is a single string formatted as follows (similar to go.mod in golang)

<repository>@<ref>/<path>

gh aw add

The add command should populate the source field when executing.

gh aw update

The update command updates all or some agentic workflows. It only applies
to workflows with the source information.

# updates all workflows
gh aw update
# updates a single workflows
gh aw update <workflowid>
# gives a preview of the update
gh aw update --dry-run
# create pull request with changes
gh aw update --pr

When updating a script, the command follows this algorithm:

resolve the updated sha (either latest, or highest release)
download latest version source text
parse current front matter and update source reference in it
perform a 3-way merge of the markdown body using git. 
let user finish merge as needed.

If the merge is successful a "compile" should be done and the changes/additions staged (like "gh aw add"). That is it should match "gh aw add".

gh aw status

The status command should check if workflows with source have been modified or if updates are available.

includes

Include local paths are converted into global routes (same syntax as source) and resolved at compile time (local cache in .aw/includes/...)

Previius tracking strategy

The previous tracking strategy is deprecated and removed with no backward compatibility.

[dsyme]

"gh aw update: When updating a script, the command follows this algorithm"

If the merge is successful a "compile" should be done and the changes/additions staged (like "gh aw add"). That is it should match "gh aw add" - if we decide not to do automatic staging we should remove it for "gh aw add" too

This means a "--pr" flag should also be supported on "gh aw update"

[danielmeppiel]

What would this be updating? the natural language based agent prompt, the frontmatter (GitHub Actions config) or both?

E.g. does researcher.md just contain text as a prompt in markdown? Or does it contain any frontmatter?

I ask these questions because I can see how untangling both from a packaging point of view can potentially make it easier for users to plug any agent written in markdown into gh aw.

[pelikhan]

The current plan is that it would update the entire file, frontmatter and markdown as a merge to retain modifications.

This would replace how we track the origin of script installed today.

[dsyme]

Done!