Add resolved workflow manifest to lock file comments for workflows with imports

[Copilot]

Summary

When compiling agentic workflows that use imports or includes, the compiled .lock.yml files now include a "Resolved workflow manifest" comment section in the header that documents all dependencies. This provides clear visibility into what files were merged into the final workflow configuration.

Problem

Previously, when a workflow used the imports: frontmatter field or @include directives to compose functionality from multiple files, the compiled .lock.yml file provided no indication of these dependencies. This made it difficult to understand:

• What files were merged into the final workflow
• Where certain tools or configurations originated from
• The full dependency chain for complex workflows

Solution

The compiler now tracks all imported and included files during the compilation process and writes them as comments in the lock file header:

Before:

# This file was automatically generated by gh-aw. DO NOT EDIT.
# To update this file, edit the corresponding .md file and run:
#   gh aw compile
# For more information: https://github.com/...

name: "Dev"
on:
  push:
...

After:

# This file was automatically generated by gh-aw. DO NOT EDIT.
# To update this file, edit the corresponding .md file and run:
#   gh aw compile
# For more information: https://github.com/...
#
# Resolved workflow manifest:
#   Imports:
#     - shared/tools.md
#   Includes:
#     - shared/use-emojis.md
#     - shared/keep-it-short.md

name: "Dev"
on:
  push:
...

Implementation Details

Parser Changes (pkg/parser/frontmatter.go)

• Added ProcessImportsFromFrontmatterWithManifest() function that returns the list of imported files along with merged tools and engines
• Added ExpandIncludesWithManifest() function that returns the list of included files along with expanded content
• Maintained backward compatibility by having original functions call the new manifest-tracking versions

Compiler Changes (pkg/workflow/compiler.go)

• Added ImportedFiles and IncludedFiles fields to WorkflowData struct
• Updated compilation pipeline to collect file manifests during processing
• Modified generateYAML() to output the manifest section when imports or includes are present
• The manifest section is only rendered when there are actual dependencies to document

Test Coverage

Added comprehensive test suite in pkg/workflow/manifest_test.go covering:

• Workflows with both imports and includes
• Workflows with only imports
• Workflows with only includes
• Workflows without any dependencies (ensures no manifest section appears)

All existing tests continue to pass, confirming backward compatibility.

Benefits

• Better Documentation: Lock files now self-document their composition
• Easier Debugging: Quickly identify where tools and configurations come from
• Dependency Tracking: Clear visibility into the full dependency chain
• No Breaking Changes: Feature is additive and doesn't affect existing functionality

Original prompt

When compiling an agentic workflow with imports, write the full manifest of resolved workflow spec in the top-file comments.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[pelikhan]

@copilot merge main. format, lint, recompile