From 981f6780265b8702a62d327a825b6614744bd594 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 18 Jun 2026 15:27:01 +0000
Subject: [PATCH 01/10] feat(init): add --agency flag to generate Claude Code
 plugin

Co-authored-by: jamesadevine <4742697+jamesadevine@users.noreply.github.com>
---
 docs/cli.md                                   |   1 +
 .../.claude-plugin/marketplace.json           |  18 +++
 .../agency-plugin/.claude-plugin/plugin.json  |  19 ++++
 src/data/agency-plugin/agents/ado-aw.md       | 107 ++++++++++++++++++
 .../commands/create-ado-agentic-workflow.md   |  14 +++
 .../commands/debug-ado-agentic-workflow.md    |  14 +++
 .../commands/update-ado-agentic-workflow.md   |  15 +++
 src/init.rs                                   |  79 ++++++++++++-
 src/main.rs                                   |  12 +-
 tests/init_tests.rs                           |  88 +++++++++++++-
 10 files changed, 362 insertions(+), 5 deletions(-)
 create mode 100644 src/data/agency-plugin/.claude-plugin/marketplace.json
 create mode 100644 src/data/agency-plugin/.claude-plugin/plugin.json
 create mode 100644 src/data/agency-plugin/agents/ado-aw.md
 create mode 100644 src/data/agency-plugin/commands/create-ado-agentic-workflow.md
 create mode 100644 src/data/agency-plugin/commands/debug-ado-agentic-workflow.md
 create mode 100644 src/data/agency-plugin/commands/update-ado-agentic-workflow.md

diff --git a/docs/cli.md b/docs/cli.md
index 2313cb4d..132606f1 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -9,6 +9,7 @@ Global flags (apply to all subcommands): `--verbose, -v` (enable info-level logg
 - `init` - Initialize a repository for AI-first agentic pipeline authoring
   - `--path <path>` - Target directory (defaults to current directory)
   - `--force` - Bypass the GitHub-remote guard (use when running inside a GitHub-hosted repository like `githubnext/ado-aw` itself)
+  - `--agency` - **Additive.** Also generate an Agency / [Claude Code plugin](https://code.claude.com/docs/en/plugins-reference) under the Claude Code default `.claude` directory (in addition to the standard Copilot agent file). Emits `.claude/.claude-plugin/plugin.json` (manifest) + `marketplace.json`, an `agents/ado-aw.md` dispatcher subagent, and `commands/{create,update,debug}-ado-agentic-workflow.md` slash commands.
   - Creates `.github/agents/ado-aw.agent.md` — a Copilot dispatcher agent that routes to specialized prompts for creating, updating, and debugging agentic pipelines
   - The agent auto-downloads the ado-aw compiler and handles the full lifecycle (create → compile → check)
 - `compile [<path>]` - Compile a markdown file to Azure DevOps pipeline YAML. If no path is given, auto-discovers and recompiles all detected agentic pipelines in the current directory.
diff --git a/src/data/agency-plugin/.claude-plugin/marketplace.json b/src/data/agency-plugin/.claude-plugin/marketplace.json
new file mode 100644
index 00000000..616c1331
--- /dev/null
+++ b/src/data/agency-plugin/.claude-plugin/marketplace.json
@@ -0,0 +1,18 @@
+{
+  "name": "ado-aw",
+  "owner": {
+    "name": "githubnext",
+    "url": "https://github.com/githubnext/ado-aw"
+  },
+  "metadata": {
+    "description": "Azure DevOps Agentic Pipelines (ado-aw) plugin marketplace",
+    "version": "{{ compiler_version }}"
+  },
+  "plugins": [
+    {
+      "name": "ado-aw",
+      "source": "./",
+      "description": "Create, update, and debug Azure DevOps agentic pipelines with ado-aw"
+    }
+  ]
+}
diff --git a/src/data/agency-plugin/.claude-plugin/plugin.json b/src/data/agency-plugin/.claude-plugin/plugin.json
new file mode 100644
index 00000000..c18e6e43
--- /dev/null
+++ b/src/data/agency-plugin/.claude-plugin/plugin.json
@@ -0,0 +1,19 @@
+{
+  "name": "ado-aw",
+  "version": "{{ compiler_version }}",
+  "description": "Azure DevOps Agentic Pipelines (ado-aw) - Create, update, and debug AI-powered ADO pipelines",
+  "author": {
+    "name": "githubnext",
+    "url": "https://github.com/githubnext/ado-aw"
+  },
+  "homepage": "https://github.com/githubnext/ado-aw",
+  "repository": "https://github.com/githubnext/ado-aw",
+  "license": "MIT",
+  "keywords": [
+    "azure-devops",
+    "ado",
+    "agentic",
+    "pipelines",
+    "ado-aw"
+  ]
+}
diff --git a/src/data/agency-plugin/agents/ado-aw.md b/src/data/agency-plugin/agents/ado-aw.md
new file mode 100644
index 00000000..979fb250
--- /dev/null
+++ b/src/data/agency-plugin/agents/ado-aw.md
@@ -0,0 +1,107 @@
+---
+name: ado-aw
+description: Create, update, and debug Azure DevOps agentic pipelines using ado-aw. Use when the user wants to author, modify, or troubleshoot AI-powered Azure DevOps pipelines written as markdown agent files.
+---
+
+# ADO Agentic Pipelines Agent
+
+This agent helps you create and manage Azure DevOps agentic pipelines using **ado-aw**.
+
+ado-aw compiles human-friendly markdown files with YAML front matter into secure, multi-stage Azure DevOps pipelines that run AI agents in network-isolated sandboxes.
+
+## Setup
+
+Before creating or compiling workflows, ensure the ado-aw compiler is available. Use the first-time installer for your platform:
+
+```bash
+# Linux
+curl -fsSL https://github.com/githubnext/ado-aw/releases/latest/download/install-linux.sh | sh
+
+# macOS (Apple Silicon)
+curl -fsSL https://github.com/githubnext/ado-aw/releases/latest/download/install-macos.sh | sh
+
+# Windows (PowerShell)
+powershell -ExecutionPolicy Bypass -NoProfile -Command "iwr https://github.com/githubnext/ado-aw/releases/latest/download/install-windows.ps1 -UseBasicParsing | iex"
+```
+
+These scripts validate release checksums, install `ado-aw`, and update PATH when needed.
+
+Verify: `ado-aw --version`
+
+## What This Agent Does
+
+This is a **dispatcher agent** that routes your request to the appropriate specialized prompt. The matching slash commands are also available:
+
+- **Creating new agentic pipelines** → `/create-ado-agentic-workflow`
+- **Updating existing pipelines** → `/update-ado-agentic-workflow`
+- **Debugging failing pipelines** → `/debug-ado-agentic-workflow`
+
+## Available Prompts
+
+### Create New Agentic Pipeline
+**Load when**: User wants to create a new agentic pipeline from scratch
+
+**Prompt file**: https://raw.githubusercontent.com/githubnext/ado-aw/v{{ compiler_version }}/prompts/create-ado-agentic-workflow.md
+
+**Use cases**:
+- "Create an agentic pipeline that reviews PRs weekly"
+- "I need a pipeline that triages work items daily"
+- "Design a scheduled dependency updater"
+
+### Update Existing Pipeline
+**Load when**: User wants to modify an existing agent workflow file
+
+**Prompt file**: https://raw.githubusercontent.com/githubnext/ado-aw/v{{ compiler_version }}/prompts/update-ado-agentic-workflow.md
+
+**Use cases**:
+- "Add the Azure DevOps MCP to my pipeline"
+- "Change the schedule from daily to weekly"
+- "Add work item creation as a safe output"
+
+### Debug Failing Pipeline
+**Load when**: User needs to troubleshoot a failing agentic pipeline
+
+**Prompt file**: https://raw.githubusercontent.com/githubnext/ado-aw/v{{ compiler_version }}/prompts/debug-ado-agentic-workflow.md
+
+**Use cases**:
+- "Why is my agentic pipeline failing?"
+- "The agent can't reach the MCP server"
+- "Safe outputs aren't being processed"
+
+## Instructions
+
+When a user interacts with you:
+
+1. **Identify the task type** from the user's request
+2. **Load the appropriate prompt** from the URLs listed above
+3. **Follow the loaded prompt's instructions** exactly
+4. **If uncertain**, ask clarifying questions to determine the right prompt
+
+## Quick Reference
+
+```bash
+# Compile an agent file to pipeline YAML
+ado-aw compile <agent-file.md>
+
+# Recompile all detected pipelines
+ado-aw compile
+
+# Verify pipeline matches source
+ado-aw check <pipeline.lock.yml>
+```
+
+## Key Features
+
+- **Natural language pipelines**: Write in markdown with YAML frontmatter
+- **3-stage security**: Agent → Threat Analysis → Safe Output Execution
+- **Network isolation**: AWF (Agentic Workflow Firewall) with domain whitelisting
+- **MCP Gateway**: Tool routing for Azure DevOps, custom MCPs
+- **Safe outputs**: Controlled write operations (PRs, work items, wiki pages)
+- **Agent memory**: Persistent storage across pipeline runs
+
+## Important Notes
+
+- Agent files must be compiled with `ado-aw compile` after YAML frontmatter changes
+- Markdown body (agent instructions) changes do NOT require recompilation
+- The agent never has direct write access — all mutations go through safe outputs
+- Full reference: https://raw.githubusercontent.com/githubnext/ado-aw/v{{ compiler_version }}/AGENTS.md
diff --git a/src/data/agency-plugin/commands/create-ado-agentic-workflow.md b/src/data/agency-plugin/commands/create-ado-agentic-workflow.md
new file mode 100644
index 00000000..630d0409
--- /dev/null
+++ b/src/data/agency-plugin/commands/create-ado-agentic-workflow.md
@@ -0,0 +1,14 @@
+---
+description: Create a new Azure DevOps agentic pipeline from scratch with ado-aw.
+---
+
+You are creating a new **ado-aw** agentic pipeline. Make sure the `ado-aw`
+compiler is installed (`ado-aw --version`); if not, install it using the
+platform installer scripts from the ado-aw releases page.
+
+Load the **entire** content of the following prompt and follow its
+instructions precisely:
+
+https://raw.githubusercontent.com/githubnext/ado-aw/v{{ compiler_version }}/prompts/create-ado-agentic-workflow.md
+
+The user's request: $ARGUMENTS
diff --git a/src/data/agency-plugin/commands/debug-ado-agentic-workflow.md b/src/data/agency-plugin/commands/debug-ado-agentic-workflow.md
new file mode 100644
index 00000000..d7f36c4f
--- /dev/null
+++ b/src/data/agency-plugin/commands/debug-ado-agentic-workflow.md
@@ -0,0 +1,14 @@
+---
+description: Debug a failing Azure DevOps agentic pipeline authored with ado-aw.
+---
+
+You are debugging a failing **ado-aw** agentic pipeline. Make sure the
+`ado-aw` compiler is installed (`ado-aw --version`); if not, install it using
+the platform installer scripts from the ado-aw releases page.
+
+Load the **entire** content of the following prompt and follow its
+instructions precisely:
+
+https://raw.githubusercontent.com/githubnext/ado-aw/v{{ compiler_version }}/prompts/debug-ado-agentic-workflow.md
+
+The user's request: $ARGUMENTS
diff --git a/src/data/agency-plugin/commands/update-ado-agentic-workflow.md b/src/data/agency-plugin/commands/update-ado-agentic-workflow.md
new file mode 100644
index 00000000..6e0fc4ea
--- /dev/null
+++ b/src/data/agency-plugin/commands/update-ado-agentic-workflow.md
@@ -0,0 +1,15 @@
+---
+description: Update an existing Azure DevOps agentic pipeline authored with ado-aw.
+---
+
+You are updating an existing **ado-aw** agentic pipeline. Make sure the
+`ado-aw` compiler is installed (`ado-aw --version`); if not, install it using
+the platform installer scripts from the ado-aw releases page.
+
+Load the **entire** content of the following prompt and follow its
+instructions precisely. Read the existing agent file before making any
+changes, and recompile with `ado-aw compile` after editing YAML front matter:
+
+https://raw.githubusercontent.com/githubnext/ado-aw/v{{ compiler_version }}/prompts/update-ado-agentic-workflow.md
+
+The user's request: $ARGUMENTS
diff --git a/src/init.rs b/src/init.rs
index 8b64c86b..9a592894 100644
--- a/src/init.rs
+++ b/src/init.rs
@@ -1,5 +1,5 @@
 use anyhow::{Context, Result};
-use std::path::PathBuf;
+use std::path::{Path, PathBuf};
 
 // The agent template is embedded from src/data/init-agent.md
 const AGENT_TEMPLATE: &str = include_str!("data/init-agent.md");
@@ -7,7 +7,49 @@ const AGENT_TEMPLATE: &str = include_str!("data/init-agent.md");
 const AGENT_DIR: &str = ".github/agents";
 const AGENT_FILENAME: &str = "ado-aw.agent.md";
 
-pub async fn run(path: Option<&std::path::Path>) -> Result<()> {
+/// Root directory (relative to the target repo) for the generated Agency /
+/// Claude Code plugin. Uses the Claude Code default project-scoped
+/// configuration directory (`.claude`).
+const AGENCY_PLUGIN_DIR: &str = ".claude";
+
+/// Files that make up the Agency plugin, following the Claude Code plugin
+/// conventions (https://code.claude.com/docs/en/plugins-reference):
+///   - `.claude-plugin/plugin.json` — plugin manifest
+///   - `.claude-plugin/marketplace.json` — marketplace so the plugin is
+///     installable straight from this dir
+///   - `agents/ado-aw.md` — dispatcher subagent
+///   - `commands/*.md` — slash commands routing to prompts
+///
+/// Each entry is `(relative path within the plugin dir, embedded template)`.
+/// `{{ compiler_version }}` placeholders are substituted at write time.
+const AGENCY_PLUGIN_FILES: &[(&str, &str)] = &[
+    (
+        ".claude-plugin/plugin.json",
+        include_str!("data/agency-plugin/.claude-plugin/plugin.json"),
+    ),
+    (
+        ".claude-plugin/marketplace.json",
+        include_str!("data/agency-plugin/.claude-plugin/marketplace.json"),
+    ),
+    (
+        "agents/ado-aw.md",
+        include_str!("data/agency-plugin/agents/ado-aw.md"),
+    ),
+    (
+        "commands/create-ado-agentic-workflow.md",
+        include_str!("data/agency-plugin/commands/create-ado-agentic-workflow.md"),
+    ),
+    (
+        "commands/update-ado-agentic-workflow.md",
+        include_str!("data/agency-plugin/commands/update-ado-agentic-workflow.md"),
+    ),
+    (
+        "commands/debug-ado-agentic-workflow.md",
+        include_str!("data/agency-plugin/commands/debug-ado-agentic-workflow.md"),
+    ),
+];
+
+pub async fn run(path: Option<&std::path::Path>, agency: bool) -> Result<()> {
     let base = path
         .map(PathBuf::from)
         .unwrap_or_else(|| PathBuf::from("."));
@@ -33,6 +75,13 @@ pub async fn run(path: Option<&std::path::Path>) -> Result<()> {
 
     // Print success message
     println!("✓ Created {}", agent_path.display());
+
+    // `--agency` is additive: keep the standard agent file above and also emit
+    // the Agency / Claude Code plugin.
+    if agency {
+        write_agency_plugin(&base, version).await?;
+    }
+
     println!();
     println!("This agent helps you create, update, and debug Azure DevOps agentic pipelines.");
     println!("It will automatically download the ado-aw compiler and handle compilation.");
@@ -47,3 +96,29 @@ pub async fn run(path: Option<&std::path::Path>) -> Result<()> {
 
     Ok(())
 }
+
+/// Write the Agency / Claude Code plugin into `<base>/.claude`.
+///
+/// The plugin is additive to the standard agent file and follows the Claude
+/// Code plugin conventions, written to the Claude Code default project-scoped
+/// directory.
+async fn write_agency_plugin(base: &Path, version: &str) -> Result<()> {
+    let plugin_root = base.join(AGENCY_PLUGIN_DIR);
+
+    for (rel_path, template) in AGENCY_PLUGIN_FILES {
+        let dest = plugin_root.join(rel_path);
+        if let Some(parent) = dest.parent() {
+            tokio::fs::create_dir_all(parent)
+                .await
+                .with_context(|| format!("Failed to create directory: {}", parent.display()))?;
+        }
+        let content = template.replace("{{ compiler_version }}", version);
+        tokio::fs::write(&dest, content)
+            .await
+            .with_context(|| format!("Failed to write plugin file: {}", dest.display()))?;
+    }
+
+    println!("✓ Created Agency plugin in {}", plugin_root.display());
+
+    Ok(())
+}
diff --git a/src/main.rs b/src/main.rs
index 05bf8058..245bf4f9 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -291,6 +291,10 @@ enum Commands {
         /// GitHub-hosted repository like `githubnext/ado-aw` itself)
         #[arg(long)]
         force: bool,
+        /// Additionally generate an Agency / Claude Code plugin under
+        /// `.claude` (additive to the standard agent file).
+        #[arg(long)]
+        agency: bool,
     },
     /// (Deprecated) Set GITHUB_TOKEN on every matched ADO definition.
     /// Use `secrets set GITHUB_TOKEN <value>` instead.
@@ -1085,7 +1089,11 @@ async fn main() -> Result<()> {
             )
             .await?;
         }
-        Commands::Init { path, force } => {
+        Commands::Init {
+            path,
+            force,
+            agency,
+        } => {
             let init_path = path.as_deref().unwrap_or(Path::new("."));
             // `--force` bypasses the GitHub-remote guard so maintainers can
             // run `ado-aw init` inside this repository (or other GitHub-hosted
@@ -1093,7 +1101,7 @@ async fn main() -> Result<()> {
             if !force {
                 ensure_non_github_remote_for_ado_aw("init", init_path).await?;
             }
-            init::run(path.as_deref()).await?;
+            init::run(path.as_deref(), agency).await?;
         }
         Commands::Configure {
             token,
diff --git a/tests/init_tests.rs b/tests/init_tests.rs
index b3344fba..cc63d161 100644
--- a/tests/init_tests.rs
+++ b/tests/init_tests.rs
@@ -75,7 +75,93 @@ fn test_init_overwrites_by_default() {
     );
 }
 
-/// Test that `--force` is advertised in `init --help` and describes its
+/// Test that `init --agency` is additive: it produces the standard agent file
+/// AND the Agency / Claude Code plugin under the `.claude` default directory.
+#[test]
+fn test_init_agency_generates_plugin() {
+    let temp_dir = tempfile::tempdir().expect("Failed to create temp directory");
+
+    let output = ado_aw_bin()
+        .args([
+            "init",
+            "--agency",
+            "--path",
+            temp_dir.path().to_str().unwrap(),
+        ])
+        .output()
+        .expect("Failed to run ado-aw init --agency");
+
+    assert!(
+        output.status.success(),
+        "init --agency should succeed: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+
+    // Standard agent file is still produced (additive behavior).
+    let agent_path = temp_dir.path().join(".github/agents/ado-aw.agent.md");
+    assert!(
+        agent_path.exists(),
+        "Standard agent file should still be created with --agency"
+    );
+
+    // Claude Code plugin manifest + marketplace under the default `.claude` dir.
+    let plugin_root = temp_dir.path().join(".claude");
+    let plugin_json = plugin_root.join(".claude-plugin/plugin.json");
+    let marketplace_json = plugin_root.join(".claude-plugin/marketplace.json");
+    assert!(plugin_json.exists(), "plugin.json should be created");
+    assert!(
+        marketplace_json.exists(),
+        "marketplace.json should be created"
+    );
+
+    // Subagent + slash commands.
+    assert!(
+        plugin_root.join("agents/ado-aw.md").exists(),
+        "Agency subagent should be created"
+    );
+    for cmd in [
+        "create-ado-agentic-workflow.md",
+        "update-ado-agentic-workflow.md",
+        "debug-ado-agentic-workflow.md",
+    ] {
+        assert!(
+            plugin_root.join("commands").join(cmd).exists(),
+            "Command {cmd} should be created"
+        );
+    }
+
+    // Version placeholder must be substituted in the manifest.
+    let manifest =
+        fs::read_to_string(&plugin_json).expect("Should be able to read plugin.json");
+    assert!(
+        !manifest.contains("{{ compiler_version }}"),
+        "Version placeholder should be replaced in plugin.json"
+    );
+    // plugin.json must be valid JSON with the expected plugin name.
+    let parsed: serde_json::Value =
+        serde_json::from_str(&manifest).expect("plugin.json should be valid JSON");
+    assert_eq!(
+        parsed["name"], "ado-aw",
+        "plugin.json name should be ado-aw"
+    );
+}
+
+/// Test that `init` WITHOUT `--agency` does not create the plugin directory.
+#[test]
+fn test_init_without_agency_skips_plugin() {
+    let temp_dir = tempfile::tempdir().expect("Failed to create temp directory");
+
+    let output = ado_aw_bin()
+        .args(["init", "--path", temp_dir.path().to_str().unwrap()])
+        .output()
+        .expect("Failed to run ado-aw init");
+    assert!(output.status.success(), "init should succeed");
+
+    assert!(
+        !temp_dir.path().join(".claude").exists(),
+        "Plugin directory should not be created without --agency"
+    );
+}
 /// actual purpose: bypassing the GitHub-remote guard so maintainers can run
 /// `ado-aw init` inside a GitHub-hosted fork of `ado-aw` itself.
 ///

From 5adc455fc526cf897b3c5df1d25ce367545b29a4 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 18 Jun 2026 15:30:19 +0000
Subject: [PATCH 02/10] refactor(init): place --agency plugin under
 .github/ado-aw

Co-authored-by: jamesadevine <4742697+jamesadevine@users.noreply.github.com>
---
 docs/cli.md         |  2 +-
 src/init.rs         | 12 ++++++------
 src/main.rs         |  2 +-
 tests/init_tests.rs |  8 ++++----
 4 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/docs/cli.md b/docs/cli.md
index 132606f1..4ad83f1a 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -9,7 +9,7 @@ Global flags (apply to all subcommands): `--verbose, -v` (enable info-level logg
 - `init` - Initialize a repository for AI-first agentic pipeline authoring
   - `--path <path>` - Target directory (defaults to current directory)
   - `--force` - Bypass the GitHub-remote guard (use when running inside a GitHub-hosted repository like `githubnext/ado-aw` itself)
-  - `--agency` - **Additive.** Also generate an Agency / [Claude Code plugin](https://code.claude.com/docs/en/plugins-reference) under the Claude Code default `.claude` directory (in addition to the standard Copilot agent file). Emits `.claude/.claude-plugin/plugin.json` (manifest) + `marketplace.json`, an `agents/ado-aw.md` dispatcher subagent, and `commands/{create,update,debug}-ado-agentic-workflow.md` slash commands.
+  - `--agency` - **Additive.** Also generate an Agency / [Claude Code plugin](https://code.claude.com/docs/en/plugins-reference) under `.github/ado-aw` (in addition to the standard Copilot agent file). Emits `.github/ado-aw/.claude-plugin/plugin.json` (manifest) + `marketplace.json`, an `agents/ado-aw.md` dispatcher subagent, and `commands/{create,update,debug}-ado-agentic-workflow.md` slash commands.
   - Creates `.github/agents/ado-aw.agent.md` — a Copilot dispatcher agent that routes to specialized prompts for creating, updating, and debugging agentic pipelines
   - The agent auto-downloads the ado-aw compiler and handles the full lifecycle (create → compile → check)
 - `compile [<path>]` - Compile a markdown file to Azure DevOps pipeline YAML. If no path is given, auto-discovers and recompiles all detected agentic pipelines in the current directory.
diff --git a/src/init.rs b/src/init.rs
index 9a592894..c9cdfe0e 100644
--- a/src/init.rs
+++ b/src/init.rs
@@ -8,9 +8,9 @@ const AGENT_DIR: &str = ".github/agents";
 const AGENT_FILENAME: &str = "ado-aw.agent.md";
 
 /// Root directory (relative to the target repo) for the generated Agency /
-/// Claude Code plugin. Uses the Claude Code default project-scoped
-/// configuration directory (`.claude`).
-const AGENCY_PLUGIN_DIR: &str = ".claude";
+/// Claude Code plugin. Placed under `.github/ado-aw` so it does not pollute
+/// the user's source tree like the conventional top-level plugin folder would.
+const AGENCY_PLUGIN_DIR: &str = ".github/ado-aw";
 
 /// Files that make up the Agency plugin, following the Claude Code plugin
 /// conventions (https://code.claude.com/docs/en/plugins-reference):
@@ -97,11 +97,11 @@ pub async fn run(path: Option<&std::path::Path>, agency: bool) -> Result<()> {
     Ok(())
 }
 
-/// Write the Agency / Claude Code plugin into `<base>/.claude`.
+/// Write the Agency / Claude Code plugin into `<base>/.github/ado-aw`.
 ///
 /// The plugin is additive to the standard agent file and follows the Claude
-/// Code plugin conventions, written to the Claude Code default project-scoped
-/// directory.
+/// Code plugin conventions, written under `.github/ado-aw` so it does not
+/// pollute the user's source tree.
 async fn write_agency_plugin(base: &Path, version: &str) -> Result<()> {
     let plugin_root = base.join(AGENCY_PLUGIN_DIR);
 
diff --git a/src/main.rs b/src/main.rs
index 245bf4f9..c876b23d 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -292,7 +292,7 @@ enum Commands {
         #[arg(long)]
         force: bool,
         /// Additionally generate an Agency / Claude Code plugin under
-        /// `.claude` (additive to the standard agent file).
+        /// `.github/ado-aw` (additive to the standard agent file).
         #[arg(long)]
         agency: bool,
     },
diff --git a/tests/init_tests.rs b/tests/init_tests.rs
index cc63d161..bfd6c3a7 100644
--- a/tests/init_tests.rs
+++ b/tests/init_tests.rs
@@ -76,7 +76,7 @@ fn test_init_overwrites_by_default() {
 }
 
 /// Test that `init --agency` is additive: it produces the standard agent file
-/// AND the Agency / Claude Code plugin under the `.claude` default directory.
+/// AND the Agency / Claude Code plugin under the `.github/ado-aw` directory.
 #[test]
 fn test_init_agency_generates_plugin() {
     let temp_dir = tempfile::tempdir().expect("Failed to create temp directory");
@@ -104,8 +104,8 @@ fn test_init_agency_generates_plugin() {
         "Standard agent file should still be created with --agency"
     );
 
-    // Claude Code plugin manifest + marketplace under the default `.claude` dir.
-    let plugin_root = temp_dir.path().join(".claude");
+    // Claude Code plugin manifest + marketplace under `.github/ado-aw`.
+    let plugin_root = temp_dir.path().join(".github/ado-aw");
     let plugin_json = plugin_root.join(".claude-plugin/plugin.json");
     let marketplace_json = plugin_root.join(".claude-plugin/marketplace.json");
     assert!(plugin_json.exists(), "plugin.json should be created");
@@ -158,7 +158,7 @@ fn test_init_without_agency_skips_plugin() {
     assert!(output.status.success(), "init should succeed");
 
     assert!(
-        !temp_dir.path().join(".claude").exists(),
+        !temp_dir.path().join(".github/ado-aw").exists(),
         "Plugin directory should not be created without --agency"
     );
 }

From 7ae330e2145b40fc04e64ed1da54ef488abd4bc4 Mon Sep 17 00:00:00 2001
From: James Devine <devinejames@microsoft.com>
Date: Mon, 22 Jun 2026 11:22:52 +0100
Subject: [PATCH 03/10] feat(agency): centralize Claude Code plugin and
 self-contained marketplace

Promote the embedded `--agency` templates into a live, checked-in plugin at
`agency/plugins/ado-aw/` as the single source of truth, and implement the full
Agency marketplace spec: plugin.json, .mcp.json wiring the read-only
`ado-aw mcp-author` server, agency.json governance (external `source` pointer,
org-only identity, no PII), README, an agents/ado-aw.md dispatcher, six
skills/*/SKILL.md playbooks, and scripts/doctor.{sh,ps1} prerequisite checks.

Make the repository itself an installable marketplace: add repo-root catalogs
`.claude-plugin/marketplace.json` (Claude) and `.github/plugin/marketplace.json`
(Copilot) that list the plugin via `source: "./agency/plugins/ado-aw"`, so
`/plugin marketplace add <repo>` detects it. `ado-aw init --agency` scaffolds the
plugin under `agency/plugins/ado-aw/` plus those root catalogs.

Align terminology on the canonical brand "Azure DevOps Agentic Workflows": the
authored markdown spec is an "agentic workflow"; "pipeline" is reserved for the
compiled ADO execution artifact. Swept the init-generated output, root catalogs,
README, AGENTS.md title/prose, and user-facing CLI help strings.

Versions stay lock-step with the compiler via release-please `extra-files`: the
plugin manifest, both root catalogs (metadata + plugin entry), and the pinned
prompt URLs in the agent + create/update/debug skills bump on each release.
`init` embeds the canonical files via include_str! and writes them verbatim; the
duplicate src/data/agency-plugin tree is removed. Parity tests assert the
scaffold matches the canonical source byte-for-byte. .gitattributes forces LF
under agency/plugins/** and the root catalogs.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .claude-plugin/marketplace.json               |  20 +++
 .gitattributes                                |   6 +
 .github/agents/ado-aw.agent.md                |  42 ++---
 .github/plugin/marketplace.json               |  20 +++
 AGENTS.md                                     |  47 ++++--
 README.md                                     |  16 +-
 .../plugins/ado-aw/.claude-plugin/plugin.json |  23 +++
 agency/plugins/ado-aw/.mcp.json               |  10 ++
 agency/plugins/ado-aw/README.md               |  80 +++++++++
 agency/plugins/ado-aw/agency.json             |  26 +++
 agency/plugins/ado-aw/agents/ado-aw.md        |  85 ++++++++++
 agency/plugins/ado-aw/scripts/doctor.ps1      |  56 +++++++
 agency/plugins/ado-aw/scripts/doctor.sh       |  60 +++++++
 .../ado-aw/skills/audit-build/SKILL.md        |  31 ++++
 .../skills/compile-and-validate/SKILL.md      |  31 ++++
 .../ado-aw/skills/create-workflow/SKILL.md    |  28 ++++
 .../ado-aw/skills/debug-workflow/SKILL.md     |  33 ++++
 .../ado-aw/skills/manage-lifecycle/SKILL.md   |  36 ++++
 .../ado-aw/skills/update-workflow/SKILL.md    |  29 ++++
 docs/cli.md                                   |   2 +-
 release-please-config.json                    |  33 +++-
 .../.claude-plugin/marketplace.json           |  18 --
 .../agency-plugin/.claude-plugin/plugin.json  |  19 ---
 src/data/agency-plugin/agents/ado-aw.md       | 107 ------------
 .../commands/create-ado-agentic-workflow.md   |  14 --
 .../commands/debug-ado-agentic-workflow.md    |  14 --
 .../commands/update-ado-agentic-workflow.md   |  15 --
 src/data/init-agent.md                        |  32 ++--
 src/init.rs                                   | 136 +++++++++++----
 src/main.rs                                   |   4 +-
 tests/init_tests.rs                           | 158 +++++++++++++++---
 31 files changed, 927 insertions(+), 304 deletions(-)
 create mode 100644 .claude-plugin/marketplace.json
 create mode 100644 .github/plugin/marketplace.json
 create mode 100644 agency/plugins/ado-aw/.claude-plugin/plugin.json
 create mode 100644 agency/plugins/ado-aw/.mcp.json
 create mode 100644 agency/plugins/ado-aw/README.md
 create mode 100644 agency/plugins/ado-aw/agency.json
 create mode 100644 agency/plugins/ado-aw/agents/ado-aw.md
 create mode 100644 agency/plugins/ado-aw/scripts/doctor.ps1
 create mode 100644 agency/plugins/ado-aw/scripts/doctor.sh
 create mode 100644 agency/plugins/ado-aw/skills/audit-build/SKILL.md
 create mode 100644 agency/plugins/ado-aw/skills/compile-and-validate/SKILL.md
 create mode 100644 agency/plugins/ado-aw/skills/create-workflow/SKILL.md
 create mode 100644 agency/plugins/ado-aw/skills/debug-workflow/SKILL.md
 create mode 100644 agency/plugins/ado-aw/skills/manage-lifecycle/SKILL.md
 create mode 100644 agency/plugins/ado-aw/skills/update-workflow/SKILL.md
 delete mode 100644 src/data/agency-plugin/.claude-plugin/marketplace.json
 delete mode 100644 src/data/agency-plugin/.claude-plugin/plugin.json
 delete mode 100644 src/data/agency-plugin/agents/ado-aw.md
 delete mode 100644 src/data/agency-plugin/commands/create-ado-agentic-workflow.md
 delete mode 100644 src/data/agency-plugin/commands/debug-ado-agentic-workflow.md
 delete mode 100644 src/data/agency-plugin/commands/update-ado-agentic-workflow.md

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
new file mode 100644
index 00000000..68e3ff90
--- /dev/null
+++ b/.claude-plugin/marketplace.json
@@ -0,0 +1,20 @@
+{
+  "name": "ado-aw",
+  "metadata": {
+    "description": "Azure DevOps Agentic Workflows (ado-aw) marketplace",
+    "version": "0.37.0"
+  },
+  "owner": {
+    "name": "GitHub Next",
+    "url": "https://github.com/githubnext/ado-aw"
+  },
+  "plugins": [
+    {
+      "name": "ado-aw",
+      "source": "./agency/plugins/ado-aw",
+      "version": "0.37.0",
+      "description": "Create, update, validate, operate, and debug Azure DevOps agentic workflows with ado-aw",
+      "keywords": ["azure-devops", "ado", "agentic", "pipelines", "ado-aw"]
+    }
+  ]
+}
diff --git a/.gitattributes b/.gitattributes
index 0ff4ac97..0b0ef50a 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -3,6 +3,12 @@
 # Install scripts must always be LF (executed on Linux/macOS via curl|sh).
 scripts/install/*.sh text eol=lf
 scripts/install/*.ps1 text eol=lf
+# Agency plugin is a Linux/macOS-consumed artifact (and release-please rewrites
+# it on Linux CI) — keep every text file LF.
+agency/plugins/** text eol=lf
+# Generated marketplace catalogs (release-please rewrites on Linux CI).
+.claude-plugin/marketplace.json text eol=lf
+.github/plugin/marketplace.json text eol=lf
 # BEGIN ado-aw managed (do not edit)
 tests/fixtures/job-agent.lock.yml linguist-generated=true merge=ours text eol=lf
 tests/fixtures/runtime_imports_author_marker_job.lock.yml linguist-generated=true merge=ours text eol=lf
diff --git a/.github/agents/ado-aw.agent.md b/.github/agents/ado-aw.agent.md
index d194b89d..c2f51220 100644
--- a/.github/agents/ado-aw.agent.md
+++ b/.github/agents/ado-aw.agent.md
@@ -1,11 +1,11 @@
 ---
-description: Azure DevOps Agentic Pipelines (ado-aw) - Create, update, and debug AI-powered ADO pipelines
+description: Azure DevOps Agentic Workflows (ado-aw) - Create, update, and debug AI-powered Azure DevOps agentic workflows
 disable-model-invocation: true
 ---
 
-# ADO Agentic Pipelines Agent
+# Azure DevOps Agentic Workflows Agent
 
-This agent helps you create and manage Azure DevOps agentic pipelines using **ado-aw**.
+This agent helps you create and manage Azure DevOps agentic workflows using **ado-aw**.
 
 ado-aw compiles human-friendly markdown files with YAML front matter into secure, multi-stage Azure DevOps pipelines that run AI agents in network-isolated sandboxes.
 
@@ -37,39 +37,39 @@ Verify: `ado-aw --version`
 
 This is a **dispatcher agent** that routes your request to the appropriate specialized prompt:
 
-- **Creating new agentic pipelines** → Routes to the create prompt
-- **Updating existing pipelines** → Routes to the update prompt  
-- **Debugging failing pipelines** → Routes to the debug prompt
+- **Creating new agentic workflows** → Routes to the create prompt
+- **Updating existing workflows** → Routes to the update prompt  
+- **Debugging failing workflows** → Routes to the debug prompt
 
 ## Available Prompts
 
-### Create New Agentic Pipeline
-**Load when**: User wants to create a new agentic pipeline from scratch
+### Create New Agentic Workflow
+**Load when**: User wants to create a new agentic workflow from scratch
 
-**Prompt file**: https://raw.githubusercontent.com/githubnext/ado-aw/v0.16.0/prompts/create-ado-agentic-workflow.md
+**Prompt file**: https://raw.githubusercontent.com/githubnext/ado-aw/v0.37.0/prompts/create-ado-agentic-workflow.md
 
 **Use cases**:
-- "Create an agentic pipeline that reviews PRs weekly"
-- "I need a pipeline that triages work items daily"
+- "Create an agentic workflow that reviews PRs weekly"
+- "I need a workflow that triages work items daily"
 - "Design a scheduled dependency updater"
 
-### Update Existing Pipeline
+### Update Existing Workflow
 **Load when**: User wants to modify an existing agent workflow file
 
-**Prompt file**: https://raw.githubusercontent.com/githubnext/ado-aw/v0.16.0/prompts/update-ado-agentic-workflow.md
+**Prompt file**: https://raw.githubusercontent.com/githubnext/ado-aw/v0.37.0/prompts/update-ado-agentic-workflow.md
 
 **Use cases**:
-- "Add the Azure DevOps MCP to my pipeline"
+- "Add the Azure DevOps MCP to my workflow"
 - "Change the schedule from daily to weekly"
 - "Add work item creation as a safe output"
 
-### Debug Failing Pipeline
-**Load when**: User needs to troubleshoot a failing agentic pipeline
+### Debug Failing Workflow
+**Load when**: User needs to troubleshoot a failing agentic workflow
 
-**Prompt file**: https://raw.githubusercontent.com/githubnext/ado-aw/v0.16.0/prompts/debug-ado-agentic-workflow.md
+**Prompt file**: https://raw.githubusercontent.com/githubnext/ado-aw/v0.37.0/prompts/debug-ado-agentic-workflow.md
 
 **Use cases**:
-- "Why is my agentic pipeline failing?"
+- "Why is my agentic workflow failing?"
 - "The agent can't reach the MCP server"
 - "Safe outputs aren't being processed"
 
@@ -92,12 +92,12 @@ ado-aw compile <agent-file.md>
 ado-aw compile
 
 # Verify pipeline matches source
-ado-aw check <pipeline.yml>
+ado-aw check <pipeline.lock.yml>
 ```
 
 ## Key Features
 
-- **Natural language pipelines**: Write in markdown with YAML frontmatter
+- **Natural language workflows**: Write in markdown with YAML frontmatter
 - **3-stage security**: Agent → Threat Analysis → Safe Output Execution
 - **Network isolation**: AWF (Agentic Workflow Firewall) with domain whitelisting
 - **MCP Gateway**: Tool routing for Azure DevOps, custom MCPs
@@ -109,4 +109,4 @@ ado-aw check <pipeline.yml>
 - Agent files must be compiled with `ado-aw compile` after YAML frontmatter changes
 - Markdown body (agent instructions) changes do NOT require recompilation
 - The agent never has direct write access — all mutations go through safe outputs
-- Full reference: https://raw.githubusercontent.com/githubnext/ado-aw/v0.16.0/AGENTS.md
+- Full reference: https://raw.githubusercontent.com/githubnext/ado-aw/v0.37.0/AGENTS.md
diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json
new file mode 100644
index 00000000..68e3ff90
--- /dev/null
+++ b/.github/plugin/marketplace.json
@@ -0,0 +1,20 @@
+{
+  "name": "ado-aw",
+  "metadata": {
+    "description": "Azure DevOps Agentic Workflows (ado-aw) marketplace",
+    "version": "0.37.0"
+  },
+  "owner": {
+    "name": "GitHub Next",
+    "url": "https://github.com/githubnext/ado-aw"
+  },
+  "plugins": [
+    {
+      "name": "ado-aw",
+      "source": "./agency/plugins/ado-aw",
+      "version": "0.37.0",
+      "description": "Create, update, validate, operate, and debug Azure DevOps agentic workflows with ado-aw",
+      "keywords": ["azure-devops", "ado", "agentic", "pipelines", "ado-aw"]
+    }
+  ]
+}
diff --git a/AGENTS.md b/AGENTS.md
index 4c272ae4..ecfd23c9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,4 +1,4 @@
-# Copilot Instructions for Azure DevOps Agentic Pipelines
+# Copilot Instructions for Azure DevOps Agentic Workflows
 
 This repository contains a compiler for Azure DevOps pipelines that transforms
 natural language markdown files with YAML front matter into Azure DevOps
@@ -102,8 +102,21 @@ Every compiled pipeline runs as three sequential jobs:
 │   │   │   ├── 0002_pool_object_form.rs # Legacy scalar pool → object form codemod
 │   │   │   └── helpers.rs # take_key, insert_no_overwrite, rename_key, ConflictPolicy
 │   │   ├── codemod_integration_test.rs # White-box rewrite-path tests (stub registry injection)
-│   │   └── types.rs      # Front matter grammar and types
-│   ├── init.rs           # Repository initialization for AI-first authoring
+│   │   ├── types.rs      # Front matter grammar and types
+│   │   └── ir/           # Typed Azure DevOps pipeline IR (see docs/ir.md)
+│   │       ├── mod.rs    # Pipeline / PipelineBody / PipelineShape root types
+│   │       ├── ids.rs    # Typed StageId / JobId / StepId newtypes
+│   │       ├── step.rs   # Step variants (Bash, Task, Checkout, Download, Publish, RawYaml)
+│   │       ├── job.rs    # Job, Pool, TemplateContext, JobVariable
+│   │       ├── stage.rs  # Stage + external-params wrap
+│   │       ├── env.rs    # Typed EnvValue (Literal, AdoMacro, PipelineVar, Secret, StepOutput, Coalesce, Concat)
+│   │       ├── condition.rs # Typed Condition / Expr AST + codegen to ADO condition syntax
+│   │       ├── output.rs # OutputDecl / OutputRef + location-aware lowering
+│   │       ├── graph.rs  # Dependency graph: validation, edge derivation, isOutput promotion, cycle detection
+│   │       ├── lower.rs  # IR → serde_yaml::Value lowering
+│   │       ├── emit.rs   # Thin `lower() + serde_yaml::to_string()` wrapper
+│   │       └── summary.rs # Public, serializable PipelineSummary / GraphSummary for agent-facing tooling (see docs/ir.md Public JSON summary)
+│   ├── init.rs           # Repository initialization for AI-first authoring (incl. `--agency` plugin scaffold, embeds agency/plugins/ado-aw/ via include_str!)
 │   ├── execute.rs        # Stage 3 safe output execution
 │   ├── fuzzy_schedule.rs # Fuzzy schedule parsing
 │   ├── logging.rs        # File-based logging infrastructure
@@ -154,7 +167,7 @@ Every compiled pipeline runs as three sequential jobs:
 │   │   ├── whatif.rs     # `ado-aw whatif`: static downstream skip classification for failures
 │   │   ├── lint.rs       # `ado-aw lint`: structural workflow lint checks
 │   │   └── catalog.rs    # `ado-aw catalog`: list in-tree registries (tools, runtimes, models, etc.)
-│   ├── detect.rs         # Agentic pipeline detection — discovers compiled pipelines; used by all lifecycle commands
+│   ├── detect.rs         # Agentic workflow detection — discovers compiled pipelines; used by all lifecycle commands
 │   ├── update_check.rs   # Version update check — queries GitHub Releases and prints advisory when newer version is available
 │   ├── ndjson.rs         # NDJSON parsing utilities
 │   ├── sanitize.rs       # Input sanitization for safe outputs
@@ -217,11 +230,21 @@ Every compiled pipeline runs as three sequential jobs:
 │           ├── extension.rs # CompilerExtension impl (compile-time)
 │           └── execute.rs   # Stage 3 runtime (validate/copy)
 ├── ado-aw-derive/        # Proc-macro crate: #[derive(SanitizeConfig)], #[derive(SanitizeContent)]
+├── .claude-plugin/       # Root Claude marketplace catalog (makes the repo installable via `/plugin marketplace add`); release-please-versioned
+│   └── marketplace.json  # Lists the ado-aw plugin with source ./agency/plugins/ado-aw
+├── agency/               # Agency / Claude Code marketplace plugin (canonical source of truth)
+│   └── plugins/ado-aw/   # Version-locked plugin (release-please bumps version + pinned prompt URLs); listed in Agency marketplace via external `source`; scaffolded into consumer repos by `ado-aw init --agency`
+│       ├── .claude-plugin/ # plugin.json (manifest)
+│       ├── .mcp.json     # Wires read-only `ado-aw mcp-author` stdio server
+│       ├── agency.json   # Marketplace governance metadata + external source pointer
+│       ├── agents/ado-aw.md # Dispatcher subagent
+│       ├── skills/       # 6 SKILL.md playbooks (create/update/debug-workflow, compile-and-validate, manage-lifecycle, audit-build)
+│       └── scripts/      # doctor.{sh,ps1} prerequisite checks
 ├── examples/             # Example agent definitions
 ├── prompts/              # AI agent prompt files for workflow authoring tasks
-│   ├── create-ado-agentic-workflow.md # Step-by-step guide for creating a new agentic pipeline
-│   ├── update-ado-agentic-workflow.md # Guide for modifying an existing agentic pipeline
-│   └── debug-ado-agentic-workflow.md  # Guide for troubleshooting a failing agentic pipeline
+│   ├── create-ado-agentic-workflow.md # Step-by-step guide for creating a new agentic workflow
+│   ├── update-ado-agentic-workflow.md # Guide for modifying an existing agentic workflow
+│   └── debug-ado-agentic-workflow.md  # Guide for troubleshooting a failing agentic workflow
 ├── scripts/              # Supporting scripts shipped as release artifacts
 │   └── ado-script/       # TypeScript workspace for bundled gate/import helpers plus execution-context bundles
 │       └── src/
@@ -262,11 +285,11 @@ index to jump to the right page.
 ### Prompt files for workflow authoring
 
 - [`prompts/create-ado-agentic-workflow.md`](prompts/create-ado-agentic-workflow.md) — step-by-step
-  guide for creating a new agentic pipeline from scratch (interactive and non-interactive modes).
+  guide for creating a new agentic workflow from scratch (interactive and non-interactive modes).
 - [`prompts/update-ado-agentic-workflow.md`](prompts/update-ado-agentic-workflow.md) — guide for
-  modifying an existing agentic pipeline (read-then-update workflow with validation).
+  modifying an existing agentic workflow (read-then-update workflow with validation).
 - [`prompts/debug-ado-agentic-workflow.md`](prompts/debug-ado-agentic-workflow.md) — guide for
-  troubleshooting a failing agentic pipeline and filing a diagnostic report.
+  troubleshooting a failing agentic workflow and filing a diagnostic report.
 
 ### Authoring agent files
 
@@ -457,10 +480,10 @@ the bash body — shellcheck honours the directive and it's inert at runtime.
 cargo run -- compile ./path/to/agent.md
 ```
 
-### Recompile all agentic pipelines in the current directory
+### Recompile all agentic workflows in the current directory
 
 ```bash
-# Auto-discovers and recompiles all detected agentic pipelines
+# Auto-discovers and recompiles all detected agentic workflows
 cargo run -- compile
 ```
 
diff --git a/README.md b/README.md
index 8b7eaef3..c2857273 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,8 @@
 # ado-aw
 
-An agentic pipeline compiler for Azure DevOps. Write pipeline definitions in
-human-friendly markdown, compile them into secure, multi-stage Azure DevOps
-pipelines that run AI agents in network-isolated sandboxes.
+**Azure DevOps Agentic Workflows.** Write agentic workflows in human-friendly
+markdown; ado-aw compiles each into a secure, multi-stage Azure DevOps pipeline
+that runs an AI agent in a network-isolated sandbox.
 
 Inspired by [GitHub Agentic Workflows (gh-aw)](https://github.com/githubnext/gh-aw).
 
@@ -71,7 +71,7 @@ If you see `The Process object must have the UseShellExecute property set to fal
 ado-aw init
 ```
 
-This creates a Copilot agent at `.github/agents/ado-aw.agent.md` that helps you create, update, and debug agentic pipelines. The agent automatically downloads the ado-aw compiler and handles compilation.
+This creates a Copilot agent at `.github/agents/ado-aw.agent.md` that helps you create, update, and debug agentic workflows. The agent automatically downloads the ado-aw compiler and handles compilation.
 
 ### 3. Create an Agent with AI
 
@@ -87,7 +87,7 @@ and open PRs to update them.
 
 Or if you've run `ado-aw init`, simply ask your AI agent:
 ```
-Create an agentic pipeline that checks for outdated dependencies and opens PRs
+Create an agentic workflow that checks for outdated dependencies and opens PRs
 ```
 
 The AI will generate a markdown file like:
@@ -522,7 +522,7 @@ network:
 ado-aw [OPTIONS] <COMMAND>
 
 Commands:
-  init          Initialize a repository for AI-first agentic pipeline authoring
+  init          Initialize a repository for AI-first agentic workflow authoring
   compile       Compile markdown to pipeline definition
   check         Verify a compiled pipeline matches its source
   mcp           Run as an MCP server (safe outputs)
@@ -568,9 +568,9 @@ ado-aw provides specialized prompt files that guide AI agents through common tas
 
 | Task | Prompt URL | Description |
 |------|-----------|-------------|
-| Create a workflow | [create-ado-agentic-workflow.md](prompts/create-ado-agentic-workflow.md) | Step-by-step guide for creating a new agentic pipeline from scratch |
+| Create a workflow | [create-ado-agentic-workflow.md](prompts/create-ado-agentic-workflow.md) | Step-by-step guide for creating a new agentic workflow from scratch |
 | Update a workflow | [update-ado-agentic-workflow.md](prompts/update-ado-agentic-workflow.md) | Guide for modifying existing agent workflows |
-| Debug a pipeline | [debug-ado-agentic-workflow.md](prompts/debug-ado-agentic-workflow.md) | Troubleshoot failing agentic pipelines |
+| Debug a workflow | [debug-ado-agentic-workflow.md](prompts/debug-ado-agentic-workflow.md) | Troubleshoot failing agentic workflows |
 
 ### Using Prompts with Your AI Agent
 
diff --git a/agency/plugins/ado-aw/.claude-plugin/plugin.json b/agency/plugins/ado-aw/.claude-plugin/plugin.json
new file mode 100644
index 00000000..9d75c649
--- /dev/null
+++ b/agency/plugins/ado-aw/.claude-plugin/plugin.json
@@ -0,0 +1,23 @@
+{
+  "name": "ado-aw",
+  "version": "0.37.0",
+  "description": "Azure DevOps Agentic Workflows (ado-aw) — create, update, validate, operate, and debug AI-powered Azure DevOps agentic workflows: Markdown agent specs compiled into secure, network-isolated ADO pipelines.",
+  "author": {
+    "name": "GitHub Next",
+    "url": "https://github.com/githubnext/ado-aw"
+  },
+  "homepage": "https://github.com/githubnext/ado-aw",
+  "repository": "https://github.com/githubnext/ado-aw",
+  "license": "MIT",
+  "keywords": [
+    "azure-devops",
+    "ado",
+    "agentic",
+    "pipelines",
+    "ado-aw",
+    "safe-outputs",
+    "compiler",
+    "automation"
+  ],
+  "mcpServers": "./.mcp.json"
+}
diff --git a/agency/plugins/ado-aw/.mcp.json b/agency/plugins/ado-aw/.mcp.json
new file mode 100644
index 00000000..ef3ae5b1
--- /dev/null
+++ b/agency/plugins/ado-aw/.mcp.json
@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "ado-aw": {
+      "command": "ado-aw",
+      "type": "local",
+      "args": ["mcp-author"],
+      "tools": ["*"]
+    }
+  }
+}
diff --git a/agency/plugins/ado-aw/README.md b/agency/plugins/ado-aw/README.md
new file mode 100644
index 00000000..240486ab
--- /dev/null
+++ b/agency/plugins/ado-aw/README.md
@@ -0,0 +1,80 @@
+# ado-aw — Azure DevOps Agentic Workflows
+
+Author, compile, validate, operate, and debug **ado-aw** agentic workflows for
+Azure DevOps from your agent (Claude Code or Copilot CLI). Each agentic workflow
+compiles to a secure, multi-stage Azure DevOps pipeline.
+
+[ado-aw](https://github.com/githubnext/ado-aw) compiles human-friendly Markdown
+agent specs (Markdown body + YAML front matter) into secure, multi-stage Azure
+DevOps pipelines that run AI agents in network-isolated sandboxes. Every compiled
+pipeline runs three sequential jobs:
+
+1. **Agent** — runs the AI agent in an AWF network-isolated sandbox with a
+   read-only ADO token, producing *safe-output proposals* (not direct actions).
+2. **Detection** — a separate agent inspects the proposals for prompt injection,
+   secret leaks, and other threats.
+3. **SafeOutputs** — a non-agent executor applies approved safe outputs with a
+   write-capable token the agent never sees.
+
+## What this plugin provides
+
+- A dispatcher **agent** (`agents/ado-aw.md`) that routes authoring/ops requests.
+- A read-only **MCP server** wired via `.mcp.json` to `ado-aw mcp-author`
+  (inspect / graph / lint / whatif / trace / audit / catalog).
+- Six **skills**:
+  - `create-workflow` — author a new pipeline from scratch (compile + lint).
+  - `update-workflow` — read-then-update an existing pipeline with validation.
+  - `debug-workflow` — diagnose a failing pipeline (`trace_failure`, `audit_build`).
+  - `compile-and-validate` — `ado-aw compile` + `lint_workflow` + IR/graph inspection.
+  - `manage-lifecycle` — enable / disable / remove / run / list / status / secrets.
+  - `audit-build` — download and analyze a finished build's artifacts.
+
+## Installing
+
+This repository is itself an installable plugin marketplace — the root
+`.claude-plugin/marketplace.json` (Claude) and `.github/plugin/marketplace.json`
+(Copilot) catalogs register the `ado-aw` plugin (whose files live under
+`agency/plugins/ado-aw/`). From your agent:
+
+```text
+/plugin marketplace add githubnext/ado-aw
+/plugin install ado-aw@ado-aw
+```
+
+`ado-aw init --agency` scaffolds the same catalogs + plugin into a consumer repo,
+so that repo becomes registerable the same way.
+
+## Prerequisites
+
+The `ado-aw` compiler must be on `PATH`. Run the bundled doctor check first:
+
+```bash
+./scripts/doctor.sh     # macOS / Linux
+```
+```powershell
+.\scripts\doctor.ps1    # Windows
+```
+
+If `ado-aw` is missing, install it from the
+[releases page](https://github.com/githubnext/ado-aw/releases/latest). ADO-facing
+skills (`debug-workflow`, `audit-build`, `manage-lifecycle`) additionally rely on
+`gh`/`az` auth or an ADO PAT, resolved through ado-aw's normal auth path.
+
+## Security model
+
+This plugin adds **no new write paths**. It only adds a read-only MCP server plus
+`ado-aw` CLI invocations the user could already run. All mutation stays inside
+ado-aw's three-stage safe-output model. No remote MCP endpoints are introduced
+and no secrets are stored in the plugin tree.
+
+## Source of truth & versioning
+
+The canonical plugin lives in the ado-aw repository at
+[`agency/plugins/ado-aw`](https://github.com/githubnext/ado-aw/tree/main/agency/plugins/ado-aw)
+and is **version-locked to the compiler**: release automation bumps the plugin
+version and the pinned prompt URLs in lock-step with each ado-aw release. The
+Agency marketplace lists it via an external `source` pointer (`agency.json`).
+
+## License
+
+MIT — see the [ado-aw repository](https://github.com/githubnext/ado-aw).
diff --git a/agency/plugins/ado-aw/agency.json b/agency/plugins/ado-aw/agency.json
new file mode 100644
index 00000000..1c06c642
--- /dev/null
+++ b/agency/plugins/ado-aw/agency.json
@@ -0,0 +1,26 @@
+{
+  "$schema": "https://github.com/agency-microsoft/.github-private/agency.schema.json",
+  "engines": ["claude", "copilot"],
+  "category": "developer-tools",
+  "platforms": ["windows", "macos", "linux"],
+  "governance": {
+    "layer": 4,
+    "certification": "draft",
+    "organization": "github-next"
+  },
+  "source": {
+    "source": "github",
+    "url": "https://github.com/githubnext/ado-aw.git",
+    "path": "agency/plugins/ado-aw"
+  },
+  "permissions": {
+    "mcpServers": ["ado-aw"],
+    "tools": ["*"],
+    "fileAccess": "read-write"
+  },
+  "requirements": {
+    "ado-aw": {
+      "description": "The ado-aw compiler binary must be on PATH. The local mcp-author stdio server (read-only inspect/graph/lint/whatif/trace/audit/catalog) is launched as `ado-aw mcp-author`. ADO-facing tools (trace, audit) reuse ado-aw's normal auth resolution (explicit PAT, environment, or Azure CLI)."
+    }
+  }
+}
diff --git a/agency/plugins/ado-aw/agents/ado-aw.md b/agency/plugins/ado-aw/agents/ado-aw.md
new file mode 100644
index 00000000..501e232d
--- /dev/null
+++ b/agency/plugins/ado-aw/agents/ado-aw.md
@@ -0,0 +1,85 @@
+---
+name: ado-aw
+description: Create, update, validate, operate, and debug Azure DevOps agentic workflows using ado-aw. Use when the user wants to author, modify, compile, run, or troubleshoot AI-powered Azure DevOps agentic workflows written as Markdown agent files (each compiles to a secure, network-isolated ADO pipeline).
+---
+
+# Azure DevOps Agentic Workflows Agent
+
+This agent helps you author and manage Azure DevOps agentic workflows using
+**ado-aw**.
+
+ado-aw compiles human-friendly Markdown files with YAML front matter into
+secure, multi-stage Azure DevOps pipelines that run AI agents in
+network-isolated sandboxes (Agent → Threat Detection → Safe-Output Execution).
+
+## Prerequisites
+
+Before doing anything else, make sure the ado-aw compiler is available — run the
+**doctor** check (`scripts/doctor.sh` on macOS/Linux, `scripts/doctor.ps1` on
+Windows). It verifies `ado-aw` is on `PATH` and that `gh`/`az` auth is present
+where ADO calls are needed. If `ado-aw` is missing, install it:
+
+```bash
+# Linux
+curl -fsSL https://github.com/githubnext/ado-aw/releases/latest/download/install-linux.sh | sh
+# macOS (Apple Silicon)
+curl -fsSL https://github.com/githubnext/ado-aw/releases/latest/download/install-macos.sh | sh
+# Windows (PowerShell)
+powershell -ExecutionPolicy Bypass -NoProfile -Command "iwr https://github.com/githubnext/ado-aw/releases/latest/download/install-windows.ps1 -UseBasicParsing | iex"
+```
+
+Verify: `ado-aw --version`
+
+## Read-only MCP tools
+
+This plugin wires the local, read-only **`ado-aw mcp-author`** server (see
+`.mcp.json`). Prefer these tools over shelling out when you only need to inspect:
+
+- `inspect_workflow`, `graph_summary`, `graph_dump`, `step_dependencies`, `step_outputs`
+- `lint_workflow`, `whatif`, `catalog`
+- `trace_failure`, `audit_build` (ADO read auth)
+
+Mutating actions are **not** in the MCP server. Use the `ado-aw` CLI (via Bash)
+for `compile`, `enable`, `disable`, `remove`, `run`, `list`, `status`,
+`secrets`, `init` — gated by the guardrails below.
+
+## Capability routing
+
+Route the user's request to the matching skill:
+
+| The user wants to… | Skill |
+| --- | --- |
+| Create a new workflow from scratch | `create-workflow` |
+| Change an existing workflow | `update-workflow` |
+| Understand why a pipeline failed | `debug-workflow` |
+| Compile / confirm a workflow is valid | `compile-and-validate` |
+| Enable / disable / run / check status | `manage-lifecycle` |
+| Analyze a finished build | `audit-build` |
+
+## Authoritative prompts (version-pinned)
+
+The create/update/debug skills load these compiler-version-pinned playbooks:
+
+- Create: https://raw.githubusercontent.com/githubnext/ado-aw/v0.37.0/prompts/create-ado-agentic-workflow.md <!-- x-release-please-version -->
+- Update: https://raw.githubusercontent.com/githubnext/ado-aw/v0.37.0/prompts/update-ado-agentic-workflow.md <!-- x-release-please-version -->
+- Debug: https://raw.githubusercontent.com/githubnext/ado-aw/v0.37.0/prompts/debug-ado-agentic-workflow.md <!-- x-release-please-version -->
+- Full reference: https://raw.githubusercontent.com/githubnext/ado-aw/v0.37.0/AGENTS.md <!-- x-release-please-version -->
+
+## Guardrails
+
+- Never bypass ado-aw's three-stage safe-output model or fabricate write tokens.
+  The agent never has direct write access — all mutations go through safe outputs.
+- Always `ado-aw compile` **and** `lint_workflow` before declaring a workflow done.
+- Agent files must be recompiled with `ado-aw compile` after YAML front-matter
+  changes; Markdown-body-only changes do not require recompilation.
+- Never push directly to a protected branch — use ado-aw's own flow.
+- Surface ADO auth/permission errors verbatim with the doc pointer
+  (`docs/safe-output-permissions.md`).
+
+## Quick reference
+
+```bash
+ado-aw compile <agent-file.md>   # compile one agent file to pipeline YAML
+ado-aw compile                   # recompile all detected pipelines
+ado-aw check <pipeline.lock.yml> # verify a pipeline matches its source
+```
diff --git a/agency/plugins/ado-aw/scripts/doctor.ps1 b/agency/plugins/ado-aw/scripts/doctor.ps1
new file mode 100644
index 00000000..11c02184
--- /dev/null
+++ b/agency/plugins/ado-aw/scripts/doctor.ps1
@@ -0,0 +1,56 @@
+#!/usr/bin/env pwsh
+# doctor.ps1 - verify prerequisites for the ado-aw Agency plugin.
+#
+# Checks:
+#   1. `ado-aw` is on PATH (else point to the install docs).
+#   2. `gh` and `az` availability + auth (advisory - only needed for ADO-facing
+#      skills: debug-workflow, audit-build, manage-lifecycle).
+#
+# Exit code is non-zero only when a hard requirement (ado-aw) is missing.
+$ErrorActionPreference = 'Stop'
+
+function Write-Ok($m)   { Write-Host "  [ok]   $m" -ForegroundColor Green }
+function Write-Warn($m) { Write-Host "  [warn] $m" -ForegroundColor Yellow }
+function Write-Err($m)  { Write-Host "  [fail] $m" -ForegroundColor Red }
+
+$hardFail = $false
+
+Write-Host "ado-aw plugin doctor"
+Write-Host ""
+
+# 1. ado-aw (hard requirement)
+if (Get-Command ado-aw -ErrorAction SilentlyContinue) {
+    $version = (ado-aw --version 2>$null)
+    if (-not $version) { $version = 'unknown' }
+    Write-Ok "ado-aw found: $version"
+} else {
+    Write-Err "ado-aw not found on PATH"
+    Write-Host '    Install it (PowerShell):'
+    Write-Host '      powershell -ExecutionPolicy Bypass -NoProfile -Command "iwr https://github.com/githubnext/ado-aw/releases/latest/download/install-windows.ps1 -UseBasicParsing | iex"'
+    Write-Host '    Docs: https://github.com/githubnext/ado-aw/releases/latest'
+    $hardFail = $true
+}
+
+# 2. ADO auth helpers (advisory)
+if (Get-Command gh -ErrorAction SilentlyContinue) {
+    gh auth status *> $null
+    if ($LASTEXITCODE -eq 0) { Write-Ok "gh authenticated" }
+    else { Write-Warn "gh found but not authenticated (run 'gh auth login' for GitHub-backed flows)" }
+} else {
+    Write-Warn "gh not found (optional; needed for some GitHub-backed flows)"
+}
+
+if (Get-Command az -ErrorAction SilentlyContinue) {
+    az account show *> $null
+    if ($LASTEXITCODE -eq 0) { Write-Ok "az authenticated" }
+    else { Write-Warn "az found but not logged in (run 'az login' for ADO trace/audit/lifecycle skills)" }
+} else {
+    Write-Warn "az not found (optional; ADO-facing skills can also use an explicit PAT)"
+}
+
+Write-Host ""
+if ($hardFail) {
+    Write-Err "Missing required tool(s). Install ado-aw before using this plugin."
+    exit 1
+}
+Write-Ok "All required prerequisites satisfied."
diff --git a/agency/plugins/ado-aw/scripts/doctor.sh b/agency/plugins/ado-aw/scripts/doctor.sh
new file mode 100644
index 00000000..efd72f00
--- /dev/null
+++ b/agency/plugins/ado-aw/scripts/doctor.sh
@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# doctor.sh - verify prerequisites for the ado-aw Agency plugin.
+#
+# Checks:
+#   1. `ado-aw` is on PATH (else point to the install docs).
+#   2. `gh` and `az` availability + auth (advisory - only needed for ADO-facing
+#      skills: debug-workflow, audit-build, manage-lifecycle).
+#
+# Exit code is non-zero only when a hard requirement (ado-aw) is missing.
+set -euo pipefail
+
+ok()   { printf '  \033[32m✓\033[0m %s\n' "$1"; }
+warn() { printf '  \033[33m!\033[0m %s\n' "$1"; }
+err()  { printf '  \033[31m✗\033[0m %s\n' "$1"; }
+
+hard_fail=0
+
+echo "ado-aw plugin doctor"
+echo
+
+# 1. ado-aw (hard requirement)
+if command -v ado-aw >/dev/null 2>&1; then
+  version="$(ado-aw --version 2>/dev/null || echo 'unknown')"
+  ok "ado-aw found: ${version}"
+else
+  err "ado-aw not found on PATH"
+  echo "    Install it:"
+  echo "      Linux:   curl -fsSL https://github.com/githubnext/ado-aw/releases/latest/download/install-linux.sh | sh"
+  echo "      macOS:   curl -fsSL https://github.com/githubnext/ado-aw/releases/latest/download/install-macos.sh | sh"
+  echo "    Docs: https://github.com/githubnext/ado-aw/releases/latest"
+  hard_fail=1
+fi
+
+# 2. ADO auth helpers (advisory)
+if command -v gh >/dev/null 2>&1; then
+  if gh auth status >/dev/null 2>&1; then
+    ok "gh authenticated"
+  else
+    warn "gh found but not authenticated (run 'gh auth login' for GitHub-backed flows)"
+  fi
+else
+  warn "gh not found (optional; needed for some GitHub-backed flows)"
+fi
+
+if command -v az >/dev/null 2>&1; then
+  if az account show >/dev/null 2>&1; then
+    ok "az authenticated"
+  else
+    warn "az found but not logged in (run 'az login' for ADO trace/audit/lifecycle skills)"
+  fi
+else
+  warn "az not found (optional; ADO-facing skills can also use an explicit PAT)"
+fi
+
+echo
+if [ "${hard_fail}" -ne 0 ]; then
+  err "Missing required tool(s). Install ado-aw before using this plugin."
+  exit 1
+fi
+ok "All required prerequisites satisfied."
diff --git a/agency/plugins/ado-aw/skills/audit-build/SKILL.md b/agency/plugins/ado-aw/skills/audit-build/SKILL.md
new file mode 100644
index 00000000..0a69c894
--- /dev/null
+++ b/agency/plugins/ado-aw/skills/audit-build/SKILL.md
@@ -0,0 +1,31 @@
+---
+name: audit-build
+description: Download and analyze a finished ado-aw pipeline build. Use when the user wants a security/behavior report on a completed build — firewall/network activity, MCP tool calls, safe-output proposals, detection findings, token usage, or policy signals.
+allowed-tools: Bash, Read, Glob, Grep, mcp__ado-aw__audit_build, mcp__ado-aw__trace_failure
+---
+
+# Audit a build
+
+Analyze a **finished** ado-aw pipeline build and render its findings.
+
+1. Confirm the `ado-aw` compiler is installed (`ado-aw --version`) and that ADO
+   read auth is available (`gh`/`az` or a PAT).
+
+2. Run the audit. Accepts a bare build id or a full Azure DevOps build URL:
+   - MCP: `audit_build` — same shape as `ado-aw audit --json`; returns the
+     structured `AuditData` report.
+   - CLI: `ado-aw audit <build-id-or-url>` (add `--json` for machine output).
+   - `trace_failure` — when the build failed, correlate the failed-job chain with
+     the local IR graph.
+
+3. The report's analyzers cover: detection-stage artifacts, AWF firewall/network
+   logs, build timeline / job-level data, MCP tool calls, missing-tool /
+   missing-data / noop safe outputs, OTel agent stats (token usage, duration,
+   turns), policy findings (safe-output integrity, prompt-injection signals), and
+   safe-output NDJSON.
+
+4. Summarize findings by severity and call out anything in the firewall, policy,
+   or safe-output sections explicitly. The audit cache is keyed on build id;
+   pass `--no-cache` (CLI) / `no_cache: true` (MCP) to force a fresh download.
+
+The user's request: $ARGUMENTS
diff --git a/agency/plugins/ado-aw/skills/compile-and-validate/SKILL.md b/agency/plugins/ado-aw/skills/compile-and-validate/SKILL.md
new file mode 100644
index 00000000..cc4d4d61
--- /dev/null
+++ b/agency/plugins/ado-aw/skills/compile-and-validate/SKILL.md
@@ -0,0 +1,31 @@
+---
+name: compile-and-validate
+description: Compile an ado-aw agent file to Azure DevOps pipeline YAML and validate it. Use when the user asks to compile a workflow, check whether it is valid, verify a pipeline matches its source, or understand the compiled IR / dependency graph.
+allowed-tools: Bash, Read, Glob, Grep, mcp__ado-aw__lint_workflow, mcp__ado-aw__inspect_workflow, mcp__ado-aw__graph_summary, mcp__ado-aw__graph_dump, mcp__ado-aw__step_dependencies, mcp__ado-aw__step_outputs
+---
+
+# Compile and validate
+
+Compile and validate an ado-aw agentic workflow. This skill is CLI- and
+MCP-driven; it does not fetch a remote playbook.
+
+1. Confirm the `ado-aw` compiler is installed (`ado-aw --version`).
+
+2. **Compile** with the CLI (mutates the `.lock.yml` on disk):
+   - `ado-aw compile <agent-file.md>` — compile one file.
+   - `ado-aw compile` — auto-discover and recompile all detected pipelines.
+   - `ado-aw check <pipeline.lock.yml>` — verify a compiled pipeline still
+     matches its source Markdown (good for CI parity checks).
+
+3. **Validate and explain** with the read-only MCP tools (no mutation):
+   - `lint_workflow` — structural lint checks; resolve every finding.
+   - `inspect_workflow` — the public `PipelineSummary` (schema_version = 1).
+   - `graph_summary` / `graph_dump` — the resolved dependency graph
+     (text or Graphviz DOT).
+   - `step_dependencies` — upstream/downstream traversal for a step or job id.
+   - `step_outputs` — declared outputs and their consumers.
+
+4. Treat the workflow as "valid" only when `compile` succeeds **and**
+   `lint_workflow` is clean. Recompile after any YAML front-matter change.
+
+The user's request: $ARGUMENTS
diff --git a/agency/plugins/ado-aw/skills/create-workflow/SKILL.md b/agency/plugins/ado-aw/skills/create-workflow/SKILL.md
new file mode 100644
index 00000000..b7b36e58
--- /dev/null
+++ b/agency/plugins/ado-aw/skills/create-workflow/SKILL.md
@@ -0,0 +1,28 @@
+---
+name: create-workflow
+description: Create a new ado-aw agentic Azure DevOps pipeline from scratch. Use when the user wants to author a brand-new AI-powered ADO pipeline as a Markdown agent file. Ends with a clean compile + lint.
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, mcp__ado-aw__catalog, mcp__ado-aw__lint_workflow, mcp__ado-aw__inspect_workflow, mcp__ado-aw__graph_summary
+---
+
+# Create an ado-aw workflow
+
+You are creating a **new** ado-aw agentic workflow.
+
+1. Confirm the `ado-aw` compiler is installed (`ado-aw --version`). If not,
+   install it using the platform installer scripts from the ado-aw releases page
+   (see the plugin README / `scripts/doctor.*`).
+
+2. Load the **entire** content of the authoritative, version-pinned playbook and
+   follow its instructions precisely:
+
+   https://raw.githubusercontent.com/githubnext/ado-aw/v0.37.0/prompts/create-ado-agentic-workflow.md <!-- x-release-please-version -->
+
+3. While authoring, use the read-only MCP tools to stay grounded:
+   - `catalog` — discover available safe-outputs, runtimes, tools, engines, models.
+   - `lint_workflow` — structural lint checks on the draft.
+   - `inspect_workflow` / `graph_summary` — confirm the compiled IR/graph shape.
+
+4. **Finish only when** `ado-aw compile <file>.md` succeeds and `lint_workflow`
+   is clean. Recompile after any YAML front-matter change.
+
+The user's request: $ARGUMENTS
diff --git a/agency/plugins/ado-aw/skills/debug-workflow/SKILL.md b/agency/plugins/ado-aw/skills/debug-workflow/SKILL.md
new file mode 100644
index 00000000..c70fbda4
--- /dev/null
+++ b/agency/plugins/ado-aw/skills/debug-workflow/SKILL.md
@@ -0,0 +1,33 @@
+---
+name: debug-workflow
+description: Diagnose a failing ado-aw agentic Azure DevOps pipeline. Use when the user reports a pipeline failing, an agent unable to reach an MCP/network host, safe outputs not being applied, or wants to understand why a build behaved a certain way.
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, mcp__ado-aw__trace_failure, mcp__ado-aw__audit_build, mcp__ado-aw__whatif, mcp__ado-aw__inspect_workflow, mcp__ado-aw__graph_summary, mcp__ado-aw__lint_workflow
+---
+
+# Debug an ado-aw workflow
+
+You are troubleshooting a **failing** ado-aw agentic workflow.
+
+1. Confirm the `ado-aw` compiler is installed (`ado-aw --version`).
+
+2. Gather evidence before theorizing:
+   - `trace_failure` — trace the build's failed-job chain using audit data plus
+     the local IR graph (pass the build id or full ADO build URL).
+   - `audit_build` — download and analyze the build's artifacts (firewall/network
+     logs, MCP tool calls, safe-output NDJSON, detection findings, policy signals).
+   - `whatif` — classify which downstream jobs are skipped when a given step/job
+     fails, to confirm the blast radius.
+
+3. Load the **entire** content of the authoritative, version-pinned playbook and
+   follow its instructions precisely:
+
+   https://raw.githubusercontent.com/githubnext/ado-aw/v0.37.0/prompts/debug-ado-agentic-workflow.md <!-- x-release-please-version -->
+
+4. For Stage 3 (SafeOutputs) 401/403 failures, consult
+   `docs/safe-output-permissions.md` and surface the auth/permission error
+   verbatim with the doc pointer.
+
+5. If a fix requires a source change, validate it with `ado-aw compile` +
+   `lint_workflow` before proposing it.
+
+The user's request: $ARGUMENTS
diff --git a/agency/plugins/ado-aw/skills/manage-lifecycle/SKILL.md b/agency/plugins/ado-aw/skills/manage-lifecycle/SKILL.md
new file mode 100644
index 00000000..8a862816
--- /dev/null
+++ b/agency/plugins/ado-aw/skills/manage-lifecycle/SKILL.md
@@ -0,0 +1,36 @@
+---
+name: manage-lifecycle
+description: Operate compiled ado-aw pipelines in Azure DevOps. Use when the user wants to register/enable/disable/remove build definitions, queue runs, set pipeline secrets, or report pipeline status.
+allowed-tools: Bash, Read, Glob, Grep
+---
+
+# Manage pipeline lifecycle
+
+Operate compiled ado-aw pipelines against Azure DevOps. These are **mutating CLI
+actions** — they are deliberately not exposed via the read-only MCP server.
+
+1. Confirm the `ado-aw` compiler is installed (`ado-aw --version`) and that ADO
+   auth is available (`gh`/`az` login or an ADO PAT, per ado-aw's auth resolution).
+
+2. Use the `ado-aw` CLI (via Bash):
+   - `ado-aw enable` — register ADO build definitions for compiled pipelines and
+     ensure they are enabled.
+   - `ado-aw disable` — set matched definitions to disabled (default) or paused.
+   - `ado-aw remove` — delete matched build definitions (honors `--yes` / tty prompt).
+   - `ado-aw run` — queue builds for matched definitions, optionally polling to
+     completion.
+   - `ado-aw list` — render matched definitions with their latest-run state
+     (text or JSON).
+   - `ado-aw status` — denser per-pipeline status block.
+   - `ado-aw secrets set/list/delete` — manage pipeline variables. `list` never
+     prints values; never echo secret values into the conversation.
+
+## Guardrails
+
+- These commands change real ADO state. Confirm scope (`--source` / `--all-repos`
+  and the matched set via `ado-aw list`) **before** running enable/disable/remove/run.
+- Never fabricate or hardcode a PAT; rely on ado-aw's auth resolution.
+- Surface ADO auth/permission errors verbatim; for Stage 3 401/403 see
+  `docs/safe-output-permissions.md`.
+
+The user's request: $ARGUMENTS
diff --git a/agency/plugins/ado-aw/skills/update-workflow/SKILL.md b/agency/plugins/ado-aw/skills/update-workflow/SKILL.md
new file mode 100644
index 00000000..273ecf25
--- /dev/null
+++ b/agency/plugins/ado-aw/skills/update-workflow/SKILL.md
@@ -0,0 +1,29 @@
+---
+name: update-workflow
+description: Update an existing ado-aw agentic Azure DevOps pipeline. Use when the user wants to modify an existing Markdown agent file — change schedule, add a tool/MCP, add a safe output, adjust runtimes, etc. Read-then-update with validation.
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, mcp__ado-aw__inspect_workflow, mcp__ado-aw__graph_summary, mcp__ado-aw__step_dependencies, mcp__ado-aw__whatif, mcp__ado-aw__lint_workflow, mcp__ado-aw__catalog
+---
+
+# Update an ado-aw workflow
+
+You are modifying an **existing** ado-aw agentic workflow.
+
+1. Confirm the `ado-aw` compiler is installed (`ado-aw --version`).
+
+2. **Read the existing agent file first**, and inspect its current shape before
+   changing anything: `inspect_workflow`, `graph_summary`, `step_dependencies`,
+   and `whatif` (to understand downstream impact of a change).
+
+3. Load the **entire** content of the authoritative, version-pinned playbook and
+   follow its instructions precisely:
+
+   https://raw.githubusercontent.com/githubnext/ado-aw/v0.37.0/prompts/update-ado-agentic-workflow.md <!-- x-release-please-version -->
+
+4. Use `catalog` to confirm any newly referenced safe-output / runtime / tool /
+   model identifiers are valid.
+
+5. **Recompile** with `ado-aw compile` after editing YAML front matter, then run
+   `lint_workflow` until clean. Markdown-body-only changes do not require
+   recompilation.
+
+The user's request: $ARGUMENTS
diff --git a/docs/cli.md b/docs/cli.md
index 4ad83f1a..beea16b6 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -9,7 +9,7 @@ Global flags (apply to all subcommands): `--verbose, -v` (enable info-level logg
 - `init` - Initialize a repository for AI-first agentic pipeline authoring
   - `--path <path>` - Target directory (defaults to current directory)
   - `--force` - Bypass the GitHub-remote guard (use when running inside a GitHub-hosted repository like `githubnext/ado-aw` itself)
-  - `--agency` - **Additive.** Also generate an Agency / [Claude Code plugin](https://code.claude.com/docs/en/plugins-reference) under `.github/ado-aw` (in addition to the standard Copilot agent file). Emits `.github/ado-aw/.claude-plugin/plugin.json` (manifest) + `marketplace.json`, an `agents/ado-aw.md` dispatcher subagent, and `commands/{create,update,debug}-ado-agentic-workflow.md` slash commands.
+  - `--agency` - **Additive.** Also generate an Agency / [Claude Code plugin](https://code.claude.com/docs/en/plugins-reference) and the marketplace catalogs that make the repo directly installable (in addition to the standard Copilot agent file). Writes the plugin under `agency/plugins/ado-aw` (mirroring how it is checked in to ado-aw itself) plus **repo-root** marketplace catalogs `.claude-plugin/marketplace.json` (Claude) and `.github/plugin/marketplace.json` (Copilot) that list the plugin via `source: "./agency/plugins/ado-aw"`. After scaffolding, register with `/plugin marketplace add <repo>` then `/plugin install ado-aw@ado-aw`. The plugin tree is a verbatim copy of the canonical in-repo plugin at [`agency/plugins/ado-aw/`](../agency/plugins/ado-aw): `.claude-plugin/plugin.json`, `.mcp.json` (wires the read-only `ado-aw mcp-author` server), `agency.json` (marketplace governance + external `source` pointer), `README.md`, an `agents/ado-aw.md` dispatcher subagent, six `skills/<name>/SKILL.md` playbooks (`create-workflow`, `update-workflow`, `debug-workflow`, `compile-and-validate`, `manage-lifecycle`, `audit-build`), and `scripts/doctor.{sh,ps1}` prerequisite checks. The canonical plugin + catalogs are version-locked to the compiler (release-please bumps the plugin/catalog versions + pinned prompt URLs in lock-step).
   - Creates `.github/agents/ado-aw.agent.md` — a Copilot dispatcher agent that routes to specialized prompts for creating, updating, and debugging agentic pipelines
   - The agent auto-downloads the ado-aw compiler and handles the full lifecycle (create → compile → check)
 - `compile [<path>]` - Compile a markdown file to Azure DevOps pipeline YAML. If no path is given, auto-discovers and recompiles all detected agentic pipelines in the current directory.
diff --git a/release-please-config.json b/release-please-config.json
index 23a61c18..a8a30b10 100644
--- a/release-please-config.json
+++ b/release-please-config.json
@@ -4,7 +4,38 @@
   "packages": {
     ".": {
       "release-type": "rust",
-      "bump-minor-pre-major": true
+      "bump-minor-pre-major": true,
+      "extra-files": [
+        {
+          "type": "json",
+          "path": "agency/plugins/ado-aw/.claude-plugin/plugin.json",
+          "jsonpath": "$.version"
+        },
+        {
+          "type": "json",
+          "path": ".claude-plugin/marketplace.json",
+          "jsonpath": "$.metadata.version"
+        },
+        {
+          "type": "json",
+          "path": ".claude-plugin/marketplace.json",
+          "jsonpath": "$.plugins[0].version"
+        },
+        {
+          "type": "json",
+          "path": ".github/plugin/marketplace.json",
+          "jsonpath": "$.metadata.version"
+        },
+        {
+          "type": "json",
+          "path": ".github/plugin/marketplace.json",
+          "jsonpath": "$.plugins[0].version"
+        },
+        "agency/plugins/ado-aw/agents/ado-aw.md",
+        "agency/plugins/ado-aw/skills/create-workflow/SKILL.md",
+        "agency/plugins/ado-aw/skills/update-workflow/SKILL.md",
+        "agency/plugins/ado-aw/skills/debug-workflow/SKILL.md"
+      ]
     }
   }
 }
diff --git a/src/data/agency-plugin/.claude-plugin/marketplace.json b/src/data/agency-plugin/.claude-plugin/marketplace.json
deleted file mode 100644
index 616c1331..00000000
--- a/src/data/agency-plugin/.claude-plugin/marketplace.json
+++ /dev/null
@@ -1,18 +0,0 @@
-{
-  "name": "ado-aw",
-  "owner": {
-    "name": "githubnext",
-    "url": "https://github.com/githubnext/ado-aw"
-  },
-  "metadata": {
-    "description": "Azure DevOps Agentic Pipelines (ado-aw) plugin marketplace",
-    "version": "{{ compiler_version }}"
-  },
-  "plugins": [
-    {
-      "name": "ado-aw",
-      "source": "./",
-      "description": "Create, update, and debug Azure DevOps agentic pipelines with ado-aw"
-    }
-  ]
-}
diff --git a/src/data/agency-plugin/.claude-plugin/plugin.json b/src/data/agency-plugin/.claude-plugin/plugin.json
deleted file mode 100644
index c18e6e43..00000000
--- a/src/data/agency-plugin/.claude-plugin/plugin.json
+++ /dev/null
@@ -1,19 +0,0 @@
-{
-  "name": "ado-aw",
-  "version": "{{ compiler_version }}",
-  "description": "Azure DevOps Agentic Pipelines (ado-aw) - Create, update, and debug AI-powered ADO pipelines",
-  "author": {
-    "name": "githubnext",
-    "url": "https://github.com/githubnext/ado-aw"
-  },
-  "homepage": "https://github.com/githubnext/ado-aw",
-  "repository": "https://github.com/githubnext/ado-aw",
-  "license": "MIT",
-  "keywords": [
-    "azure-devops",
-    "ado",
-    "agentic",
-    "pipelines",
-    "ado-aw"
-  ]
-}
diff --git a/src/data/agency-plugin/agents/ado-aw.md b/src/data/agency-plugin/agents/ado-aw.md
deleted file mode 100644
index 979fb250..00000000
--- a/src/data/agency-plugin/agents/ado-aw.md
+++ /dev/null
@@ -1,107 +0,0 @@
----
-name: ado-aw
-description: Create, update, and debug Azure DevOps agentic pipelines using ado-aw. Use when the user wants to author, modify, or troubleshoot AI-powered Azure DevOps pipelines written as markdown agent files.
----
-
-# ADO Agentic Pipelines Agent
-
-This agent helps you create and manage Azure DevOps agentic pipelines using **ado-aw**.
-
-ado-aw compiles human-friendly markdown files with YAML front matter into secure, multi-stage Azure DevOps pipelines that run AI agents in network-isolated sandboxes.
-
-## Setup
-
-Before creating or compiling workflows, ensure the ado-aw compiler is available. Use the first-time installer for your platform:
-
-```bash
-# Linux
-curl -fsSL https://github.com/githubnext/ado-aw/releases/latest/download/install-linux.sh | sh
-
-# macOS (Apple Silicon)
-curl -fsSL https://github.com/githubnext/ado-aw/releases/latest/download/install-macos.sh | sh
-
-# Windows (PowerShell)
-powershell -ExecutionPolicy Bypass -NoProfile -Command "iwr https://github.com/githubnext/ado-aw/releases/latest/download/install-windows.ps1 -UseBasicParsing | iex"
-```
-
-These scripts validate release checksums, install `ado-aw`, and update PATH when needed.
-
-Verify: `ado-aw --version`
-
-## What This Agent Does
-
-This is a **dispatcher agent** that routes your request to the appropriate specialized prompt. The matching slash commands are also available:
-
-- **Creating new agentic pipelines** → `/create-ado-agentic-workflow`
-- **Updating existing pipelines** → `/update-ado-agentic-workflow`
-- **Debugging failing pipelines** → `/debug-ado-agentic-workflow`
-
-## Available Prompts
-
-### Create New Agentic Pipeline
-**Load when**: User wants to create a new agentic pipeline from scratch
-
-**Prompt file**: https://raw.githubusercontent.com/githubnext/ado-aw/v{{ compiler_version }}/prompts/create-ado-agentic-workflow.md
-
-**Use cases**:
-- "Create an agentic pipeline that reviews PRs weekly"
-- "I need a pipeline that triages work items daily"
-- "Design a scheduled dependency updater"
-
-### Update Existing Pipeline
-**Load when**: User wants to modify an existing agent workflow file
-
-**Prompt file**: https://raw.githubusercontent.com/githubnext/ado-aw/v{{ compiler_version }}/prompts/update-ado-agentic-workflow.md
-
-**Use cases**:
-- "Add the Azure DevOps MCP to my pipeline"
-- "Change the schedule from daily to weekly"
-- "Add work item creation as a safe output"
-
-### Debug Failing Pipeline
-**Load when**: User needs to troubleshoot a failing agentic pipeline
-
-**Prompt file**: https://raw.githubusercontent.com/githubnext/ado-aw/v{{ compiler_version }}/prompts/debug-ado-agentic-workflow.md
-
-**Use cases**:
-- "Why is my agentic pipeline failing?"
-- "The agent can't reach the MCP server"
-- "Safe outputs aren't being processed"
-
-## Instructions
-
-When a user interacts with you:
-
-1. **Identify the task type** from the user's request
-2. **Load the appropriate prompt** from the URLs listed above
-3. **Follow the loaded prompt's instructions** exactly
-4. **If uncertain**, ask clarifying questions to determine the right prompt
-
-## Quick Reference
-
-```bash
-# Compile an agent file to pipeline YAML
-ado-aw compile <agent-file.md>
-
-# Recompile all detected pipelines
-ado-aw compile
-
-# Verify pipeline matches source
-ado-aw check <pipeline.lock.yml>
-```
-
-## Key Features
-
-- **Natural language pipelines**: Write in markdown with YAML frontmatter
-- **3-stage security**: Agent → Threat Analysis → Safe Output Execution
-- **Network isolation**: AWF (Agentic Workflow Firewall) with domain whitelisting
-- **MCP Gateway**: Tool routing for Azure DevOps, custom MCPs
-- **Safe outputs**: Controlled write operations (PRs, work items, wiki pages)
-- **Agent memory**: Persistent storage across pipeline runs
-
-## Important Notes
-
-- Agent files must be compiled with `ado-aw compile` after YAML frontmatter changes
-- Markdown body (agent instructions) changes do NOT require recompilation
-- The agent never has direct write access — all mutations go through safe outputs
-- Full reference: https://raw.githubusercontent.com/githubnext/ado-aw/v{{ compiler_version }}/AGENTS.md
diff --git a/src/data/agency-plugin/commands/create-ado-agentic-workflow.md b/src/data/agency-plugin/commands/create-ado-agentic-workflow.md
deleted file mode 100644
index 630d0409..00000000
--- a/src/data/agency-plugin/commands/create-ado-agentic-workflow.md
+++ /dev/null
@@ -1,14 +0,0 @@
----
-description: Create a new Azure DevOps agentic pipeline from scratch with ado-aw.
----
-
-You are creating a new **ado-aw** agentic pipeline. Make sure the `ado-aw`
-compiler is installed (`ado-aw --version`); if not, install it using the
-platform installer scripts from the ado-aw releases page.
-
-Load the **entire** content of the following prompt and follow its
-instructions precisely:
-
-https://raw.githubusercontent.com/githubnext/ado-aw/v{{ compiler_version }}/prompts/create-ado-agentic-workflow.md
-
-The user's request: $ARGUMENTS
diff --git a/src/data/agency-plugin/commands/debug-ado-agentic-workflow.md b/src/data/agency-plugin/commands/debug-ado-agentic-workflow.md
deleted file mode 100644
index d7f36c4f..00000000
--- a/src/data/agency-plugin/commands/debug-ado-agentic-workflow.md
+++ /dev/null
@@ -1,14 +0,0 @@
----
-description: Debug a failing Azure DevOps agentic pipeline authored with ado-aw.
----
-
-You are debugging a failing **ado-aw** agentic pipeline. Make sure the
-`ado-aw` compiler is installed (`ado-aw --version`); if not, install it using
-the platform installer scripts from the ado-aw releases page.
-
-Load the **entire** content of the following prompt and follow its
-instructions precisely:
-
-https://raw.githubusercontent.com/githubnext/ado-aw/v{{ compiler_version }}/prompts/debug-ado-agentic-workflow.md
-
-The user's request: $ARGUMENTS
diff --git a/src/data/agency-plugin/commands/update-ado-agentic-workflow.md b/src/data/agency-plugin/commands/update-ado-agentic-workflow.md
deleted file mode 100644
index 6e0fc4ea..00000000
--- a/src/data/agency-plugin/commands/update-ado-agentic-workflow.md
+++ /dev/null
@@ -1,15 +0,0 @@
----
-description: Update an existing Azure DevOps agentic pipeline authored with ado-aw.
----
-
-You are updating an existing **ado-aw** agentic pipeline. Make sure the
-`ado-aw` compiler is installed (`ado-aw --version`); if not, install it using
-the platform installer scripts from the ado-aw releases page.
-
-Load the **entire** content of the following prompt and follow its
-instructions precisely. Read the existing agent file before making any
-changes, and recompile with `ado-aw compile` after editing YAML front matter:
-
-https://raw.githubusercontent.com/githubnext/ado-aw/v{{ compiler_version }}/prompts/update-ado-agentic-workflow.md
-
-The user's request: $ARGUMENTS
diff --git a/src/data/init-agent.md b/src/data/init-agent.md
index e548070e..b39e6083 100644
--- a/src/data/init-agent.md
+++ b/src/data/init-agent.md
@@ -1,11 +1,11 @@
 ---
-description: Azure DevOps Agentic Pipelines (ado-aw) - Create, update, and debug AI-powered ADO pipelines
+description: Azure DevOps Agentic Workflows (ado-aw) - Create, update, and debug AI-powered Azure DevOps agentic workflows
 disable-model-invocation: true
 ---
 
-# ADO Agentic Pipelines Agent
+# Azure DevOps Agentic Workflows Agent
 
-This agent helps you create and manage Azure DevOps agentic pipelines using **ado-aw**.
+This agent helps you create and manage Azure DevOps agentic workflows using **ado-aw**.
 
 ado-aw compiles human-friendly markdown files with YAML front matter into secure, multi-stage Azure DevOps pipelines that run AI agents in network-isolated sandboxes.
 
@@ -37,39 +37,39 @@ Verify: `ado-aw --version`
 
 This is a **dispatcher agent** that routes your request to the appropriate specialized prompt:
 
-- **Creating new agentic pipelines** → Routes to the create prompt
-- **Updating existing pipelines** → Routes to the update prompt  
-- **Debugging failing pipelines** → Routes to the debug prompt
+- **Creating new agentic workflows** → Routes to the create prompt
+- **Updating existing workflows** → Routes to the update prompt  
+- **Debugging failing workflows** → Routes to the debug prompt
 
 ## Available Prompts
 
-### Create New Agentic Pipeline
-**Load when**: User wants to create a new agentic pipeline from scratch
+### Create New Agentic Workflow
+**Load when**: User wants to create a new agentic workflow from scratch
 
 **Prompt file**: https://raw.githubusercontent.com/githubnext/ado-aw/v{{ compiler_version }}/prompts/create-ado-agentic-workflow.md
 
 **Use cases**:
-- "Create an agentic pipeline that reviews PRs weekly"
-- "I need a pipeline that triages work items daily"
+- "Create an agentic workflow that reviews PRs weekly"
+- "I need a workflow that triages work items daily"
 - "Design a scheduled dependency updater"
 
-### Update Existing Pipeline
+### Update Existing Workflow
 **Load when**: User wants to modify an existing agent workflow file
 
 **Prompt file**: https://raw.githubusercontent.com/githubnext/ado-aw/v{{ compiler_version }}/prompts/update-ado-agentic-workflow.md
 
 **Use cases**:
-- "Add the Azure DevOps MCP to my pipeline"
+- "Add the Azure DevOps MCP to my workflow"
 - "Change the schedule from daily to weekly"
 - "Add work item creation as a safe output"
 
-### Debug Failing Pipeline
-**Load when**: User needs to troubleshoot a failing agentic pipeline
+### Debug Failing Workflow
+**Load when**: User needs to troubleshoot a failing agentic workflow
 
 **Prompt file**: https://raw.githubusercontent.com/githubnext/ado-aw/v{{ compiler_version }}/prompts/debug-ado-agentic-workflow.md
 
 **Use cases**:
-- "Why is my agentic pipeline failing?"
+- "Why is my agentic workflow failing?"
 - "The agent can't reach the MCP server"
 - "Safe outputs aren't being processed"
 
@@ -97,7 +97,7 @@ ado-aw check <pipeline.lock.yml>
 
 ## Key Features
 
-- **Natural language pipelines**: Write in markdown with YAML frontmatter
+- **Natural language workflows**: Write in markdown with YAML frontmatter
 - **3-stage security**: Agent → Threat Analysis → Safe Output Execution
 - **Network isolation**: AWF (Agentic Workflow Firewall) with domain whitelisting
 - **MCP Gateway**: Tool routing for Azure DevOps, custom MCPs
diff --git a/src/init.rs b/src/init.rs
index c9cdfe0e..23498396 100644
--- a/src/init.rs
+++ b/src/init.rs
@@ -8,44 +8,92 @@ const AGENT_DIR: &str = ".github/agents";
 const AGENT_FILENAME: &str = "ado-aw.agent.md";
 
 /// Root directory (relative to the target repo) for the generated Agency /
-/// Claude Code plugin. Placed under `.github/ado-aw` so it does not pollute
-/// the user's source tree like the conventional top-level plugin folder would.
-const AGENCY_PLUGIN_DIR: &str = ".github/ado-aw";
-
-/// Files that make up the Agency plugin, following the Claude Code plugin
-/// conventions (https://code.claude.com/docs/en/plugins-reference):
-///   - `.claude-plugin/plugin.json` — plugin manifest
-///   - `.claude-plugin/marketplace.json` — marketplace so the plugin is
-///     installable straight from this dir
-///   - `agents/ado-aw.md` — dispatcher subagent
-///   - `commands/*.md` — slash commands routing to prompts
+/// Claude Code plugin. Mirrors the canonical in-repo layout (`agency/plugins/
+/// ado-aw/`) so a scaffolded consumer repo matches how the plugin is checked in
+/// to ado-aw itself, keeping `--agency` output and the source of truth aligned.
+const AGENCY_PLUGIN_DIR: &str = "agency/plugins/ado-aw";
+
+/// Marketplace catalog files written at the **repo root** (not inside the plugin
+/// dir). These are what make the repository itself an installable marketplace:
+/// `/plugin marketplace add <repo>` reads the root `.claude-plugin/marketplace
+/// .json` (Claude) / `.github/plugin/marketplace.json` (Copilot), each of which
+/// lists the `ado-aw` plugin with `source: "./agency/plugins/ado-aw"`. Written
+/// verbatim from the canonical catalogs at the ado-aw repo root.
 ///
-/// Each entry is `(relative path within the plugin dir, embedded template)`.
-/// `{{ compiler_version }}` placeholders are substituted at write time.
+/// Each entry is `(path relative to the repo root, embedded file)`.
+const AGENCY_MARKETPLACE_FILES: &[(&str, &str)] = &[
+    (
+        ".claude-plugin/marketplace.json",
+        include_str!("../.claude-plugin/marketplace.json"),
+    ),
+    (
+        ".github/plugin/marketplace.json",
+        include_str!("../.github/plugin/marketplace.json"),
+    ),
+];
+
+/// Files that make up the Agency / Claude Code plugin. The canonical, live copy
+/// is checked in at `agency/plugins/ado-aw/` (the single source of truth, listed
+/// in the Agency marketplace via an external `source` pointer and version-locked
+/// to the compiler by release-please). `--agency` embeds that same tree and
+/// scaffolds it into a consumer repo, so the two stay byte-for-byte identical.
+///
+/// Each entry is `(relative path within the plugin dir, embedded file)`. The
+/// embedded files already carry the literal release version (release-please
+/// bumps the canonical files and `Cargo.toml` together), so they are written
+/// verbatim — no placeholder substitution.
 const AGENCY_PLUGIN_FILES: &[(&str, &str)] = &[
     (
         ".claude-plugin/plugin.json",
-        include_str!("data/agency-plugin/.claude-plugin/plugin.json"),
+        include_str!("../agency/plugins/ado-aw/.claude-plugin/plugin.json"),
     ),
     (
-        ".claude-plugin/marketplace.json",
-        include_str!("data/agency-plugin/.claude-plugin/marketplace.json"),
+        ".mcp.json",
+        include_str!("../agency/plugins/ado-aw/.mcp.json"),
+    ),
+    (
+        "agency.json",
+        include_str!("../agency/plugins/ado-aw/agency.json"),
+    ),
+    (
+        "README.md",
+        include_str!("../agency/plugins/ado-aw/README.md"),
     ),
     (
         "agents/ado-aw.md",
-        include_str!("data/agency-plugin/agents/ado-aw.md"),
+        include_str!("../agency/plugins/ado-aw/agents/ado-aw.md"),
+    ),
+    (
+        "skills/create-workflow/SKILL.md",
+        include_str!("../agency/plugins/ado-aw/skills/create-workflow/SKILL.md"),
+    ),
+    (
+        "skills/update-workflow/SKILL.md",
+        include_str!("../agency/plugins/ado-aw/skills/update-workflow/SKILL.md"),
     ),
     (
-        "commands/create-ado-agentic-workflow.md",
-        include_str!("data/agency-plugin/commands/create-ado-agentic-workflow.md"),
+        "skills/debug-workflow/SKILL.md",
+        include_str!("../agency/plugins/ado-aw/skills/debug-workflow/SKILL.md"),
     ),
     (
-        "commands/update-ado-agentic-workflow.md",
-        include_str!("data/agency-plugin/commands/update-ado-agentic-workflow.md"),
+        "skills/compile-and-validate/SKILL.md",
+        include_str!("../agency/plugins/ado-aw/skills/compile-and-validate/SKILL.md"),
     ),
     (
-        "commands/debug-ado-agentic-workflow.md",
-        include_str!("data/agency-plugin/commands/debug-ado-agentic-workflow.md"),
+        "skills/manage-lifecycle/SKILL.md",
+        include_str!("../agency/plugins/ado-aw/skills/manage-lifecycle/SKILL.md"),
+    ),
+    (
+        "skills/audit-build/SKILL.md",
+        include_str!("../agency/plugins/ado-aw/skills/audit-build/SKILL.md"),
+    ),
+    (
+        "scripts/doctor.sh",
+        include_str!("../agency/plugins/ado-aw/scripts/doctor.sh"),
+    ),
+    (
+        "scripts/doctor.ps1",
+        include_str!("../agency/plugins/ado-aw/scripts/doctor.ps1"),
     ),
 ];
 
@@ -79,11 +127,11 @@ pub async fn run(path: Option<&std::path::Path>, agency: bool) -> Result<()> {
     // `--agency` is additive: keep the standard agent file above and also emit
     // the Agency / Claude Code plugin.
     if agency {
-        write_agency_plugin(&base, version).await?;
+        write_agency_plugin(&base).await?;
     }
 
     println!();
-    println!("This agent helps you create, update, and debug Azure DevOps agentic pipelines.");
+    println!("This agent helps you create, update, and debug Azure DevOps agentic workflows.");
     println!("It will automatically download the ado-aw compiler and handle compilation.");
     println!();
     println!("To use it, ask your AI agent:");
@@ -97,28 +145,52 @@ pub async fn run(path: Option<&std::path::Path>, agency: bool) -> Result<()> {
     Ok(())
 }
 
-/// Write the Agency / Claude Code plugin into `<base>/.github/ado-aw`.
+/// Write the Agency / Claude Code plugin into `<base>/agency/plugins/ado-aw`,
+/// plus the repo-root marketplace catalogs that make `<base>` an installable
+/// marketplace.
 ///
 /// The plugin is additive to the standard agent file and follows the Claude
-/// Code plugin conventions, written under `.github/ado-aw` so it does not
-/// pollute the user's source tree.
-async fn write_agency_plugin(base: &Path, version: &str) -> Result<()> {
+/// Code plugin conventions, written under `agency/plugins/ado-aw` so it mirrors
+/// how the plugin is checked in to ado-aw itself. Files are copied verbatim from
+/// the canonical in-repo plugin (`agency/plugins/ado-aw/`); they already carry
+/// the correct release version, so no substitution is performed.
+///
+/// The root catalogs (`.claude-plugin/marketplace.json`,
+/// `.github/plugin/marketplace.json`) are what `/plugin marketplace add <repo>`
+/// reads, so the scaffolded repo is directly registerable as a marketplace.
+async fn write_agency_plugin(base: &Path) -> Result<()> {
     let plugin_root = base.join(AGENCY_PLUGIN_DIR);
 
-    for (rel_path, template) in AGENCY_PLUGIN_FILES {
+    for (rel_path, contents) in AGENCY_PLUGIN_FILES {
         let dest = plugin_root.join(rel_path);
         if let Some(parent) = dest.parent() {
             tokio::fs::create_dir_all(parent)
                 .await
                 .with_context(|| format!("Failed to create directory: {}", parent.display()))?;
         }
-        let content = template.replace("{{ compiler_version }}", version);
-        tokio::fs::write(&dest, content)
+        tokio::fs::write(&dest, contents)
             .await
             .with_context(|| format!("Failed to write plugin file: {}", dest.display()))?;
     }
 
+    // Root marketplace catalogs (written relative to the repo root, not the
+    // plugin dir) so `/plugin marketplace add <repo>` can detect the plugin.
+    for (rel_path, contents) in AGENCY_MARKETPLACE_FILES {
+        let dest = base.join(rel_path);
+        if let Some(parent) = dest.parent() {
+            tokio::fs::create_dir_all(parent)
+                .await
+                .with_context(|| format!("Failed to create directory: {}", parent.display()))?;
+        }
+        tokio::fs::write(&dest, contents)
+            .await
+            .with_context(|| format!("Failed to write marketplace catalog: {}", dest.display()))?;
+    }
+
     println!("✓ Created Agency plugin in {}", plugin_root.display());
+    println!(
+        "✓ Wrote marketplace catalogs (.claude-plugin/, .github/plugin/) — register with: /plugin marketplace add <this repo>"
+    );
 
     Ok(())
 }
diff --git a/src/main.rs b/src/main.rs
index c876b23d..5ed2fa31 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -282,7 +282,7 @@ enum Commands {
         #[arg(long = "enabled-tools")]
         enabled_tools: Vec<String>,
     },
-    /// Initialize a repository for AI-first agentic pipeline authoring
+    /// Initialize a repository for AI-first agentic workflow authoring
     Init {
         /// Target directory (defaults to current directory)
         #[arg(long)]
@@ -608,7 +608,7 @@ enum Commands {
 }
 
 #[derive(Parser, Debug)]
-#[command(version, about = "Compiler for Azure DevOps agentic pipelines")]
+#[command(version, about = "Compiler for Azure DevOps Agentic Workflows")]
 struct Args {
     /// Enable verbose logging (info level)
     #[arg(short, long, global = true)]
diff --git a/tests/init_tests.rs b/tests/init_tests.rs
index bfd6c3a7..74935494 100644
--- a/tests/init_tests.rs
+++ b/tests/init_tests.rs
@@ -26,7 +26,7 @@ fn test_init_creates_agent_file() {
 
     let content = fs::read_to_string(&agent_path).expect("Should be able to read agent file");
     assert!(
-        content.contains("ADO Agentic Pipelines Agent"),
+        content.contains("Azure DevOps Agentic Workflows Agent"),
         "Agent file should contain the expected title"
     );
     // Verify version placeholder was substituted
@@ -66,7 +66,7 @@ fn test_init_overwrites_by_default() {
 
     let content = fs::read_to_string(&agent_path).expect("Should read agent file");
     assert!(
-        content.contains("ADO Agentic Pipelines Agent"),
+        content.contains("Azure DevOps Agentic Workflows Agent"),
         "Default init should restore the template content"
     );
     assert!(
@@ -76,7 +76,7 @@ fn test_init_overwrites_by_default() {
 }
 
 /// Test that `init --agency` is additive: it produces the standard agent file
-/// AND the Agency / Claude Code plugin under the `.github/ado-aw` directory.
+/// AND the Agency / Claude Code plugin under the `agency/plugins/ado-aw` directory.
 #[test]
 fn test_init_agency_generates_plugin() {
     let temp_dir = tempfile::tempdir().expect("Failed to create temp directory");
@@ -104,46 +104,148 @@ fn test_init_agency_generates_plugin() {
         "Standard agent file should still be created with --agency"
     );
 
-    // Claude Code plugin manifest + marketplace under `.github/ado-aw`.
-    let plugin_root = temp_dir.path().join(".github/ado-aw");
+    // Claude Code plugin manifest + MCP wiring under `agency/plugins/ado-aw`.
+    let plugin_root = temp_dir.path().join("agency/plugins/ado-aw");
     let plugin_json = plugin_root.join(".claude-plugin/plugin.json");
-    let marketplace_json = plugin_root.join(".claude-plugin/marketplace.json");
     assert!(plugin_json.exists(), "plugin.json should be created");
     assert!(
-        marketplace_json.exists(),
-        "marketplace.json should be created"
+        plugin_root.join(".mcp.json").exists(),
+        "MCP server wiring (.mcp.json) should be created"
     );
+    assert!(
+        plugin_root.join("agency.json").exists(),
+        "agency.json governance metadata should be created"
+    );
+    assert!(
+        plugin_root.join("README.md").exists(),
+        "Plugin README.md should be created"
+    );
+
+    // Root marketplace catalogs make the repo registerable via
+    // `/plugin marketplace add <repo>` — they live at the repo root, not in the
+    // plugin dir, and must list the ado-aw plugin via a relative `source`.
+    for catalog in [
+        ".claude-plugin/marketplace.json",
+        ".github/plugin/marketplace.json",
+    ] {
+        let cat_path = temp_dir.path().join(catalog);
+        assert!(
+            cat_path.exists(),
+            "Root marketplace catalog {catalog} should be created"
+        );
+        let cat: serde_json::Value =
+            serde_json::from_str(&fs::read_to_string(&cat_path).expect("catalog readable"))
+                .unwrap_or_else(|e| panic!("{catalog} should be valid JSON: {e}"));
+        assert_eq!(
+            cat["plugins"][0]["name"], "ado-aw",
+            "{catalog} should list the ado-aw plugin"
+        );
+        assert_eq!(
+            cat["plugins"][0]["source"], "./agency/plugins/ado-aw",
+            "{catalog} plugin source should point at the plugin dir"
+        );
+    }
 
-    // Subagent + slash commands.
+    // Dispatcher subagent.
     assert!(
         plugin_root.join("agents/ado-aw.md").exists(),
         "Agency subagent should be created"
     );
-    for cmd in [
-        "create-ado-agentic-workflow.md",
-        "update-ado-agentic-workflow.md",
-        "debug-ado-agentic-workflow.md",
+
+    // All six skills.
+    for skill in [
+        "create-workflow",
+        "update-workflow",
+        "debug-workflow",
+        "compile-and-validate",
+        "manage-lifecycle",
+        "audit-build",
     ] {
         assert!(
-            plugin_root.join("commands").join(cmd).exists(),
-            "Command {cmd} should be created"
+            plugin_root
+                .join("skills")
+                .join(skill)
+                .join("SKILL.md")
+                .exists(),
+            "Skill {skill}/SKILL.md should be created"
+        );
+    }
+
+    // Doctor prerequisite scripts (both platforms).
+    for script in ["doctor.sh", "doctor.ps1"] {
+        assert!(
+            plugin_root.join("scripts").join(script).exists(),
+            "scripts/{script} should be created"
         );
     }
 
-    // Version placeholder must be substituted in the manifest.
-    let manifest =
-        fs::read_to_string(&plugin_json).expect("Should be able to read plugin.json");
+    // The manifest is a verbatim copy of the canonical plugin: it must carry a
+    // concrete version (no unresolved placeholder) and be valid JSON.
+    let manifest = fs::read_to_string(&plugin_json).expect("Should be able to read plugin.json");
     assert!(
         !manifest.contains("{{ compiler_version }}"),
-        "Version placeholder should be replaced in plugin.json"
+        "Version placeholder should not appear in plugin.json"
     );
     // plugin.json must be valid JSON with the expected plugin name.
     let parsed: serde_json::Value =
         serde_json::from_str(&manifest).expect("plugin.json should be valid JSON");
-    assert_eq!(
-        parsed["name"], "ado-aw",
-        "plugin.json name should be ado-aw"
-    );
+    assert_eq!(parsed["name"], "ado-aw", "plugin.json name should be ado-aw");
+}
+
+/// Test that `init --agency` scaffolds a byte-for-byte copy of the canonical
+/// in-repo plugin (`agency/plugins/ado-aw/`). This guards the single-source-of-
+/// truth invariant: the embedded files and the checked-in files must not drift.
+#[test]
+fn test_init_agency_matches_canonical_source() {
+    let temp_dir = tempfile::tempdir().expect("Failed to create temp directory");
+
+    let output = ado_aw_bin()
+        .args([
+            "init",
+            "--agency",
+            "--path",
+            temp_dir.path().to_str().unwrap(),
+        ])
+        .output()
+        .expect("Failed to run ado-aw init --agency");
+    assert!(output.status.success(), "init --agency should succeed");
+
+    let repo_root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
+    let canonical = repo_root.join("agency/plugins/ado-aw");
+    let scaffolded = temp_dir.path().join("agency/plugins/ado-aw");
+
+    for rel in [
+        ".claude-plugin/plugin.json",
+        ".mcp.json",
+        "agency.json",
+        "README.md",
+        "agents/ado-aw.md",
+        "skills/create-workflow/SKILL.md",
+        "skills/compile-and-validate/SKILL.md",
+        "scripts/doctor.sh",
+        "scripts/doctor.ps1",
+    ] {
+        let want = fs::read_to_string(canonical.join(rel))
+            .unwrap_or_else(|e| panic!("canonical {rel} should be readable: {e}"));
+        let got = fs::read_to_string(scaffolded.join(rel))
+            .unwrap_or_else(|e| panic!("scaffolded {rel} should be readable: {e}"));
+        assert_eq!(
+            got, want,
+            "scaffolded {rel} must match the canonical agency/plugins/ado-aw source"
+        );
+    }
+
+    // Root marketplace catalogs must also match the canonical repo-root copies.
+    for rel in [
+        ".claude-plugin/marketplace.json",
+        ".github/plugin/marketplace.json",
+    ] {
+        let want = fs::read_to_string(repo_root.join(rel))
+            .unwrap_or_else(|e| panic!("canonical {rel} should be readable: {e}"));
+        let got = fs::read_to_string(temp_dir.path().join(rel))
+            .unwrap_or_else(|e| panic!("scaffolded {rel} should be readable: {e}"));
+        assert_eq!(got, want, "scaffolded {rel} must match the canonical repo-root catalog");
+    }
 }
 
 /// Test that `init` WITHOUT `--agency` does not create the plugin directory.
@@ -158,9 +260,17 @@ fn test_init_without_agency_skips_plugin() {
     assert!(output.status.success(), "init should succeed");
 
     assert!(
-        !temp_dir.path().join(".github/ado-aw").exists(),
+        !temp_dir.path().join("agency/plugins/ado-aw").exists(),
         "Plugin directory should not be created without --agency"
     );
+    assert!(
+        !temp_dir.path().join(".claude-plugin/marketplace.json").exists(),
+        "Root Claude catalog should not be created without --agency"
+    );
+    assert!(
+        !temp_dir.path().join(".github/plugin/marketplace.json").exists(),
+        "Root Copilot catalog should not be created without --agency"
+    );
 }
 /// actual purpose: bypassing the GitHub-remote guard so maintainers can run
 /// `ado-aw init` inside a GitHub-hosted fork of `ado-aw` itself.

From 02ed055c4a875ef9f5e1d517fb202cf99ccb9ffd Mon Sep 17 00:00:00 2001
From: James Devine <devinejames@microsoft.com>
Date: Mon, 22 Jun 2026 15:46:55 +0100
Subject: [PATCH 04/10] fix(init): correct --agency help path and complete
 parity test coverage

Address Rust PR Reviewer feedback on #1102:
- `--agency` help text said `.github/ado-aw` (stale); the scaffold writes to
  `agency/plugins/ado-aw` plus repo-root marketplace catalogs.
- Extend test_init_agency_matches_canonical_source to verify all 13 embedded
  plugin files byte-for-byte (was 9), covering the previously-unchecked
  update/debug/manage-lifecycle/audit-build skills.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 src/main.rs         | 3 ++-
 tests/init_tests.rs | 4 ++++
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/src/main.rs b/src/main.rs
index 5ed2fa31..5d591780 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -292,7 +292,8 @@ enum Commands {
         #[arg(long)]
         force: bool,
         /// Additionally generate an Agency / Claude Code plugin under
-        /// `.github/ado-aw` (additive to the standard agent file).
+        /// `agency/plugins/ado-aw` plus repo-root marketplace catalogs
+        /// (additive to the standard agent file).
         #[arg(long)]
         agency: bool,
     },
diff --git a/tests/init_tests.rs b/tests/init_tests.rs
index 74935494..731ab9bc 100644
--- a/tests/init_tests.rs
+++ b/tests/init_tests.rs
@@ -221,7 +221,11 @@ fn test_init_agency_matches_canonical_source() {
         "README.md",
         "agents/ado-aw.md",
         "skills/create-workflow/SKILL.md",
+        "skills/update-workflow/SKILL.md",
+        "skills/debug-workflow/SKILL.md",
         "skills/compile-and-validate/SKILL.md",
+        "skills/manage-lifecycle/SKILL.md",
+        "skills/audit-build/SKILL.md",
         "scripts/doctor.sh",
         "scripts/doctor.ps1",
     ] {

From 9d4c992c30223fc728cf3c1db46d674ec7e5dc70 Mon Sep 17 00:00:00 2001
From: James Devine <devinejames@microsoft.com>
Date: Tue, 23 Jun 2026 09:56:44 +0100
Subject: [PATCH 05/10] docs(agency): add dedicated Agency plugin reference
 page

Add docs/agency-plugin.md (canonical layout, skills, mcp-author wiring,
self-contained root marketplace catalogs, init --agency scaffolding,
release-please version-locking, shared-marketplace listing) and index it
from AGENTS.md, matching the repo's one-page-per-concept docs convention.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 AGENTS.md             |   6 ++
 docs/agency-plugin.md | 134 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 140 insertions(+)
 create mode 100644 docs/agency-plugin.md

diff --git a/AGENTS.md b/AGENTS.md
index ecfd23c9..f6cb8e4b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -336,11 +336,17 @@ index to jump to the right page.
 ### Compiler internals & operations
 
 - [`docs/ir.md`](docs/ir.md) — typed Azure DevOps pipeline IR (`Pipeline`, jobs/stages/steps, output refs, graph pass, lowering, target builders, and the public JSON summary consumed by agent-facing tooling).
+- [`docs/cli.md`](docs/cli.md) — `ado-aw` CLI commands (`init`, `compile`,
+  `check`, `mcp`, `mcp-http`, `execute`, `secrets`, `enable`, `disable`,
 - [`docs/cli.md`](docs/cli.md) — `ado-aw` CLI commands (`init`, `compile`,
   `check`, `mcp`, `mcp-http`, `execute`, `secrets`, `enable`, `disable`,
   `remove`, `list`, `status`, `run`, `audit`, `mcp-author`, `trace`,
   `inspect`, `graph`, `whatif`, `lint`, `catalog`; `configure` is a
   deprecated hidden alias and `export-gate-schema` is a hidden build-time tool).
+- [`docs/agency-plugin.md`](docs/agency-plugin.md) — the Agency / Claude Code
+  plugin (`agency/plugins/ado-aw/`): canonical layout, six skills, `mcp-author`
+  wiring, the self-contained root marketplace catalogs, `init --agency`
+  scaffolding, release-please version-locking, and shared-marketplace listing.
 - [`docs/audit.md`](docs/audit.md) — `ado-aw audit`: accepted build-id / URL
   forms, artifact layout, cache behavior, rejection tracing, and `AuditData`
   report shape.
diff --git a/docs/agency-plugin.md b/docs/agency-plugin.md
new file mode 100644
index 00000000..c511b65b
--- /dev/null
+++ b/docs/agency-plugin.md
@@ -0,0 +1,134 @@
+# Agency / Claude Code Plugin
+
+_Part of the [ado-aw documentation](../AGENTS.md)._
+
+ado-aw ships a [Claude Code plugin](https://code.claude.com/docs/en/plugins-reference)
+that helps engineers author, compile, validate, operate, and debug Azure DevOps
+agentic workflows from their agent (Claude Code or Copilot CLI). It is also an
+[Agency](https://github.com/agency-microsoft/playground) marketplace plugin.
+
+The plugin is mostly **packaging + wiring**, not new behavior: it surfaces
+ado-aw's existing read-only [`mcp-author`](mcp-author.md) server and the
+authoring playbooks in [`prompts/`](../prompts) as agent skills.
+
+## Source of truth
+
+The canonical, version-controlled plugin lives in this repository at
+[`agency/plugins/ado-aw/`](../agency/plugins/ado-aw). It is the single source of
+truth — `ado-aw init --agency` embeds these exact files via `include_str!` and
+scaffolds them verbatim, so a consumer repo's plugin can never drift from the
+canonical copy. A parity test (`tests/init_tests.rs`) asserts the two are
+byte-for-byte identical.
+
+## Layout
+
+```
+agency/plugins/ado-aw/
+├── .claude-plugin/
+│   └── plugin.json            # plugin manifest (name, version, mcpServers ref)
+├── .mcp.json                  # wires the read-only `ado-aw mcp-author` server
+├── agency.json                # Agency marketplace governance + external source
+├── README.md                  # plugin landing page
+├── agents/
+│   └── ado-aw.md              # dispatcher subagent (routes to skills)
+├── skills/
+│   ├── create-workflow/SKILL.md
+│   ├── update-workflow/SKILL.md
+│   ├── debug-workflow/SKILL.md
+│   ├── compile-and-validate/SKILL.md
+│   ├── manage-lifecycle/SKILL.md
+│   └── audit-build/SKILL.md
+└── scripts/
+    ├── doctor.sh              # prerequisite check (POSIX)
+    └── doctor.ps1             # prerequisite check (Windows)
+```
+
+### Skills
+
+| Skill | Source of truth | What it does |
+| --- | --- | --- |
+| `create-workflow` | `prompts/create-ado-agentic-workflow.md` | Author a new agentic workflow; ends with compile + lint. |
+| `update-workflow` | `prompts/update-ado-agentic-workflow.md` | Read-then-update an existing workflow with validation. |
+| `debug-workflow` | `prompts/debug-ado-agentic-workflow.md` | Diagnose a failing run via `trace_failure` + `audit_build`. |
+| `compile-and-validate` | [`docs/cli.md`](cli.md), [`docs/ir.md`](ir.md) | `ado-aw compile` + `lint_workflow` + IR/graph inspection. |
+| `manage-lifecycle` | [`docs/cli.md`](cli.md) | `enable`/`disable`/`remove`/`run`/`list`/`status`/`secrets`. |
+| `audit-build` | [`docs/audit.md`](audit.md) | Download + analyze a finished build's artifacts. |
+
+The `create`/`update`/`debug` skills load their authoritative playbook from a
+**compiler-version-pinned** `raw.githubusercontent.com/.../v<version>/prompts/...`
+URL, so the instructions always match the installed binary.
+
+## MCP / tool surface
+
+`.mcp.json` wires the local, read-only [`ado-aw mcp-author`](mcp-author.md) stdio
+server, exposing `inspect_workflow`, `graph_summary`, `graph_dump`,
+`step_dependencies`, `step_outputs`, `lint_workflow`, `whatif`, `catalog`,
+`trace_failure`, and `audit_build`. Mutating actions (`compile`, `enable`,
+`disable`, `remove`, `run`, `secrets`, `init`) are **not** in the MCP server — the
+skills invoke them via the agent's shell, so the read-only firebreak is preserved.
+
+## Self-contained marketplace
+
+The repository root carries two generated marketplace catalogs that make the repo
+directly installable:
+
+| File | Engine |
+| --- | --- |
+| `.claude-plugin/marketplace.json` | Claude Code |
+| `.github/plugin/marketplace.json` | GitHub Copilot |
+
+Each lists the `ado-aw` plugin via `source: "./agency/plugins/ado-aw"`. After
+running `ado-aw init --agency` (or pointing at this repo), register and install:
+
+```text
+/plugin marketplace add githubnext/ado-aw
+/plugin install ado-aw@ado-aw
+```
+
+`ado-aw init --agency` writes the plugin under `agency/plugins/ado-aw/` **plus**
+these root catalogs into the target repo, mirroring how the plugin is checked in
+to ado-aw itself.
+
+## Versioning
+
+The plugin is **version-locked to the compiler**. `release-please` (via
+`extra-files` in `release-please-config.json`) bumps, in lock-step on every
+release:
+
+- `plugin.json` `version` and both root catalogs' `metadata.version` +
+  `plugins[0].version` (JSON updaters), and
+- the version-pinned prompt URLs in `agents/ado-aw.md` and the
+  create/update/debug skills (generic updater, keyed on the
+  `<!-- x-release-please-version -->` marker).
+
+## Identity & governance
+
+`agency.json` declares `engines: ["claude", "copilot"]`, `category:
+developer-tools`, and `governance: { layer: 4, certification: draft,
+organization: github-next }`. Following the Agency convention, it carries **no
+personal alias or email** — identity is the organization name only. It also
+declares an external `source` pointer to this repo, used when the plugin is
+listed in the shared Agency marketplace.
+
+## Listing in the shared Agency marketplace
+
+Hosting the plugin here makes it installable directly, but it is separate from
+being _listed in_ `agency-microsoft/playground`. To list it, add a one-line
+external-source entry to that repo's `marketplace-config.json`:
+
+```json
+"extPluginSources": {
+  "https://github.com/githubnext/ado-aw.git": ["agency/plugins/ado-aw"]
+}
+```
+
+The playground's sync bot then generates the shared marketplace entry from this
+repo's `agency.json` `source` block.
+
+## Related references
+
+- [`docs/cli.md`](cli.md) — the `init --agency` flag and CLI counterparts for the
+  skills' commands.
+- [`docs/mcp-author.md`](mcp-author.md) — the read-only MCP server the plugin wires.
+- [`prompts/`](../prompts) — the authoritative authoring playbooks the
+  create/update/debug skills load.

From 5e74d7f387e68d84613f503915d745a4a03b0f9d Mon Sep 17 00:00:00 2001
From: James Devine <devinejames@microsoft.com>
Date: Tue, 23 Jun 2026 10:11:20 +0100
Subject: [PATCH 06/10] chore(agency): resync plugin version to 0.38.0 after
 release

The 0.37.0->0.38.0 release landed on main while this PR was open, bumping
Cargo.toml but not the not-yet-merged plugin files. Resync the literal
versions (plugin.json, both root catalogs, and the pinned prompt URLs in the
agent + create/update/debug skills) so the plugin matches the compiler.
release-please extra-files keeps them in lock-step on future releases.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .claude-plugin/marketplace.json                       | 4 ++--
 .github/plugin/marketplace.json                       | 4 ++--
 agency/plugins/ado-aw/.claude-plugin/plugin.json      | 2 +-
 agency/plugins/ado-aw/agents/ado-aw.md                | 8 ++++----
 agency/plugins/ado-aw/skills/create-workflow/SKILL.md | 2 +-
 agency/plugins/ado-aw/skills/debug-workflow/SKILL.md  | 2 +-
 agency/plugins/ado-aw/skills/update-workflow/SKILL.md | 2 +-
 7 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 68e3ff90..747ddf8b 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -2,7 +2,7 @@
   "name": "ado-aw",
   "metadata": {
     "description": "Azure DevOps Agentic Workflows (ado-aw) marketplace",
-    "version": "0.37.0"
+    "version": "0.38.0"
   },
   "owner": {
     "name": "GitHub Next",
@@ -12,7 +12,7 @@
     {
       "name": "ado-aw",
       "source": "./agency/plugins/ado-aw",
-      "version": "0.37.0",
+      "version": "0.38.0",
       "description": "Create, update, validate, operate, and debug Azure DevOps agentic workflows with ado-aw",
       "keywords": ["azure-devops", "ado", "agentic", "pipelines", "ado-aw"]
     }
diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json
index 68e3ff90..747ddf8b 100644
--- a/.github/plugin/marketplace.json
+++ b/.github/plugin/marketplace.json
@@ -2,7 +2,7 @@
   "name": "ado-aw",
   "metadata": {
     "description": "Azure DevOps Agentic Workflows (ado-aw) marketplace",
-    "version": "0.37.0"
+    "version": "0.38.0"
   },
   "owner": {
     "name": "GitHub Next",
@@ -12,7 +12,7 @@
     {
       "name": "ado-aw",
       "source": "./agency/plugins/ado-aw",
-      "version": "0.37.0",
+      "version": "0.38.0",
       "description": "Create, update, validate, operate, and debug Azure DevOps agentic workflows with ado-aw",
       "keywords": ["azure-devops", "ado", "agentic", "pipelines", "ado-aw"]
     }
diff --git a/agency/plugins/ado-aw/.claude-plugin/plugin.json b/agency/plugins/ado-aw/.claude-plugin/plugin.json
index 9d75c649..77781a4b 100644
--- a/agency/plugins/ado-aw/.claude-plugin/plugin.json
+++ b/agency/plugins/ado-aw/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "ado-aw",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "description": "Azure DevOps Agentic Workflows (ado-aw) — create, update, validate, operate, and debug AI-powered Azure DevOps agentic workflows: Markdown agent specs compiled into secure, network-isolated ADO pipelines.",
   "author": {
     "name": "GitHub Next",
diff --git a/agency/plugins/ado-aw/agents/ado-aw.md b/agency/plugins/ado-aw/agents/ado-aw.md
index 501e232d..e5d60f9e 100644
--- a/agency/plugins/ado-aw/agents/ado-aw.md
+++ b/agency/plugins/ado-aw/agents/ado-aw.md
@@ -60,10 +60,10 @@ Route the user's request to the matching skill:
 
 The create/update/debug skills load these compiler-version-pinned playbooks:
 
-- Create: https://raw.githubusercontent.com/githubnext/ado-aw/v0.37.0/prompts/create-ado-agentic-workflow.md <!-- x-release-please-version -->
-- Update: https://raw.githubusercontent.com/githubnext/ado-aw/v0.37.0/prompts/update-ado-agentic-workflow.md <!-- x-release-please-version -->
-- Debug: https://raw.githubusercontent.com/githubnext/ado-aw/v0.37.0/prompts/debug-ado-agentic-workflow.md <!-- x-release-please-version -->
-- Full reference: https://raw.githubusercontent.com/githubnext/ado-aw/v0.37.0/AGENTS.md <!-- x-release-please-version -->
+- Create: https://raw.githubusercontent.com/githubnext/ado-aw/v0.38.0/prompts/create-ado-agentic-workflow.md <!-- x-release-please-version -->
+- Update: https://raw.githubusercontent.com/githubnext/ado-aw/v0.38.0/prompts/update-ado-agentic-workflow.md <!-- x-release-please-version -->
+- Debug: https://raw.githubusercontent.com/githubnext/ado-aw/v0.38.0/prompts/debug-ado-agentic-workflow.md <!-- x-release-please-version -->
+- Full reference: https://raw.githubusercontent.com/githubnext/ado-aw/v0.38.0/AGENTS.md <!-- x-release-please-version -->
 
 ## Guardrails
 
diff --git a/agency/plugins/ado-aw/skills/create-workflow/SKILL.md b/agency/plugins/ado-aw/skills/create-workflow/SKILL.md
index b7b36e58..11ef17c3 100644
--- a/agency/plugins/ado-aw/skills/create-workflow/SKILL.md
+++ b/agency/plugins/ado-aw/skills/create-workflow/SKILL.md
@@ -15,7 +15,7 @@ You are creating a **new** ado-aw agentic workflow.
 2. Load the **entire** content of the authoritative, version-pinned playbook and
    follow its instructions precisely:
 
-   https://raw.githubusercontent.com/githubnext/ado-aw/v0.37.0/prompts/create-ado-agentic-workflow.md <!-- x-release-please-version -->
+   https://raw.githubusercontent.com/githubnext/ado-aw/v0.38.0/prompts/create-ado-agentic-workflow.md <!-- x-release-please-version -->
 
 3. While authoring, use the read-only MCP tools to stay grounded:
    - `catalog` — discover available safe-outputs, runtimes, tools, engines, models.
diff --git a/agency/plugins/ado-aw/skills/debug-workflow/SKILL.md b/agency/plugins/ado-aw/skills/debug-workflow/SKILL.md
index c70fbda4..266b5f3e 100644
--- a/agency/plugins/ado-aw/skills/debug-workflow/SKILL.md
+++ b/agency/plugins/ado-aw/skills/debug-workflow/SKILL.md
@@ -21,7 +21,7 @@ You are troubleshooting a **failing** ado-aw agentic workflow.
 3. Load the **entire** content of the authoritative, version-pinned playbook and
    follow its instructions precisely:
 
-   https://raw.githubusercontent.com/githubnext/ado-aw/v0.37.0/prompts/debug-ado-agentic-workflow.md <!-- x-release-please-version -->
+   https://raw.githubusercontent.com/githubnext/ado-aw/v0.38.0/prompts/debug-ado-agentic-workflow.md <!-- x-release-please-version -->
 
 4. For Stage 3 (SafeOutputs) 401/403 failures, consult
    `docs/safe-output-permissions.md` and surface the auth/permission error
diff --git a/agency/plugins/ado-aw/skills/update-workflow/SKILL.md b/agency/plugins/ado-aw/skills/update-workflow/SKILL.md
index 273ecf25..36d00482 100644
--- a/agency/plugins/ado-aw/skills/update-workflow/SKILL.md
+++ b/agency/plugins/ado-aw/skills/update-workflow/SKILL.md
@@ -17,7 +17,7 @@ You are modifying an **existing** ado-aw agentic workflow.
 3. Load the **entire** content of the authoritative, version-pinned playbook and
    follow its instructions precisely:
 
-   https://raw.githubusercontent.com/githubnext/ado-aw/v0.37.0/prompts/update-ado-agentic-workflow.md <!-- x-release-please-version -->
+   https://raw.githubusercontent.com/githubnext/ado-aw/v0.38.0/prompts/update-ado-agentic-workflow.md <!-- x-release-please-version -->
 
 4. Use `catalog` to confirm any newly referenced safe-output / runtime / tool /
    model identifiers are valid.

From bfae6653b3efd634dd002b9c8b63b87531ab9207 Mon Sep 17 00:00:00 2001
From: James Devine <devinejames@microsoft.com>
Date: Tue, 23 Jun 2026 10:54:15 +0100
Subject: [PATCH 07/10] fix(agency): address Rust PR review feedback

Round 2 review (run 28016634353) on #1102:

- doctor.sh not executable: scaffolded copies (tokio::fs::write) and the
  checked-in file (git 100644) were non-exec, so `./scripts/doctor.sh` would
  fail with Permission denied. Mark the canonical file 100755 and document the
  cross-platform-safe `bash ./scripts/doctor.sh` invocation in the plugin
  README + dispatcher agent.
- tests/init_tests.rs: restore the truncated first line of the
  test_init_force_flag_is_advertised_in_help doc comment.
- src/init.rs: replace the silent `if let Some(parent)` skip with an explicit
  parent-directory resolution + error, so a missing parent fails loudly.
- release-please: track the checked-in .github/agents/ado-aw.agent.md for
  version bumps (add x-release-please-version markers to src/data/init-agent.md
  prompt URLs + list it in extra-files) so it no longer drifts on each release.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .github/agents/ado-aw.agent.md          |  8 ++++----
 agency/plugins/ado-aw/README.md         |  4 ++--
 agency/plugins/ado-aw/agents/ado-aw.md  |  2 +-
 agency/plugins/ado-aw/scripts/doctor.sh |  0
 release-please-config.json              |  3 ++-
 src/data/init-agent.md                  |  8 ++++----
 src/init.rs                             | 22 ++++++++++++----------
 tests/init_tests.rs                     |  1 +
 8 files changed, 26 insertions(+), 22 deletions(-)
 mode change 100644 => 100755 agency/plugins/ado-aw/scripts/doctor.sh

diff --git a/.github/agents/ado-aw.agent.md b/.github/agents/ado-aw.agent.md
index c2f51220..e6fd5f76 100644
--- a/.github/agents/ado-aw.agent.md
+++ b/.github/agents/ado-aw.agent.md
@@ -46,7 +46,7 @@ This is a **dispatcher agent** that routes your request to the appropriate speci
 ### Create New Agentic Workflow
 **Load when**: User wants to create a new agentic workflow from scratch
 
-**Prompt file**: https://raw.githubusercontent.com/githubnext/ado-aw/v0.37.0/prompts/create-ado-agentic-workflow.md
+**Prompt file**: https://raw.githubusercontent.com/githubnext/ado-aw/v0.38.0/prompts/create-ado-agentic-workflow.md <!-- x-release-please-version -->
 
 **Use cases**:
 - "Create an agentic workflow that reviews PRs weekly"
@@ -56,7 +56,7 @@ This is a **dispatcher agent** that routes your request to the appropriate speci
 ### Update Existing Workflow
 **Load when**: User wants to modify an existing agent workflow file
 
-**Prompt file**: https://raw.githubusercontent.com/githubnext/ado-aw/v0.37.0/prompts/update-ado-agentic-workflow.md
+**Prompt file**: https://raw.githubusercontent.com/githubnext/ado-aw/v0.38.0/prompts/update-ado-agentic-workflow.md <!-- x-release-please-version -->
 
 **Use cases**:
 - "Add the Azure DevOps MCP to my workflow"
@@ -66,7 +66,7 @@ This is a **dispatcher agent** that routes your request to the appropriate speci
 ### Debug Failing Workflow
 **Load when**: User needs to troubleshoot a failing agentic workflow
 
-**Prompt file**: https://raw.githubusercontent.com/githubnext/ado-aw/v0.37.0/prompts/debug-ado-agentic-workflow.md
+**Prompt file**: https://raw.githubusercontent.com/githubnext/ado-aw/v0.38.0/prompts/debug-ado-agentic-workflow.md <!-- x-release-please-version -->
 
 **Use cases**:
 - "Why is my agentic workflow failing?"
@@ -109,4 +109,4 @@ ado-aw check <pipeline.lock.yml>
 - Agent files must be compiled with `ado-aw compile` after YAML frontmatter changes
 - Markdown body (agent instructions) changes do NOT require recompilation
 - The agent never has direct write access — all mutations go through safe outputs
-- Full reference: https://raw.githubusercontent.com/githubnext/ado-aw/v0.37.0/AGENTS.md
+- Full reference: https://raw.githubusercontent.com/githubnext/ado-aw/v0.38.0/AGENTS.md <!-- x-release-please-version -->
diff --git a/agency/plugins/ado-aw/README.md b/agency/plugins/ado-aw/README.md
index 240486ab..a84a82a6 100644
--- a/agency/plugins/ado-aw/README.md
+++ b/agency/plugins/ado-aw/README.md
@@ -49,10 +49,10 @@ so that repo becomes registerable the same way.
 The `ado-aw` compiler must be on `PATH`. Run the bundled doctor check first:
 
 ```bash
-./scripts/doctor.sh     # macOS / Linux
+bash ./scripts/doctor.sh    # macOS / Linux
 ```
 ```powershell
-.\scripts\doctor.ps1    # Windows
+.\scripts\doctor.ps1        # Windows
 ```
 
 If `ado-aw` is missing, install it from the
diff --git a/agency/plugins/ado-aw/agents/ado-aw.md b/agency/plugins/ado-aw/agents/ado-aw.md
index e5d60f9e..ee465c49 100644
--- a/agency/plugins/ado-aw/agents/ado-aw.md
+++ b/agency/plugins/ado-aw/agents/ado-aw.md
@@ -15,7 +15,7 @@ network-isolated sandboxes (Agent → Threat Detection → Safe-Output Execution
 ## Prerequisites
 
 Before doing anything else, make sure the ado-aw compiler is available — run the
-**doctor** check (`scripts/doctor.sh` on macOS/Linux, `scripts/doctor.ps1` on
+**doctor** check (`bash scripts/doctor.sh` on macOS/Linux, `scripts/doctor.ps1` on
 Windows). It verifies `ado-aw` is on `PATH` and that `gh`/`az` auth is present
 where ADO calls are needed. If `ado-aw` is missing, install it:
 
diff --git a/agency/plugins/ado-aw/scripts/doctor.sh b/agency/plugins/ado-aw/scripts/doctor.sh
old mode 100644
new mode 100755
diff --git a/release-please-config.json b/release-please-config.json
index a8a30b10..99e216d7 100644
--- a/release-please-config.json
+++ b/release-please-config.json
@@ -34,7 +34,8 @@
         "agency/plugins/ado-aw/agents/ado-aw.md",
         "agency/plugins/ado-aw/skills/create-workflow/SKILL.md",
         "agency/plugins/ado-aw/skills/update-workflow/SKILL.md",
-        "agency/plugins/ado-aw/skills/debug-workflow/SKILL.md"
+        "agency/plugins/ado-aw/skills/debug-workflow/SKILL.md",
+        ".github/agents/ado-aw.agent.md"
       ]
     }
   }
diff --git a/src/data/init-agent.md b/src/data/init-agent.md
index b39e6083..7b52ec73 100644
--- a/src/data/init-agent.md
+++ b/src/data/init-agent.md
@@ -46,7 +46,7 @@ This is a **dispatcher agent** that routes your request to the appropriate speci
 ### Create New Agentic Workflow
 **Load when**: User wants to create a new agentic workflow from scratch
 
-**Prompt file**: https://raw.githubusercontent.com/githubnext/ado-aw/v{{ compiler_version }}/prompts/create-ado-agentic-workflow.md
+**Prompt file**: https://raw.githubusercontent.com/githubnext/ado-aw/v{{ compiler_version }}/prompts/create-ado-agentic-workflow.md <!-- x-release-please-version -->
 
 **Use cases**:
 - "Create an agentic workflow that reviews PRs weekly"
@@ -56,7 +56,7 @@ This is a **dispatcher agent** that routes your request to the appropriate speci
 ### Update Existing Workflow
 **Load when**: User wants to modify an existing agent workflow file
 
-**Prompt file**: https://raw.githubusercontent.com/githubnext/ado-aw/v{{ compiler_version }}/prompts/update-ado-agentic-workflow.md
+**Prompt file**: https://raw.githubusercontent.com/githubnext/ado-aw/v{{ compiler_version }}/prompts/update-ado-agentic-workflow.md <!-- x-release-please-version -->
 
 **Use cases**:
 - "Add the Azure DevOps MCP to my workflow"
@@ -66,7 +66,7 @@ This is a **dispatcher agent** that routes your request to the appropriate speci
 ### Debug Failing Workflow
 **Load when**: User needs to troubleshoot a failing agentic workflow
 
-**Prompt file**: https://raw.githubusercontent.com/githubnext/ado-aw/v{{ compiler_version }}/prompts/debug-ado-agentic-workflow.md
+**Prompt file**: https://raw.githubusercontent.com/githubnext/ado-aw/v{{ compiler_version }}/prompts/debug-ado-agentic-workflow.md <!-- x-release-please-version -->
 
 **Use cases**:
 - "Why is my agentic workflow failing?"
@@ -109,4 +109,4 @@ ado-aw check <pipeline.lock.yml>
 - Agent files must be compiled with `ado-aw compile` after YAML frontmatter changes
 - Markdown body (agent instructions) changes do NOT require recompilation
 - The agent never has direct write access — all mutations go through safe outputs
-- Full reference: https://raw.githubusercontent.com/githubnext/ado-aw/v{{ compiler_version }}/AGENTS.md
+- Full reference: https://raw.githubusercontent.com/githubnext/ado-aw/v{{ compiler_version }}/AGENTS.md <!-- x-release-please-version -->
diff --git a/src/init.rs b/src/init.rs
index 23498396..7e86011f 100644
--- a/src/init.rs
+++ b/src/init.rs
@@ -163,11 +163,12 @@ async fn write_agency_plugin(base: &Path) -> Result<()> {
 
     for (rel_path, contents) in AGENCY_PLUGIN_FILES {
         let dest = plugin_root.join(rel_path);
-        if let Some(parent) = dest.parent() {
-            tokio::fs::create_dir_all(parent)
-                .await
-                .with_context(|| format!("Failed to create directory: {}", parent.display()))?;
-        }
+        let parent = dest
+            .parent()
+            .with_context(|| format!("Plugin file has no parent directory: {}", dest.display()))?;
+        tokio::fs::create_dir_all(parent)
+            .await
+            .with_context(|| format!("Failed to create directory: {}", parent.display()))?;
         tokio::fs::write(&dest, contents)
             .await
             .with_context(|| format!("Failed to write plugin file: {}", dest.display()))?;
@@ -177,11 +178,12 @@ async fn write_agency_plugin(base: &Path) -> Result<()> {
     // plugin dir) so `/plugin marketplace add <repo>` can detect the plugin.
     for (rel_path, contents) in AGENCY_MARKETPLACE_FILES {
         let dest = base.join(rel_path);
-        if let Some(parent) = dest.parent() {
-            tokio::fs::create_dir_all(parent)
-                .await
-                .with_context(|| format!("Failed to create directory: {}", parent.display()))?;
-        }
+        let parent = dest.parent().with_context(|| {
+            format!("Marketplace catalog has no parent directory: {}", dest.display())
+        })?;
+        tokio::fs::create_dir_all(parent)
+            .await
+            .with_context(|| format!("Failed to create directory: {}", parent.display()))?;
         tokio::fs::write(&dest, contents)
             .await
             .with_context(|| format!("Failed to write marketplace catalog: {}", dest.display()))?;
diff --git a/tests/init_tests.rs b/tests/init_tests.rs
index 731ab9bc..abb0a30a 100644
--- a/tests/init_tests.rs
+++ b/tests/init_tests.rs
@@ -276,6 +276,7 @@ fn test_init_without_agency_skips_plugin() {
         "Root Copilot catalog should not be created without --agency"
     );
 }
+/// Test that `--force` is advertised in `init --help` and describes its
 /// actual purpose: bypassing the GitHub-remote guard so maintainers can run
 /// `ado-aw init` inside a GitHub-hosted fork of `ado-aw` itself.
 ///

From 183d1b203597ad080e5cb88ac2bdc18ff4901ac1 Mon Sep 17 00:00:00 2001
From: James Devine <devinejames@microsoft.com>
Date: Tue, 23 Jun 2026 13:50:58 +0100
Subject: [PATCH 08/10] fix(init): set executable bit on scaffolded doctor.sh +
 document version tracking
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Follow-up to the Rust PR review on #1102:

- src/init.rs: after writing each plugin file, set mode 0755 on `.sh` files
  (`#[cfg(unix)]`, mirroring src/compile/common.rs) so the scaffolded
  doctor.sh is executable and the documented `./scripts/doctor.sh` works —
  `tokio::fs::write` otherwise leaves it 0644.
- tests/init_tests.rs: add a `#[cfg(unix)]` assertion that the scaffolded
  doctor.sh carries the executable bit, guarding this going forward.
- docs/agency-plugin.md: add a maintainer note spelling out that the
  compile-and-validate/manage-lifecycle/audit-build skills are intentionally
  omitted from release-please `extra-files`, and that adding a version-pinned
  URL to any of them requires both an x-release-please-version marker and an
  extra-files entry.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 docs/agency-plugin.md |  9 +++++++++
 src/init.rs           | 12 ++++++++++++
 tests/init_tests.rs   | 15 +++++++++++++++
 3 files changed, 36 insertions(+)

diff --git a/docs/agency-plugin.md b/docs/agency-plugin.md
index c511b65b..85c04897 100644
--- a/docs/agency-plugin.md
+++ b/docs/agency-plugin.md
@@ -101,6 +101,15 @@ release:
   create/update/debug skills (generic updater, keyed on the
   `<!-- x-release-please-version -->` marker).
 
+> **Maintainer note — adding a version reference to a skill.** Only files that
+> contain a version-pinned URL are listed in `release-please-config.json`
+> `extra-files`. The `compile-and-validate`, `manage-lifecycle`, and
+> `audit-build` skills are **intentionally omitted** because they are CLI/MCP-
+> driven and carry no pinned version. If you add a `v<version>/...` reference to
+> any of them, you **must** add a `<!-- x-release-please-version -->` marker on
+> that line **and** add the file to `extra-files`, or the bump will silently be
+> missed.
+
 ## Identity & governance
 
 `agency.json` declares `engines: ["claude", "copilot"]`, `category:
diff --git a/src/init.rs b/src/init.rs
index 7e86011f..20411f2c 100644
--- a/src/init.rs
+++ b/src/init.rs
@@ -172,6 +172,18 @@ async fn write_agency_plugin(base: &Path) -> Result<()> {
         tokio::fs::write(&dest, contents)
             .await
             .with_context(|| format!("Failed to write plugin file: {}", dest.display()))?;
+
+        // `tokio::fs::write` creates files mode 0644 (minus umask); shell scripts
+        // need the executable bit so the documented `./scripts/doctor.sh` works.
+        #[cfg(unix)]
+        if rel_path.ends_with(".sh") {
+            use std::os::unix::fs::PermissionsExt;
+            tokio::fs::set_permissions(&dest, std::fs::Permissions::from_mode(0o755))
+                .await
+                .with_context(|| {
+                    format!("Failed to set executable bit: {}", dest.display())
+                })?;
+        }
     }
 
     // Root marketplace catalogs (written relative to the repo root, not the
diff --git a/tests/init_tests.rs b/tests/init_tests.rs
index abb0a30a..067eb39d 100644
--- a/tests/init_tests.rs
+++ b/tests/init_tests.rs
@@ -179,6 +179,21 @@ fn test_init_agency_generates_plugin() {
         );
     }
 
+    // On Unix, the scaffolded doctor.sh must be executable so the documented
+    // `./scripts/doctor.sh` invocation works (not just `bash doctor.sh`).
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        let mode = fs::metadata(plugin_root.join("scripts/doctor.sh"))
+            .expect("doctor.sh metadata")
+            .permissions()
+            .mode();
+        assert!(
+            mode & 0o111 != 0,
+            "scaffolded doctor.sh should have the executable bit set, got mode {mode:o}"
+        );
+    }
+
     // The manifest is a verbatim copy of the canonical plugin: it must carry a
     // concrete version (no unresolved placeholder) and be valid JSON.
     let manifest = fs::read_to_string(&plugin_json).expect("Should be able to read plugin.json");

From fb812dbde688baf6a9c8d94889158d68d01bf433 Mon Sep 17 00:00:00 2001
From: James Devine <devinejames@microsoft.com>
Date: Wed, 24 Jun 2026 22:19:02 +0100
Subject: [PATCH 09/10] test(init): harden SSOT/version invariants from design
 review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Address the design-review findings on #1102:

- Directory-walk parity test: test_init_agency_matches_canonical_source now
  walks agency/plugins/ado-aw/ instead of a hardcoded list, so a new canonical
  file that nobody wired into AGENCY_PLUGIN_FILES fails loudly instead of being
  shipped via the in-repo marketplace but never scaffolded by `init --agency`.
- Version-parity guard: test_plugin_version_matches_crate_version asserts
  plugin.json + both root catalogs (metadata + plugins[0]) equal the crate
  version, so a release landing mid-change can no longer desync silently.
- Clobber guard: write_agency_plugin no longer overwrites a consumer's
  pre-existing, differing root marketplace catalog — it skips with a warning and
  leaves it for manual merge (identical catalogs remain an idempotent no-op).
  Covered by test_init_agency_does_not_clobber_existing_catalog.
- Committed-agent parity: test_committed_agent_file_matches_template_output
  guards .github/agents/ado-aw.agent.md against drift from its template.
- Clarify in docs/agency-plugin.md that the template's release-please markers
  intentionally propagate into the committed agent file (the tracked one); the
  template markers are inert by design and must not be stripped.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 docs/agency-plugin.md |  10 +++
 src/init.rs           |  36 ++++++++-
 tests/init_tests.rs   | 170 +++++++++++++++++++++++++++++++++++++-----
 3 files changed, 196 insertions(+), 20 deletions(-)

diff --git a/docs/agency-plugin.md b/docs/agency-plugin.md
index 85c04897..b6238980 100644
--- a/docs/agency-plugin.md
+++ b/docs/agency-plugin.md
@@ -101,6 +101,16 @@ release:
   create/update/debug skills (generic updater, keyed on the
   `<!-- x-release-please-version -->` marker).
 
+The standard init agent file `.github/agents/ado-aw.agent.md` is also tracked.
+Note that its `<!-- x-release-please-version -->` markers originate in the
+template `src/data/init-agent.md` (where the version is a `{{ compiler_version }}`
+placeholder substituted at `init` time) and **propagate verbatim** into the
+generated, committed agent file — which is the file release-please actually
+updates. The markers in the template itself are inert (the template is not in
+`extra-files`); they exist solely to carry through to the generated file. A
+parity test (`tests/init_tests.rs`) asserts the generated file stays in sync
+with the template, so do not strip the markers from the template.
+
 > **Maintainer note — adding a version reference to a skill.** Only files that
 > contain a version-pinned URL are listed in `release-please-config.json`
 > `extra-files`. The `compile-and-validate`, `manage-lifecycle`, and
diff --git a/src/init.rs b/src/init.rs
index 20411f2c..02f2db84 100644
--- a/src/init.rs
+++ b/src/init.rs
@@ -188,8 +188,31 @@ async fn write_agency_plugin(base: &Path) -> Result<()> {
 
     // Root marketplace catalogs (written relative to the repo root, not the
     // plugin dir) so `/plugin marketplace add <repo>` can detect the plugin.
+    //
+    // Unlike the plugin files under `agency/plugins/ado-aw/` (which ado-aw owns
+    // and may freely re-scaffold), these root catalogs are shared repo-level
+    // files a consumer might already maintain — e.g. when running `init
+    // --agency` in a repo that is itself a plugin marketplace. Never silently
+    // clobber an existing, differing catalog: skip it with a warning so the
+    // user can merge by hand. Re-writing an identical catalog is a no-op, which
+    // keeps `init --agency` idempotent.
+    let mut wrote_catalog = false;
+    let mut skipped_catalog = false;
     for (rel_path, contents) in AGENCY_MARKETPLACE_FILES {
         let dest = base.join(rel_path);
+
+        if let Ok(existing) = tokio::fs::read_to_string(&dest).await {
+            if existing == *contents {
+                continue; // identical — idempotent no-op
+            }
+            eprintln!(
+                "⚠ Skipped {rel_path}: a different marketplace catalog already exists. \
+                 Merge the `ado-aw` plugin entry into it by hand (see docs/agency-plugin.md)."
+            );
+            skipped_catalog = true;
+            continue;
+        }
+
         let parent = dest.parent().with_context(|| {
             format!("Marketplace catalog has no parent directory: {}", dest.display())
         })?;
@@ -199,12 +222,19 @@ async fn write_agency_plugin(base: &Path) -> Result<()> {
         tokio::fs::write(&dest, contents)
             .await
             .with_context(|| format!("Failed to write marketplace catalog: {}", dest.display()))?;
+        wrote_catalog = true;
     }
 
     println!("✓ Created Agency plugin in {}", plugin_root.display());
-    println!(
-        "✓ Wrote marketplace catalogs (.claude-plugin/, .github/plugin/) — register with: /plugin marketplace add <this repo>"
-    );
+    if wrote_catalog {
+        println!(
+            "✓ Wrote marketplace catalogs (.claude-plugin/, .github/plugin/) — register with: /plugin marketplace add <this repo>"
+        );
+    } else if skipped_catalog {
+        println!(
+            "ℹ Left existing marketplace catalogs untouched — add the `ado-aw` plugin entry manually to register it."
+        );
+    }
 
     Ok(())
 }
diff --git a/tests/init_tests.rs b/tests/init_tests.rs
index 067eb39d..f4a7729e 100644
--- a/tests/init_tests.rs
+++ b/tests/init_tests.rs
@@ -207,9 +207,39 @@ fn test_init_agency_generates_plugin() {
     assert_eq!(parsed["name"], "ado-aw", "plugin.json name should be ado-aw");
 }
 
+/// Recursively collect file paths under `root`, returned relative to `root`
+/// (with forward-slash separators for stable comparison across platforms).
+fn collect_files_rel(root: &std::path::Path) -> Vec<String> {
+    fn walk(dir: &std::path::Path, base: &std::path::Path, out: &mut Vec<String>) {
+        let entries = fs::read_dir(dir)
+            .unwrap_or_else(|e| panic!("read_dir {} failed: {e}", dir.display()));
+        for entry in entries {
+            let path = entry.expect("dir entry").path();
+            if path.is_dir() {
+                walk(&path, base, out);
+            } else {
+                let rel = path
+                    .strip_prefix(base)
+                    .expect("strip_prefix")
+                    .to_string_lossy()
+                    .replace('\\', "/");
+                out.push(rel);
+            }
+        }
+    }
+    let mut out = Vec::new();
+    walk(root, root, &mut out);
+    out.sort();
+    out
+}
+
 /// Test that `init --agency` scaffolds a byte-for-byte copy of the canonical
 /// in-repo plugin (`agency/plugins/ado-aw/`). This guards the single-source-of-
 /// truth invariant: the embedded files and the checked-in files must not drift.
+///
+/// It walks the canonical directory rather than a hardcoded list, so a NEW file
+/// added to `agency/plugins/ado-aw/` that nobody wired into `init.rs`'s embed
+/// list is caught here (it would exist canonically but never be scaffolded).
 #[test]
 fn test_init_agency_matches_canonical_source() {
     let temp_dir = tempfile::tempdir().expect("Failed to create temp directory");
@@ -229,25 +259,20 @@ fn test_init_agency_matches_canonical_source() {
     let canonical = repo_root.join("agency/plugins/ado-aw");
     let scaffolded = temp_dir.path().join("agency/plugins/ado-aw");
 
-    for rel in [
-        ".claude-plugin/plugin.json",
-        ".mcp.json",
-        "agency.json",
-        "README.md",
-        "agents/ado-aw.md",
-        "skills/create-workflow/SKILL.md",
-        "skills/update-workflow/SKILL.md",
-        "skills/debug-workflow/SKILL.md",
-        "skills/compile-and-validate/SKILL.md",
-        "skills/manage-lifecycle/SKILL.md",
-        "skills/audit-build/SKILL.md",
-        "scripts/doctor.sh",
-        "scripts/doctor.ps1",
-    ] {
+    // Every canonical plugin file must be scaffolded byte-for-byte. Walking the
+    // directory (not a fixed list) is what makes a newly-added-but-unwired file
+    // fail loudly instead of silently shipping un-scaffolded.
+    let canonical_files = collect_files_rel(&canonical);
+    assert!(
+        !canonical_files.is_empty(),
+        "canonical plugin dir should contain files"
+    );
+    for rel in &canonical_files {
         let want = fs::read_to_string(canonical.join(rel))
             .unwrap_or_else(|e| panic!("canonical {rel} should be readable: {e}"));
-        let got = fs::read_to_string(scaffolded.join(rel))
-            .unwrap_or_else(|e| panic!("scaffolded {rel} should be readable: {e}"));
+        let got = fs::read_to_string(scaffolded.join(rel)).unwrap_or_else(|e| {
+            panic!("canonical file {rel} was NOT scaffolded by `init --agency` (add it to AGENCY_PLUGIN_FILES in src/init.rs): {e}")
+        });
         assert_eq!(
             got, want,
             "scaffolded {rel} must match the canonical agency/plugins/ado-aw source"
@@ -319,3 +344,114 @@ fn test_init_force_flag_is_advertised_in_help() {
         "init --help should explain that --force bypasses the GitHub-remote guard, got:\n{stdout}"
     );
 }
+
+/// Guard the lock-step versioning invariant: the plugin manifest and both root
+/// marketplace catalogs must carry the same version as the compiler crate.
+///
+/// release-please bumps all of these together via `extra-files`, but if a
+/// release lands while a plugin-touching change is in flight (which has happened),
+/// the literals can desync. This asserts that never reaches `main`.
+#[test]
+fn test_plugin_version_matches_crate_version() {
+    let repo_root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
+    let crate_version = env!("CARGO_PKG_VERSION");
+
+    let read_json = |rel: &str| -> serde_json::Value {
+        let s = fs::read_to_string(repo_root.join(rel))
+            .unwrap_or_else(|e| panic!("{rel} should be readable: {e}"));
+        serde_json::from_str(&s).unwrap_or_else(|e| panic!("{rel} should be valid JSON: {e}"))
+    };
+
+    let plugin = read_json("agency/plugins/ado-aw/.claude-plugin/plugin.json");
+    assert_eq!(
+        plugin["version"], crate_version,
+        "plugin.json version must match Cargo.toml ({crate_version}); release-please \
+         bumps both — resync if a release landed mid-change"
+    );
+
+    for catalog in [
+        ".claude-plugin/marketplace.json",
+        ".github/plugin/marketplace.json",
+    ] {
+        let cat = read_json(catalog);
+        assert_eq!(
+            cat["metadata"]["version"], crate_version,
+            "{catalog} metadata.version must match Cargo.toml ({crate_version})"
+        );
+        assert_eq!(
+            cat["plugins"][0]["version"], crate_version,
+            "{catalog} plugins[0].version must match Cargo.toml ({crate_version})"
+        );
+    }
+}
+
+/// Guard that the committed `.github/agents/ado-aw.agent.md` stays in sync with
+/// its template `src/data/init-agent.md`: running `init` must reproduce the
+/// committed file byte-for-byte. This is what keeps the version-pinned URLs (and
+/// their release-please markers) in the committed file correct, since that file
+/// — not the placeholder-bearing template — is what release-please updates.
+#[test]
+fn test_committed_agent_file_matches_template_output() {
+    let repo_root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
+    let committed = fs::read_to_string(repo_root.join(".github/agents/ado-aw.agent.md"))
+        .expect("committed agent file should be readable");
+
+    let temp_dir = tempfile::tempdir().expect("Failed to create temp directory");
+    let output = ado_aw_bin()
+        .args(["init", "--path", temp_dir.path().to_str().unwrap()])
+        .output()
+        .expect("Failed to run ado-aw init");
+    assert!(output.status.success(), "init should succeed");
+
+    let generated = fs::read_to_string(temp_dir.path().join(".github/agents/ado-aw.agent.md"))
+        .expect("generated agent file should be readable");
+
+    assert_eq!(
+        generated.replace("\r\n", "\n"),
+        committed.replace("\r\n", "\n"),
+        "committed .github/agents/ado-aw.agent.md is stale — regenerate it with \
+         `ado-aw init --force` after editing src/data/init-agent.md"
+    );
+}
+
+/// `init --agency` must NOT clobber a consumer's pre-existing, differing root
+/// marketplace catalog. It should leave the existing file untouched and still
+/// scaffold the plugin tree.
+#[test]
+fn test_init_agency_does_not_clobber_existing_catalog() {
+    let temp_dir = tempfile::tempdir().expect("Failed to create temp directory");
+
+    // Simulate a consumer that already maintains a Claude marketplace catalog.
+    let catalog_dir = temp_dir.path().join(".claude-plugin");
+    fs::create_dir_all(&catalog_dir).expect("create .claude-plugin");
+    let catalog = catalog_dir.join("marketplace.json");
+    let sentinel = "{\n  \"name\": \"consumer-owned\",\n  \"plugins\": []\n}\n";
+    fs::write(&catalog, sentinel).expect("write pre-existing catalog");
+
+    let output = ado_aw_bin()
+        .args([
+            "init",
+            "--agency",
+            "--path",
+            temp_dir.path().to_str().unwrap(),
+        ])
+        .output()
+        .expect("Failed to run ado-aw init --agency");
+    assert!(output.status.success(), "init --agency should still succeed");
+
+    // The consumer's catalog must be left exactly as it was.
+    let after = fs::read_to_string(&catalog).expect("catalog should still be readable");
+    assert_eq!(
+        after, sentinel,
+        "existing root catalog must not be clobbered by init --agency"
+    );
+
+    // The plugin tree is still scaffolded regardless.
+    assert!(
+        temp_dir
+            .path()
+            .join("agency/plugins/ado-aw/.claude-plugin/plugin.json")
+            .exists(),
+        "plugin tree should still be scaffolded even when a root catalog pre-exists"
+    );
+}

From 97b0ac3ff6d9003240285bb3caeb62ef3c716571 Mon Sep 17 00:00:00 2001
From: James Devine <devinejames@microsoft.com>
Date: Wed, 24 Jun 2026 22:39:28 +0100
Subject: [PATCH 10/10] fix(init): correct summary line when catalogs are
 partially written
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The wrote_catalog/skipped_catalog booleans were reported with `if/else if`, so
the mixed case (one root catalog written, one pre-existing one skipped) printed
the "✓ Wrote marketplace catalogs" line and falsely implied both were written,
contradicting the per-file skip warning. Replace with an exhaustive match over
(wrote, skipped) including a dedicated mixed-case message. Extend
test_init_agency_does_not_clobber_existing_catalog to assert the stderr skip
warning, the corrected stdout summary, and that the non-pre-existing catalog is
still written.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 src/init.rs         | 17 +++++++++++------
 tests/init_tests.rs | 22 ++++++++++++++++++++++
 2 files changed, 33 insertions(+), 6 deletions(-)

diff --git a/src/init.rs b/src/init.rs
index 02f2db84..efe94b0b 100644
--- a/src/init.rs
+++ b/src/init.rs
@@ -226,14 +226,19 @@ async fn write_agency_plugin(base: &Path) -> Result<()> {
     }
 
     println!("✓ Created Agency plugin in {}", plugin_root.display());
-    if wrote_catalog {
-        println!(
+    match (wrote_catalog, skipped_catalog) {
+        (true, false) => println!(
             "✓ Wrote marketplace catalogs (.claude-plugin/, .github/plugin/) — register with: /plugin marketplace add <this repo>"
-        );
-    } else if skipped_catalog {
-        println!(
+        ),
+        (true, true) => println!(
+            "✓ Wrote one marketplace catalog; left a pre-existing one untouched (see warning above) — merge the `ado-aw` plugin entry into it to register."
+        ),
+        (false, true) => println!(
             "ℹ Left existing marketplace catalogs untouched — add the `ado-aw` plugin entry manually to register it."
-        );
+        ),
+        // No catalogs written and none skipped means every catalog already
+        // matched ours exactly (idempotent re-run): nothing to report.
+        (false, false) => {}
     }
 
     Ok(())
diff --git a/tests/init_tests.rs b/tests/init_tests.rs
index f4a7729e..b7f0e95f 100644
--- a/tests/init_tests.rs
+++ b/tests/init_tests.rs
@@ -454,4 +454,26 @@ fn test_init_agency_does_not_clobber_existing_catalog() {
             .exists(),
         "plugin tree should still be scaffolded even when a root catalog pre-exists"
     );
+
+    // The other catalog (.github/plugin/) had no pre-existing file, so it IS
+    // written — this is the mixed (wrote one, skipped one) case. The user-facing
+    // output must reflect both: a skip warning on stderr and a summary line that
+    // does NOT falsely claim both catalogs were written.
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(
+        stderr.contains("Skipped .claude-plugin/marketplace.json"),
+        "stderr should warn about the skipped pre-existing catalog, got:\n{stderr}"
+    );
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert!(
+        stdout.contains("left a pre-existing one untouched"),
+        "stdout summary must acknowledge the skipped catalog, not claim both were written, got:\n{stdout}"
+    );
+    assert!(
+        temp_dir
+            .path()
+            .join(".github/plugin/marketplace.json")
+            .exists(),
+        "the non-pre-existing catalog should still be written"
+    );
 }
