Objective
Update the gh-aw documentation to clearly explain import path resolution rules, covering repo-root-relative paths, .github/agents/ imports, cross-repo imports, and the existing relative-to---dir default.
Context
Issue #23900 revealed that users don't know .github/agents/ imports fail, that the .github/-prefix syntax exists (after the fix), or that cross-repo imports are already supported via owner/repo/path@ref workflowspec syntax.
Changes Required
1. Imports Reference Doc
Update or create docs/src/content/docs/reference/imports.md (or the equivalent imports reference page) to document:
- Relative paths (default):
imports: [agents/my-agent.md] → resolved relative to --dir (default .github/workflows/). Backward-compatible, existing behaviour.
- Repo-root-relative paths (new):
imports: [.github/agents/my-agent.md] → paths starting with .github/ or / are resolved from the repository root. Enables the documented .github/agents/ convention.
- Cross-repo imports (existing, underdocumented):
imports: [owner/repo/path/to/agent.md@v1.0.0] → fetched from GitHub at compile time, inlined into the lock file. Supports tags, branches, and SHAs for pinning.
Include a worked example showing all three forms in a single frontmatter block, a note about backward compatibility, and security constraints (paths must remain within .github/).
2. Update Workflow Frontmatter Schema / JSON Schema Comments
In pkg/parser/schemas/ (the frontmatter JSON schema), update the imports field description to mention repo-root-relative support.
3. Update AGENTS.md / DEVGUIDE.md if They Reference Import Paths
Search for existing references to import paths in AGENTS.md and DEVGUIDE.md and update any statements that say imports only work relative to .github/workflows/.
Files to Modify
docs/src/content/docs/reference/imports.md (or equivalent) — primary doc update- Relevant JSON schema file in
pkg/parser/schemas/ — update imports field description
AGENTS.md or DEVGUIDE.md if they contain outdated statements about import paths
Acceptance Criteria
Generated by Plan Command for issue #23900 · ● 1.4M · ◷
Objective
Update the
gh-awdocumentation to clearly explain import path resolution rules, covering repo-root-relative paths,.github/agents/imports, cross-repo imports, and the existing relative-to---dirdefault.Context
Issue #23900 revealed that users don't know
.github/agents/imports fail, that the.github/-prefix syntax exists (after the fix), or that cross-repo imports are already supported viaowner/repo/path@refworkflowspec syntax.Changes Required
1. Imports Reference Doc
Update or create
docs/src/content/docs/reference/imports.md(or the equivalent imports reference page) to document:imports: [agents/my-agent.md]→ resolved relative to--dir(default.github/workflows/). Backward-compatible, existing behaviour.imports: [.github/agents/my-agent.md]→ paths starting with.github/or/are resolved from the repository root. Enables the documented.github/agents/convention.imports: [owner/repo/path/to/agent.md@v1.0.0]→ fetched from GitHub at compile time, inlined into the lock file. Supports tags, branches, and SHAs for pinning.Include a worked example showing all three forms in a single frontmatter block, a note about backward compatibility, and security constraints (paths must remain within
.github/).2. Update Workflow Frontmatter Schema / JSON Schema Comments
In
pkg/parser/schemas/(the frontmatter JSON schema), update theimportsfield description to mention repo-root-relative support.3. Update
AGENTS.md/DEVGUIDE.mdif They Reference Import PathsSearch for existing references to import paths in
AGENTS.mdandDEVGUIDE.mdand update any statements that say imports only work relative to.github/workflows/.Files to Modify
docs/src/content/docs/reference/imports.md(or equivalent) — primary doc updatepkg/parser/schemas/— updateimportsfield descriptionAGENTS.mdorDEVGUIDE.mdif they contain outdated statements about import pathsAcceptance Criteria
owner/repo/path@ref) is documented with a pinning exampleimportsfield is updatedRelated to Fix: Flexible import path resolution and cross-repo agent imports #23900