Prompt content from imports with `steps:` appears after prompt-only imports, breaking declared import order

[yskopets]

🤖 This issue has been filed by Claude Code.

Problem

When a workflow declares imports in a specific order, you would expect the combined agent prompt to present content in that same order. The compiler, however, treats shared files differently depending on whether they contain steps::

• Prompt-only files (no steps:) — prose is inlined at compile time, in place.
• Files with steps: — their prose documentation is emitted as a compiler-generated {{#runtime-import …}} placeholder at the end of the prompt heredoc, after all inlined content.

This means the effective prompt ordering can differ significantly from the declared import order.

Minimal Reproduction

# my-workflow.md
imports:
  - shared/infra.md        # has steps: AND some prose/docs
  - shared/instructions.md # prompt-only, no steps

Compiled lock file prompt body (schematic):

# shared/instructions.md prose (inlined at compile time)
...instructions content...

{{#runtime-import .github/workflows/shared/infra.md}}   ← placed last, despite being declared first
{{#runtime-import .github/workflows/my-workflow.md}}

Even though shared/infra.md was declared first in imports:, its prose ends up after shared/instructions.md's content in the running agent's context.

This is particularly surprising because:

1. The imports: list looks sequential — developers naturally expect the agent to see content in that order.
2. The behaviour is undocumented: the reference docs describe {{#runtime-import}} as something authors write explicitly, not as something the compiler generates automatically for any import that happens to have steps:.
3. When the prose of a "setup" import is meant to orient the agent before task-specific instructions, having it appear after them can change agent behaviour.

Expected Behaviour

Prompt content (whether statically inlined or emitted as a {{#runtime-import}}) should appear in the order the imports are declared. If shared/infra.md is listed before shared/instructions.md, the agent should see shared/infra.md's prose before shared/instructions.md's prose — regardless of whether each is rendered statically or dynamically.

Suggested Fix Direction

Preserve the relative ordering of compiler-generated {{#runtime-import}} placeholders according to import declaration order, interleaved with any statically inlined content at the positions those imports occupy in the list.

Alternatively, document the current behaviour clearly so authors can work around it by reordering their imports: list or using explicit {{#runtime-import}} in the workflow body.

[yskopets]

🤖 This comment has been generated by Claude Code.

Follow-up with a more precise root cause after further investigation.

Corrected Root Cause

My initial report attributed the ordering split to whether a shared file has steps:. After more investigation, that was wrong. The actual criterion appears to be whether the shared file itself declares imports: in its own frontmatter.

In the example from the original report:

• shared/instructions.md — leaf file, no imports: → prose inlined at compile time
• shared/infra.md — declares its own imports: (it pulls in other shared components) → prose emitted as {{#runtime-import}} at the end of the prompt

Adding steps: to leaf files does not change their inlined status. The presence of imports: in a shared file is what causes the compiler to defer it to a {{#runtime-import}} placeholder.

Why This Matters More

This makes the ordering problem harder to work around. A shared file that composes multiple sub-components (via its own imports:) is typically the one you most want to appear early in the prompt — it establishes the environment and capabilities. But because it has imports:, it always ends up last, regardless of where it sits in the consuming workflow's imports: list.

The ask from the original report stands: prompt content should be combined in import-declaration order regardless of whether each file is a leaf or a composite import.

[yskopets]

🤖 This comment has been generated by Claude Code.

Further update after additional experiments — the root cause is now narrowed to the file structure, not the frontmatter fields.

Corrected Root Cause (Again)

Neither steps: nor imports: in a shared file's frontmatter determines whether its content is inlined vs. deferred to a {{#runtime-import}}. After testing both:

• Adding steps: to leaf files → no change, prose still inlined
• Adding imports: to a file that has prose → no change, prose still inlined; only the newly imported sub-file (which had no prose) became a runtime-import

The actual criterion appears to be: whether the shared file has prose content after its closing --- separator.

File structure	Compiled output
Has prose content after ---	Prose inlined at compile time
No prose after --- (file ends at the separator)	File emitted as {{#runtime-import}}

This holds regardless of whether the file has steps: or imports:.

Evidence

There is already a deliberately engineered workaround for this in the codebase: a shared infrastructure file ends with:

steps:
  - name: Workaround placeholder for the prose of <filename>
    run: true

---

The trailing --- with nothing after it is the workaround. It forces the compiler to emit a {{#runtime-import}} for this file rather than inlining it. The step name explicitly calls it a workaround.

A completely empty shared file (just ---\n---, empty frontmatter, no prose) also becomes a {{#runtime-import}}, confirming the rule.

Practical Impact

The only way to control prompt ordering today is to restructure a file's prose out of the shared partial entirely — leaving just a trailing --- — and move the prose somewhere else (e.g. directly into the consuming workflow). This is a disruptive structural change and essentially a compiler workaround.

The requested fix (from the original issue) remains: the compiler should emit all prompt contributions in import-declaration order, regardless of whether each file's prose is inlined or deferred.

[yskopets]

I think none of the Claude Code's theories is accurate.

Here is my own description of the context of the issue.

We have a top-level workflow with direct imports and nested imports:

my-workflow.md
├── shared/side-repository-ops.md
├── shared/per-target-repository-instructions.md
│   ├── shared/go.md
│   └── shared/apm.md
└── shared/other-reusable-instructions.md

Apparently, the resulting order of the combined Markdown depends on whether a given shared file is parameterized or not.

For a while, we had the following set-up with regards to parameterization (notice uses: ...):

my-workflow.md
├── uses: shared/side-repository-ops.md
    with: ...
├── shared/per-target-repository-instructions.md
│   ├── shared/go.md
│   └── uses: shared/apm.md
        with: ...
└── uses: shared/other-reusable-instructions.md
    with: ...

It went unnoticed that the effective order of markdown in my-workflow.lock.yml was in fact:

1. INLINED shared/side-repository-ops.md
2. INLINED shared/other-reusable-instructions.md
3. {{#runtime-import shared/per-target-repository-instructions.md}}
4. {{#runtime-import shared/go.md}}
5. {{#runtime-import my-workflow.md}}

Notice that the middle import (shared/per-target-repository-instructions.md and its own imports) was somehow pushed after the shared/other-reusable-instructions.md. It was already not what was expected.

Now, we've added a parameter to the shared/go.md:

my-workflow.md
├── uses: shared/side-repository-ops.md
    with: ...
├── shared/per-target-repository-instructions.md
│   ├── uses: shared/go.md
        with: ...
│   └── uses: shared/apm.md
        with: ...
└── uses: shared/other-reusable-instructions.md
    with: ...

and the order of markdown in my-workflow.lock.yml changed to:

1. INLINED shared/side-repository-ops.md
2. INLINED shared/other-reusable-instructions.md
3. INLINED shared/go.md
4. {{#runtime-import shared/per-target-repository-instructions.md}}
5. {{#runtime-import my-workflow.md}}

---

Issue

The ordering of Markdown in the compiled *.lock.yml file is non-intuitive and brittle.

It results in a prompt that an Agent doesn't follow as was intended.