From 72be873953489c8cf95d8c1add2390ef45b0fa17 Mon Sep 17 00:00:00 2001 From: danielmeppiel Date: Thu, 12 Mar 2026 10:03:56 +0100 Subject: [PATCH 1/2] docs: position apm compile as optional across all pages Sweep compile messaging to reflect that apm install is the primary command for Copilot and Claude (which read deployed primitives natively), while apm compile is only needed for Cursor, Codex, Gemini, and other tools without native APM integration. Pages updated: - why-apm: qualify compile as bridge feature, not core - how-it-works: clarify native vs compiled tool support - first-package: mark compile step as optional - ci-cd: comment out compile in CI examples, add opt-in notes - ide-tool-integration: reframe compile sections as optional - github-rulesets: qualify compile CI steps - teams: clarify compile role in mid-size team workflows - adoption-playbook: comment out compile in CI phase Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../docs/enterprise/adoption-playbook.md | 6 +- docs/src/content/docs/enterprise/teams.md | 4 +- .../docs/getting-started/first-package.md | 6 +- docs/src/content/docs/integrations/ci-cd.md | 31 +++-- .../docs/integrations/github-rulesets.md | 11 +- .../docs/integrations/ide-tool-integration.md | 131 +++--------------- .../content/docs/introduction/how-it-works.md | 83 ++++++----- docs/src/content/docs/introduction/why-apm.md | 8 +- 8 files changed, 102 insertions(+), 178 deletions(-) diff --git a/docs/src/content/docs/enterprise/adoption-playbook.md b/docs/src/content/docs/enterprise/adoption-playbook.md index 1cf91fcf..27d57da4 100644 --- a/docs/src/content/docs/enterprise/adoption-playbook.md +++ b/docs/src/content/docs/enterprise/adoption-playbook.md @@ -119,8 +119,10 @@ reach production. - name: Install APM packages run: apm install - - name: Compile configuration - run: apm compile + # Optional: only needed if targeting Cursor, Codex, Gemini, or other + # tools without native APM integration + # - name: Compile configuration + # run: apm compile - name: Audit for drift run: apm audit --ci diff --git a/docs/src/content/docs/enterprise/teams.md b/docs/src/content/docs/enterprise/teams.md index 030e7434..9dece5a2 100644 --- a/docs/src/content/docs/enterprise/teams.md +++ b/docs/src/content/docs/enterprise/teams.md @@ -93,7 +93,7 @@ Configuration is ready. Updates are a pull request to `apm.yml`. A mid-size organization maintains three layers of configuration: organization-wide security rules, team-specific coding standards, and project-level context. Different teams need different combinations. -APM composes these layers through its dependency model. The organization publishes shared packages. Each team's `apm.yml` references the org packages it needs alongside team and project packages. Compilation merges them in the correct order. +APM composes these layers through its dependency model. The organization publishes shared packages. Each team's `apm.yml` references the org packages it needs alongside team and project packages. `apm install` deploys them for Copilot and Claude natively; `apm compile` can merge them into instruction files for other tools. ```yaml packages: @@ -152,5 +152,5 @@ For hands-on setup and deeper topics, start here: - [Quick Start](../../getting-started/installation/) — install APM and configure your first project in five minutes. - [Organization-Wide Packages](../../guides/org-packages/) — publish and maintain shared configuration packages across your organization. -- [Compilation Guide](../../guides/compilation/) — understand how APM merges and transforms configuration from multiple sources. +- [Compilation Guide](../../guides/compilation/) — optional: generate instruction files for tools without native APM integration (Cursor, Codex, Gemini). - [Dependencies Guide](../../guides/dependencies/) — version constraints, lock file mechanics, and update workflows. diff --git a/docs/src/content/docs/getting-started/first-package.md b/docs/src/content/docs/getting-started/first-package.md index bd90ad7d..94f08f66 100644 --- a/docs/src/content/docs/getting-started/first-package.md +++ b/docs/src/content/docs/getting-started/first-package.md @@ -103,15 +103,15 @@ APM automatically: - Copies prompts to `.github/prompts/` - Updates `apm.yml` with the dependency -## 7. Compile +## 7. Optional: Compile for Other Tools -Generate the compiled context files: +If you use tools beyond GitHub Copilot and Claude (which read deployed primitives natively), generate compiled instruction files: ```bash apm compile ``` -This produces `AGENTS.md` (for Copilot, Cursor, Codex) and `CLAUDE.md` (for Claude) with all your instructions optimized for each agent. +This produces `AGENTS.md` (for Cursor, Codex) and `CLAUDE.md` for tools that need a single instructions file. Copilot and Claude users can skip this step. ## Next Steps diff --git a/docs/src/content/docs/integrations/ci-cd.md b/docs/src/content/docs/integrations/ci-cd.md index ac3e382e..4c61eabc 100644 --- a/docs/src/content/docs/integrations/ci-cd.md +++ b/docs/src/content/docs/integrations/ci-cd.md @@ -1,11 +1,11 @@ --- title: "APM in CI/CD" -description: "Automate APM install and compile in GitHub Actions, Azure Pipelines, and other CI systems." +description: "Automate APM install in GitHub Actions, Azure Pipelines, and other CI systems." sidebar: order: 1 --- -APM integrates into your CI/CD pipeline to ensure agent context is always up to date and compiled correctly. +APM integrates into your CI/CD pipeline to ensure agent context is always up to date. ## GitHub Actions @@ -20,17 +20,19 @@ on: pull_request: jobs: - compile: + install: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - - name: Install APM & compile + - name: Install APM packages uses: microsoft/apm-action@v1 with: commands: | apm install - apm compile --verbose + # Optional: only needed if targeting Cursor, Codex, Gemini, or other + # tools without native APM integration + # apm compile --verbose ``` ### Private Dependencies @@ -38,19 +40,18 @@ jobs: For private repositories, pass a GitHub token: ```yaml - - name: Install APM & compile + - name: Install APM packages uses: microsoft/apm-action@v1 with: commands: | apm install - apm compile env: GITHUB_APM_PAT: ${{ secrets.APM_PAT }} ``` -### Verify Compiled Output +### Verify Compiled Output (Optional) -Add a check to ensure `AGENTS.md` stays in sync with `apm.yml`: +If your project uses `apm compile` to target tools like Cursor, Codex, or Gemini, add a check to ensure compiled output stays in sync: ```yaml - name: Check for drift @@ -60,6 +61,8 @@ Add a check to ensure `AGENTS.md` stays in sync with `apm.yml`: (echo "Compiled output is out of date. Run 'apm compile' locally." && exit 1) ``` +This step is not needed if your team only uses GitHub Copilot and Claude, which read deployed primitives natively. + ## Azure Pipelines ```yaml @@ -67,8 +70,9 @@ steps: - script: | curl -sSL https://raw.githubusercontent.com/microsoft/apm/main/install.sh | sh apm install - apm compile - displayName: 'APM Install & Compile' + # Optional: only if targeting Cursor, Codex, Gemini, or similar tools + # apm compile + displayName: 'APM Install' env: ADO_APM_PAT: $(ADO_PAT) ``` @@ -80,7 +84,8 @@ For any CI system with Python available: ```bash pip install apm-cli apm install -apm compile --verbose +# Optional: only if targeting Cursor, Codex, Gemini, or similar tools +# apm compile --verbose ``` ## Governance with `apm audit` @@ -148,5 +153,5 @@ See the [Pack & Distribute guide](../../guides/pack-distribute/) for the full wo - **Pin APM version** in CI to avoid unexpected changes: `pip install apm-cli==0.7.7` - **Commit `apm.lock`** so CI resolves the same dependency versions as local development -- **Run `apm compile` in CI** and fail the build if the output differs from what's committed — this catches drift early +- **If using `apm compile`** (for Cursor, Codex, Gemini), run it in CI and fail the build if the output differs from what's committed - **Use `GITHUB_APM_PAT`** for private dependencies; never use the default `GITHUB_TOKEN` for cross-repo access diff --git a/docs/src/content/docs/integrations/github-rulesets.md b/docs/src/content/docs/integrations/github-rulesets.md index aca5b69a..d36eea1b 100644 --- a/docs/src/content/docs/integrations/github-rulesets.md +++ b/docs/src/content/docs/integrations/github-rulesets.md @@ -111,16 +111,17 @@ jobs: commands: | apm install apm audit --ci - apm compile - git diff --exit-code AGENTS.md || \ - (echo "Compiled output is out of date. Run 'apm compile' locally." && exit 1) + # Optional: only needed if targeting Cursor, Codex, Gemini, or similar + # apm compile + # git diff --exit-code AGENTS.md || \ + # (echo "Compiled output is out of date. Run 'apm compile' locally." && exit 1) env: GITHUB_APM_PAT: ${{ secrets.APM_PAT }} ``` ### Separate Jobs for Granular Status -If you want audit and compile as separate required checks, split them into distinct jobs: +If your project uses `apm compile` (for Cursor, Codex, Gemini, or other tools without native APM integration), you can add audit and compile as separate required checks: ```yaml jobs: @@ -147,7 +148,7 @@ jobs: apm compile --verbose ``` -This lets you require both `audit` and `compile` as independent status checks in your ruleset. +This lets you require both `audit` and `compile` as independent status checks in your ruleset. The compile job is only needed if your project targets tools that require compiled instruction files. ## Troubleshooting diff --git a/docs/src/content/docs/integrations/ide-tool-integration.md b/docs/src/content/docs/integrations/ide-tool-integration.md index 57e972b1..117a9423 100644 --- a/docs/src/content/docs/integrations/ide-tool-integration.md +++ b/docs/src/content/docs/integrations/ide-tool-integration.md @@ -23,22 +23,22 @@ APM provides the infrastructure layer for AI development: When using Spec-kit for Specification-Driven Development (SDD), APM automatically integrates the Spec-kit constitution: -- **Constitution Injection**: APM automatically injects the Spec-kit `constitution.md` into the compiled context layer (`AGENTS.md`) +- **Constitution Injection**: When using `apm compile`, APM injects the Spec-kit `constitution.md` into the compiled instruction files (`AGENTS.md`) - **Rule Enforcement**: All coding agents respect the non-negotiable rules governing your project -- **Contextual Augmentation**: APM embeds your team's context modules into `AGENTS.md` after Spec-kit's constitution +- **Contextual Augmentation**: Compiled output embeds your team's context modules after Spec-kit's constitution - **SDD Enhancement**: Augments the Spec Driven Development process with additional context curated by your teams ### Integrated Workflow ```bash # 1. Set up APM contextual foundation -apm init my-project && apm compile +apm init my-project && apm install -# 2. Use Spec-kit for specification-driven development -# Spec-kit constitution is automatically included in AGENTS.md +# 2. Optional: compile for tools without native integration (Cursor, Codex, Gemini) +# Spec-kit constitution is automatically included in compiled AGENTS.md +apm compile -# 3. Run AI workflows with both SDD rules and team context -apm run implement-feature --param spec="user-auth" --param approach="sdd" +# 3. AI workflows use both SDD rules and team context ``` **Key Benefits of Integration**: @@ -47,102 +47,9 @@ apm run implement-feature --param spec="user-auth" --param approach="sdd" - **Flexible Workflows**: Also works with traditional prompting and vibe coding - **Team Knowledge**: Combines constitutional rules with team-specific context -## Supported AI Runtimes - -APM manages AI runtime installation and provides seamless integration with multiple coding agents: - -### OpenAI Codex CLI - -Terminal-native coding agent with GitHub Models support: - -```bash -# Install and configure -apm runtime setup codex -``` - -Codex reads primitives from `.github/` (instructions, agents, prompts, skills) the same way GitHub Copilot does. APM also configures MCP servers for Codex at `~/.codex/config.toml`. - -**Features**: -- GitHub Models API backend -- Terminal-native workflow -- Real-time streaming output -- Native MCP server support -- Automatic `.github/` primitive discovery +## Running Agentic Workflows -**Best for**: Teams preferring terminal workflows, custom model configurations - -### GitHub Copilot CLI - -GitHub's Copilot agent for the terminal: - -```bash -# Install and configure -apm runtime setup copilot -``` - -**Features**: -- Native MCP server integration via `~/.copilot/mcp-config.json` -- Multi-model switching -- Advanced prompt engineering support -- `--allow-all-tools` and `--add-dir` options - -**Best for**: Teams using GitHub Copilot across IDE and terminal - -**Configuration**: -```yaml -runtime: - copilot: - model: "github/gpt-4o-mini" - provider: "github-models" - api_base: "https://models.github.ai" -``` - -### LLM Library - -Flexible runtime supporting multiple model providers: - -```bash -# Install and configure -apm runtime setup llm - -# Features -- Multiple model providers (OpenAI, Anthropic, Ollama) -- Local model support -- Custom plugin system -- Advanced configuration options -- Cost optimization features -``` - -**Best for**: Teams needing model flexibility, local development, cost optimization, custom integrations - -**Configuration**: -```yaml -runtime: - llm: - default_model: "gpt-4" - providers: - - openai - - ollama - - anthropic - local_models: - - "llama3:8b" - cost_limits: - daily_max: "$50" -``` - -### Verify Installation - -Check what runtimes are available and properly configured: - -```bash -# List installed runtimes -apm runtime list - -# Test runtime functionality -apm runtime test copilot -apm runtime test codex -apm runtime test llm -``` +For running agentic workflows locally, see the [Agent Workflows guide](../../guides/agent-workflows/). ## VS Code Integration @@ -239,9 +146,9 @@ apm install microsoft/apm-sample-package - File-pattern based instruction application - Agent support for different personas and workflows -### Compiled Context with AGENTS.md +### Optional: Compiled Context with AGENTS.md -In addition to file-level integration, `apm compile` produces an `AGENTS.md` file that provides comprehensive project context. This is useful for older Copilot versions or IDEs that do not support granular `.github/` primitive discovery. +For tools that do not support granular `.github/` primitive discovery (such as Cursor, Codex, or Gemini), `apm compile` produces an `AGENTS.md` file that merges instructions into a single document. This is not needed for GitHub Copilot or Claude, which read deployed primitives natively. ```bash # Compile all local and dependency instructions into AGENTS.md @@ -260,13 +167,13 @@ APM provides first-class support for Claude Code and Claude Desktop through nati > **Auto-Detection**: Claude integration is automatically enabled when a `.claude/` folder exists in your project. If neither `.github/` nor `.claude/` exists, `apm install` skips folder integration (packages are still installed to `apm_modules/`). -### Output Files for Claude +### Optional: Compiled Output for Claude -When you run `apm compile`, APM generates Claude-native files: +Running `apm compile` is optional for Claude Code, which reads deployed primitives natively via `apm install`. If you want a single `CLAUDE.md` instruction file (for example, for Claude Desktop), you can generate one: | File | Purpose | |------|---------| -| `CLAUDE.md` | Project instructions for Claude (instructions only, using `@import` syntax) | +| `CLAUDE.md` | Merged project instructions for Claude (instructions only, using `@import` syntax) | When you run `apm install`, APM integrates package primitives into Claude's native structure: @@ -361,9 +268,9 @@ apm install anthropics/claude-plugins-official/plugins/hookify 5. Rewrites `${CLAUDE_PLUGIN_ROOT}` and relative script paths for the target platform 6. `apm uninstall` removes hook files and cleans up merged settings -### Target-Specific Compilation +### Optional: Target-Specific Compilation -Generate only Claude formats when needed: +Compilation is optional for Copilot and Claude, which read deployed primitives natively. Use it when targeting tools like Cursor, Codex, or Gemini, or when you want a single merged instruction file: ```bash # Generate all formats (default) @@ -401,8 +308,8 @@ Review the current design for accessibility and UI standards. apm install microsoft/apm-sample-package apm install github/awesome-copilot/skills/review-and-refactor -# 2. Compile instructions for Claude -apm compile --target claude +# 2. Optional: compile instructions if not using Claude Code natively +# apm compile --target claude # 3. In Claude Code, use: # /code-review -- Runs the code review workflow @@ -417,7 +324,7 @@ apm compile --target claude Skills installed to `.github/skills/` are the primary location; when a `.claude/` directory exists, APM also copies skills to `.claude/skills/` for compatibility. Each skill folder contains a `SKILL.md` that defines the skill's capabilities and any supporting files. -Claude Desktop can use `CLAUDE.md` as its project instructions file. Run `apm compile --target claude` to generate `CLAUDE.md` with `@import` syntax for organized instruction loading. +Claude Desktop can use `CLAUDE.md` as its project instructions file. Optionally run `apm compile --target claude` to generate `CLAUDE.md` with `@import` syntax for organized instruction loading. ### Cleanup and Sync diff --git a/docs/src/content/docs/introduction/how-it-works.md b/docs/src/content/docs/introduction/how-it-works.md index 464ffbc6..b9529ca3 100644 --- a/docs/src/content/docs/introduction/how-it-works.md +++ b/docs/src/content/docs/introduction/how-it-works.md @@ -10,16 +10,16 @@ APM implements the complete [AI-Native Development framework](https://danielmepp Most developers experience AI as inconsistent and unreliable: -- ❌ **Ad-hoc prompting** that produces different results each time -- ❌ **Context overload** that confuses AI agents and wastes tokens -- ❌ **Vendor lock-in** to specific AI tools and platforms -- ❌ **No knowledge persistence** across sessions and team members +- **Ad-hoc prompting** that produces different results each time +- **Context overload** that confuses AI agents and wastes tokens +- **Vendor lock-in** to specific AI tools and platforms +- **No knowledge persistence** across sessions and team members **APM solves this** by implementing the complete 3-layer AI-Native Development framework: -**🔧 Layer 1: Markdown Prompt Engineering** - Structured, repeatable AI instructions -**⚙️ Layer 2: Context** - Configurable tools that deploy prompt + context engineering -**🎯 Layer 3: Context Engineering** - Strategic LLM memory management for reliability +**Layer 1: Markdown Prompt Engineering** - Structured, repeatable AI instructions +**Layer 2: Context** - Configurable tools that deploy prompt + context engineering +**Layer 3: Context Engineering** - Strategic LLM memory management for reliability **Result**: Transform from supervising every AI interaction to architecting systems that delegate complete workflows to AI agents. @@ -29,7 +29,7 @@ Most developers experience AI as inconsistent and unreliable: Most developers start by manually supervising every AI interaction. APM enables the transformation to AI-Native engineering: -### 🔴 Before APM: Manual Agent Supervision +### Before APM: Manual Agent Supervision The traditional approach requires constant developer attention: @@ -42,7 +42,7 @@ The traditional approach requires constant developer attention: *You're the bottleneck - every AI task needs your personal attention and guidance.* -### 🟢 With APM: Engineered Agent Delegation +### With APM: Engineered Agent Delegation APM transforms AI from a supervised tool to an engineered system: @@ -76,11 +76,11 @@ Just as npm revolutionized JavaScript by creating package ecosystem infrastructu ### Key Benefits -**🎯 Reliable Results** - Replace trial-and-error with proven AI-Native Development patterns -**🔄 Universal Portability** - Works with any coding agent through the agents.md standard -**📦 Knowledge Packaging** - Share AI workflows like code packages with versioning -**🧠 Compound Intelligence** - Primitives improve through iterative team refinement -**⚡ Team Scaling** - Transform any project for reliable AI-Native Development workflows +**Reliable Results** - Replace trial-and-error with proven AI-Native Development patterns +**Universal Portability** - Works with any coding agent through the agents.md standard +**Knowledge Packaging** - Share AI workflows like code packages with versioning +**Compound Intelligence** - Primitives improve through iterative team refinement +**Team Scaling** - Transform any project for reliable AI-Native Development workflows ## Architecture Overview @@ -88,18 +88,18 @@ APM implements a complete system architecture that bridges the gap between human ```mermaid graph TD - A["📝 Context
.apm/ directory
(.chatmode, .instructions, .prompt, .context)"] --> B["🔧 APM CLI"] + A["Context
.apm/ directory
(.chatmode, .instructions, .prompt, .context)"] --> B["APM CLI"] - B --> D["📦 APM Package Manager
Dependencies
Templates"] - B --> C["⚙️ APM Context Compiler
Script Resolution
Primitive Compilation"] - B --> E["🏗️ APM Runtime Manager
Install & Configure
Codex, LLM, etc."] + B --> D["APM Package Manager
Dependencies
Templates"] + B --> C["APM Context Compiler
Script Resolution
Primitive Compilation"] + B --> E["APM Runtime Manager
Install & Configure
Codex, LLM, etc."] - C --> F["📄 AGENTS.md
Portable Standard
Cross-Runtime Compatible"] + C --> F["AGENTS.md
Portable Standard
Cross-Runtime Compatible"] - F --> G["⚡ AI Coding Agents
Codex CLI,
llm, ."] + F --> G["AI Coding Agents
Codex CLI,
llm, ."] - E --> H["🛠️ MCP Servers
Tool Integration"] - E --> I["🧠 LLM Models
GitHub Models
Ollama, etc."] + E --> H["MCP Servers
Tool Integration"] + E --> I["LLM Models
GitHub Models
Ollama, etc."] style A fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,color:#000 style B fill:#f3e5f5,stroke:#7b1fa2,stroke-width:3px,color:#000 @@ -123,7 +123,7 @@ graph TD 4. **AI Coding Agents** - Execute your compiled workflows (Copilot, Cursor, etc.) 5. **Supporting Infrastructure** - MCP servers for tools, LLM models for execution -The compiled `agents.md` file ensures your Context work with any coding agent - from GitHub Copilot to Cursor, Codex to Aider. +GitHub Copilot and Claude read the deployed primitives natively. For other tools (Cursor, Codex, Gemini), `apm compile` generates an `agents.md` instruction file they can consume. ## The Three Layers Explained @@ -131,9 +131,9 @@ The compiled `agents.md` file ensures your Context work with any coding agent - Transform ad-hoc prompts into structured, repeatable instructions using markdown format: -**❌ Traditional**: "Add authentication to the API" +**Traditional**: "Add authentication to the API" -**✅ Engineered**: +**Engineered**: ```markdown # Secure Authentication Implementation @@ -149,7 +149,7 @@ Transform ad-hoc prompts into structured, repeatable instructions using markdown 4. Add logout functionality ## Validation Gates -🚨 **STOP**: Security review required before deployment +**STOP**: Security review required before deployment ``` ### Layer 2: Context @@ -253,21 +253,30 @@ Lifecycle event handlers that run scripts at specific points during AI operation } ``` -## Universal Compatibility +## Compatibility -APM generates context files for all major coding agents: +APM supports coding agents at two levels: **native integration** for tools with rich primitive support, and **compiled instructions** for tools that consume a single instructions file. -**Copilot Target** (AGENTS.md + .github/): -- **GitHub Copilot** - VSCode integration, chat, and CLI -- **Cursor** - AI-first code editor -- **Codex CLI** - OpenAI's development tool -- **Gemini** - Google's AI assistant +### Native integration -**Claude Target** (CLAUDE.md + .claude/): -- **Claude Code** - Anthropic's coding assistant -- **Claude Desktop** - Desktop application +These tools support the full set of APM primitives. Running `apm install` deploys instructions, prompts, agents, skills, context, MCP configuration, and hooks directly into each tool's native format. -APM auto-detects your target based on project structure (`.github/` or `.claude/` folders) and generates the appropriate format. This ensures your investment in primitives works regardless of which AI tools your team chooses. +- **GitHub Copilot** (AGENTS.md + .github/) - instructions, prompts, chat modes, context, hooks, MCP +- **Claude Code** (CLAUDE.md + .claude/) - commands, skills, MCP configuration + +APM auto-detects the target based on project structure (`.github/` or `.claude/` folders) and deploys the appropriate primitives. + +### Compiled instructions + +For tools that read a single instructions file, `apm compile` merges your primitives into a portable document the tool can consume. This gives you instruction-level support rather than full primitive integration. + +- **Cursor** - compiled to `.cursor/rules/` +- **Codex CLI** - compiled to `AGENTS.md` +- **Gemini** - compiled to `GEMINI.md` + +See the [Compilation guide](../../guides/compilation/) for details on output formats and options. + +Your investment in primitives is portable: full primitive support for Copilot and Claude, instruction-level support for other tools via compilation. ## Learn the Complete Framework diff --git a/docs/src/content/docs/introduction/why-apm.md b/docs/src/content/docs/introduction/why-apm.md index 0bbc4fd0..811ea846 100644 --- a/docs/src/content/docs/introduction/why-apm.md +++ b/docs/src/content/docs/introduction/why-apm.md @@ -35,8 +35,8 @@ dependencies: Run `apm install` and APM: - **Resolves transitive dependencies** — if package A depends on package B, both are installed automatically. -- **Integrates primitives** — instructions go to `.github/instructions/`, prompts to `.github/prompts/`, skills to `.github/skills/`. -- **Compiles context** — `apm compile` produces optimized `AGENTS.md` and `CLAUDE.md` files for every major AI coding agent. +- **Integrates primitives** — instructions go to `.github/instructions/`, prompts to `.github/prompts/`, skills to `.github/skills/`. GitHub Copilot and Claude read these natively. +- **Bridges other tools** — for Cursor, Codex, Gemini, and other tools without native integration, `apm compile` generates compatible instruction files (`AGENTS.md`, `CLAUDE.md`). ## APM vs. Manual Setup @@ -62,7 +62,7 @@ git clone my-project && cd my-project ```bash git clone my-project && cd my-project apm install -# Done. All 5 plugins resolved, installed, and compiled. +# Done. All 5 plugins resolved and installed. ``` | | Without APM | With APM | @@ -100,7 +100,7 @@ All declared in one manifest. All installed with one command. ## Design Principles - **Familiar** — APM works like the package managers you already know. -- **Fast** — install, compile, and run in seconds. +- **Fast** — install and run in seconds. - **Open** — built on [AGENTS.md](https://agents.md), [Agent Skills](https://agentskills.io), and [MCP](https://modelcontextprotocol.io). - **Portable** — install from GitHub, GitLab, Bitbucket, Azure DevOps, or any git host. From a038f2854c88cc63bc28366440dcd5f8257e1138 Mon Sep 17 00:00:00 2001 From: danielmeppiel Date: Thu, 12 Mar 2026 10:05:31 +0100 Subject: [PATCH 2/2] docs: narrative redesign for accuracy and cohesion - Rewrite quick-start as 3-minute install-focused flow (no compile step) - Rewrite installation page from 527 to 119 lines (install-only) - Reconceptualize migration page as lightweight adoption guide - Create agent-workflows.md consolidating apm run/runtime (experimental) - Rewrite gh-aw integration with real frontmatter dependencies syntax - Reposition apm compile as optional bridge for non-Copilot/Claude tools - Fix tools support claims: Full (Copilot/Claude) vs Instructions-only - Add pack/unpack to lifecycle, fix governance/making-the-case commands - Clean up apm run/runtime references across 6 pages - Remove emojis from all documentation pages - Refactor prompts guide to focus on primitive, not execution - Sweep compile messaging across enterprise/CI/integration pages - Update sidebar: rename Migration to Existing Projects, add Agent Workflows - Fix landing CTA to point to quick-start Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/astro.config.mjs | 3 +- .../src/content/docs/enterprise/governance.md | 14 +- .../docs/enterprise/making-the-case.md | 8 +- .../docs/getting-started/authentication.md | 10 +- .../docs/getting-started/installation.md | 495 ++---------------- .../content/docs/getting-started/migration.md | 167 +----- .../docs/getting-started/quick-start.md | 183 +++---- .../content/docs/guides/agent-workflows.md | 246 +++++++++ docs/src/content/docs/guides/compilation.md | 47 +- docs/src/content/docs/guides/dependencies.md | 1 - docs/src/content/docs/guides/prompts.md | 168 +----- docs/src/content/docs/index.mdx | 2 +- docs/src/content/docs/integrations/gh-aw.md | 157 +++--- .../integrations/runtime-compatibility.md | 2 + .../content/docs/introduction/key-concepts.md | 13 +- .../content/docs/introduction/what-is-apm.md | 30 +- .../content/docs/reference/cli-commands.md | 10 +- docs/src/content/docs/reference/examples.md | 2 + 18 files changed, 556 insertions(+), 1002 deletions(-) create mode 100644 docs/src/content/docs/guides/agent-workflows.md diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 36ee8e10..3f39170f 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -55,7 +55,7 @@ export default defineConfig({ { label: 'Quick Start', slug: 'getting-started/quick-start' }, { label: 'Your First Package', slug: 'getting-started/first-package' }, { label: 'Authentication', slug: 'getting-started/authentication' }, - { label: 'Migrating Projects', slug: 'getting-started/migration' }, + { label: 'Existing Projects', slug: 'getting-started/migration' }, ], }, { @@ -68,6 +68,7 @@ export default defineConfig({ { label: 'Dependencies & Lockfile', slug: 'guides/dependencies' }, { label: 'Pack & Distribute', slug: 'guides/pack-distribute' }, { label: 'Org-Wide Packages', slug: 'guides/org-packages' }, + { label: 'Agent Workflows (Experimental)', slug: 'guides/agent-workflows' }, ], }, { diff --git a/docs/src/content/docs/enterprise/governance.md b/docs/src/content/docs/enterprise/governance.md index d503e249..f53a6bde 100644 --- a/docs/src/content/docs/enterprise/governance.md +++ b/docs/src/content/docs/enterprise/governance.md @@ -102,6 +102,10 @@ No additional tooling is required. The lock file turns git into an agent configu ## CI enforcement with `apm audit --ci` +:::note[Planned Feature] +`apm audit --ci` is not yet available. The following describes planned behavior and is provided to illustrate the intended workflow. +::: + The `apm audit --ci` command is designed to run as a required status check in your CI pipeline. It verifies that the lock file is in sync with the declared manifest and that deployed files match expectations. ### What it catches @@ -151,6 +155,10 @@ This ensures every merge to a protected branch has a verified, consistent agent ## Drift detection with `apm audit --drift` +:::note[Planned Feature] +`apm audit --drift` is not yet available. The following describes planned behavior and is provided to illustrate the intended workflow. +::: + Drift occurs when the on-disk state of agent configuration diverges from what the lock file declares. The `apm audit --drift` command detects this divergence. ### What drift detection catches @@ -274,9 +282,9 @@ This ensures that organizational rules are consistently applied across all teams GitHub Rulesets provide a scalable way to enforce APM governance across multiple repositories. -### Level 1: Required status check (available now) +### Level 1: Required status check -Configure `apm audit --ci` as a required status check through Rulesets: +Once `apm audit --ci` is available (see [CI enforcement](#ci-enforcement-with-apm-audit---ci) above), configure it as a required status check through Rulesets: 1. Create a new Ruleset at the organization or repository level. 2. Target the branches you want to protect (e.g., `main`, `release/*`). @@ -325,7 +333,7 @@ APM enforces change management by design: 1. **Declaration.** Changes start in `apm.yml`, which is a committed, reviewable file. 2. **Resolution.** `apm install` resolves declarations to exact commits in `apm.lock`. 3. **Review.** Both files are included in the PR diff for peer review. -4. **Verification.** `apm audit --ci` confirms consistency before merge. +4. **Verification.** `apm audit --ci` confirms consistency before merge (planned — currently achieved through PR review of `apm.lock` diffs). 5. **Traceability.** Git history provides a permanent record of who changed what and when. No agent configuration change can reach a protected branch without passing through this pipeline. diff --git a/docs/src/content/docs/enterprise/making-the-case.md b/docs/src/content/docs/enterprise/making-the-case.md index 70686f63..9a182dc1 100644 --- a/docs/src/content/docs/enterprise/making-the-case.md +++ b/docs/src/content/docs/enterprise/making-the-case.md @@ -35,7 +35,7 @@ An internal advocacy toolkit for APM. Each section is self-contained and designe ### For Platform Teams - **Standardize AI configuration across N repos.** Publish a shared APM package with your organization's coding standards, approved MCP servers, and prompt templates. Every repo that depends on it stays in sync. -- **Enforce standards via CI gates.** Add `apm install --check` to your CI pipeline. Builds fail if agent configuration has drifted from the declared manifest. +- **Enforce standards via CI gates.** APM's planned `apm audit --ci` command will gate pull requests when agent configuration drifts from the declared manifest, enabling automated enforcement in your CI pipeline. - **Version-controlled standards updates.** When standards change, update the shared package and bump the version. Teams adopt updates through normal dependency management, not ad-hoc communication. ### For Individual Developers @@ -54,7 +54,7 @@ Plugins handle single-tool installation for a single AI platform. APM adds capab - **Cross-tool composition.** One manifest manages configuration for Copilot, Claude, Cursor, and any other agent runtime simultaneously. - **Consumer-side lock files.** Plugins install the latest version. APM pins exact versions so your team stays synchronized. -- **CI enforcement.** There is no plugin equivalent of `apm install --check` in a CI pipeline. +- **CI enforcement.** There is no plugin equivalent of `apm audit --ci` for drift detection in a CI pipeline. - **Multi-source dependency resolution.** APM resolves transitive dependencies across packages from multiple git hosts. - **Shared organizational packages.** Plugins are published by tool vendors. APM packages are published by your own teams, containing your own standards and configurations. @@ -129,7 +129,7 @@ For stakeholders familiar with existing tools, this comparison clarifies where A | Version pinning | None | Vendor-controlled | Consumer-side lock file | | Cross-tool support | N separate processes | Single tool only | Unified manifest | | Dependency resolution | Manual | None | Automatic, transitive | -| CI enforcement | Custom scripts | Not available | Built-in (`--check` flag) | +| CI enforcement | Custom scripts | Not available | Planned (`apm audit --ci`) | | Shared org standards | Wiki pages, copy-paste | Not available | Versioned packages | | Audit trail | Implicit via git | Varies by vendor | Explicit via `apm.lock` | | Lock-in | To manual process | To specific vendor | None (native output files) | @@ -197,4 +197,4 @@ With APM, setup reduces to `apm install` (under 30 seconds). Standards updates r 1. Review the [Adoption Playbook](../adoption-playbook/) for a phased rollout plan. 2. Start with a single team or repository as a pilot. 3. Publish a shared package with your organization's standards using the [APM for Teams](../teams/) guide. -4. Add `apm install --check` to CI and measure drift reduction over 30 days. +4. Add `apm audit --ci` to CI when available and measure drift reduction over 30 days. diff --git a/docs/src/content/docs/getting-started/authentication.md b/docs/src/content/docs/getting-started/authentication.md index e3bee610..3dc7a25d 100644 --- a/docs/src/content/docs/getting-started/authentication.md +++ b/docs/src/content/docs/getting-started/authentication.md @@ -12,7 +12,7 @@ APM works without any tokens for public packages. Authentication is only needed |----------|---------|-------------| | `GITHUB_APM_PAT` | Private GitHub/GHE repos | Private GitHub packages | | `ADO_APM_PAT` | Private Azure DevOps repos | Private ADO packages | -| `GITHUB_COPILOT_PAT` | Copilot runtime | `apm run` with Copilot | +| `GITHUB_COPILOT_PAT` | Copilot runtime | Runtime features (see [Agent Workflows](../../guides/agent-workflows/)) | | `GITHUB_HOST` | Default host for bare package names | GitHub Enterprise setups | ### GITHUB_APM_PAT @@ -41,7 +41,7 @@ export ADO_APM_PAT=your_ado_pat export GITHUB_COPILOT_PAT=ghp_copilot_token ``` -- **Purpose**: Authentication for `apm run` with Copilot runtime +- **Purpose**: Authentication for runtime features (see [Agent Workflows guide](../../guides/agent-workflows/)) - **Type**: Personal Access Token with Copilot access - **Fallback**: Falls back to `GITHUB_TOKEN` if not set @@ -87,7 +87,9 @@ export GITHUB_APM_PAT=ghp_enterprise_token apm install team/package # → github.company.com/team/package ``` -#### Running Prompts +#### Runtime Features + +Authentication may be needed for runtime features. See the [Agent Workflows guide](../../guides/agent-workflows/) for details. ```bash export GITHUB_COPILOT_PAT=ghp_copilot_token @@ -159,6 +161,6 @@ apm install dev.azure.com/myorg/myproject/myrepo/prompts/code-review.prompt.md - Go to `https://dev.azure.com/{org}/_usersSettings/tokens` - Create PAT with **Code (Read)** scope -3. **GITHUB_COPILOT_PAT** (Running prompts): +3. **GITHUB_COPILOT_PAT** (Runtime features -- see [Agent Workflows](../../guides/agent-workflows/)): - Go to [github.com/settings/tokens](https://github.com/settings/tokens) - Create token with Copilot access diff --git a/docs/src/content/docs/getting-started/installation.md b/docs/src/content/docs/getting-started/installation.md index 4e24d231..995e2802 100644 --- a/docs/src/content/docs/getting-started/installation.md +++ b/docs/src/content/docs/getting-started/installation.md @@ -1,527 +1,120 @@ --- title: "Installation" +description: "Install APM on macOS, Linux, or from source." sidebar: order: 1 --- -Get APM running in seconds. No tokens, no configuration — just install and go. +## Requirements -## Try APM in 60 Seconds +- macOS or Linux (x86_64 or ARM64) +- [git](https://git-scm.com/) for dependency management +- Python 3.10+ (only for pip or from-source installs) -See APM in action before reading anything else: +## Quick install (recommended) ```bash -# Install APM curl -sSL https://raw.githubusercontent.com/microsoft/apm/main/install.sh | sh - -# Install a sample package into any project -cd your-project -apm install microsoft/apm-sample-package - -# See what was installed -apm deps list ``` -That's it — your project now has agent instructions, prompts, and skills configured. Open it in VS Code or Claude to see the difference. - -Ready for a deeper walkthrough? See the [Quick Start guide](../quick-start/). - ---- - -## Quick Install (Recommended) +The install script detects your platform, downloads the latest binary, and installs it to `/usr/local/bin/`. -The fastest way to get APM running: - -```bash -curl -sSL https://raw.githubusercontent.com/microsoft/apm/main/install.sh | sh -``` - -This script automatically: -- Detects your platform (macOS/Linux, Intel/ARM) -- Downloads the latest binary -- Installs to `/usr/local/bin/` -- Verifies installation - -### Python Package - -If you prefer managing APM through Python: +## pip install ```bash pip install apm-cli ``` -**Note**: This requires Python 3.8+ and may have additional dependencies. +Requires Python 3.10+. -### Manual Installation +## Manual binary install -Download the binary for your platform from [GitHub Releases](https://github.com/microsoft/apm/releases/latest): +Download the archive for your platform from [GitHub Releases](https://github.com/microsoft/apm/releases/latest) and install manually: -#### macOS Apple Silicon ```bash +# Example: macOS Apple Silicon curl -L https://github.com/microsoft/apm/releases/latest/download/apm-darwin-arm64.tar.gz | tar -xz sudo mkdir -p /usr/local/lib/apm sudo cp -r apm-darwin-arm64/* /usr/local/lib/apm/ sudo ln -sf /usr/local/lib/apm/apm /usr/local/bin/apm ``` -#### macOS Intel -```bash -curl -L https://github.com/microsoft/apm/releases/latest/download/apm-darwin-x86_64.tar.gz | tar -xz -sudo mkdir -p /usr/local/lib/apm -sudo cp -r apm-darwin-x86_64/* /usr/local/lib/apm/ -sudo ln -sf /usr/local/lib/apm/apm /usr/local/bin/apm -``` - -#### Linux x86_64 -```bash -curl -L https://github.com/microsoft/apm/releases/latest/download/apm-linux-x86_64.tar.gz | tar -xz -sudo mkdir -p /usr/local/lib/apm -sudo cp -r apm-linux-x86_64/* /usr/local/lib/apm/ -sudo ln -sf /usr/local/lib/apm/apm /usr/local/bin/apm -``` +Replace `apm-darwin-arm64` with the archive name for your platform: -### From Source (Developers) +| Platform | Archive name | +|--------------------|----------------------| +| macOS Apple Silicon | `apm-darwin-arm64` | +| macOS Intel | `apm-darwin-x86_64` | +| Linux x86_64 | `apm-linux-x86_64` | +| Linux ARM64 | `apm-linux-arm64` | -For development or customization: +## From source (contributors) ```bash git clone https://github.com/microsoft/apm.git cd apm -# Install uv (if not already installed) +# Install uv if not already installed curl -LsSf https://astral.sh/uv/install.sh | sh -# Create virtual environment and install in development mode +# Create environment and install in development mode uv venv uv pip install -e ".[dev]" - -# Activate the environment for development -source .venv/bin/activate # On macOS/Linux -# .venv\Scripts\activate # On Windows +source .venv/bin/activate ``` -### Build Binary from Source +## Build binary from source -To build a platform-specific binary using PyInstaller: +To build a standalone binary with PyInstaller: ```bash -# Clone and setup (if not already done) -git clone https://github.com/microsoft/apm.git -cd apm - -# Install uv and dependencies -curl -LsSf https://astral.sh/uv/install.sh | sh -uv venv -uv pip install -e ".[dev]" +cd apm # cloned repo from step above uv pip install pyinstaller - -# Activate environment -source .venv/bin/activate - -# Build binary for your platform chmod +x scripts/build-binary.sh ./scripts/build-binary.sh ``` -This creates a platform-specific binary at `./dist/apm-{platform}-{arch}/apm` that can be distributed without Python dependencies. - -**Build features**: -- **Cross-platform**: Automatically detects macOS/Linux and Intel/ARM architectures -- **UPX compression**: Automatically compresses binary if UPX is available (`brew install upx`) -- **Self-contained**: Binary includes all Python dependencies -- **Fast startup**: Uses `--onedir` mode for optimal CLI performance -- **Verification**: Automatically tests the built binary and generates checksums - -## Setup AI Runtime +The output binary is at `./dist/apm-{platform}-{arch}/apm`. -APM works with multiple AI coding agents. Choose your preferred runtime: - -### GitHub Copilot CLI (Recommended) +## Verify installation ```bash -apm runtime setup copilot +apm --version ``` -Uses GitHub Copilot CLI with native MCP integration and advanced AI coding assistance. - -### OpenAI Codex CLI +## Troubleshooting -```bash -apm runtime setup codex -``` - -Uses GitHub Models API for GPT-4 access through Codex CLI. +### `apm: command not found` -### LLM Library +Ensure `/usr/local/bin` is in your `PATH`: ```bash -apm runtime setup llm +echo $PATH | tr ':' '\n' | grep /usr/local/bin ``` -Installs the LLM library for local and cloud model access. - -### Verify Installation - -Check what runtimes are available: +If missing, add it to your shell profile (`~/.zshrc`, `~/.bashrc`, etc.): ```bash -apm runtime list +export PATH="/usr/local/bin:$PATH" ``` -## First Project Walkthrough +### Permission denied during install -Let's create your first AI-native project step by step: - -### 1. Initialize Project +Use `sudo` for system-wide installation, or install to a user-writable directory instead: ```bash -apm init my-first-project -cd my-first-project -``` - -This creates a complete Context structure: - -```yaml -my-first-project/ -├── apm.yml # Project configuration -├── SKILL.md # Package meta-guide for AI discovery -└── .apm/ - ├── agents/ # AI assistant personalities - ├── instructions/ # Context and coding standards - ├── prompts/ # Reusable agent workflows - └── context/ # Project knowledge base +mkdir -p ~/bin +# then install the binary to ~/bin/apm and add ~/bin to PATH ``` -**About SKILL.md:** This file serves as a meta-guide that helps AI agents discover and understand the package's capabilities. When your package is installed as a dependency, the `SKILL.md` content helps the AI understand what skills/workflows are available and how to use them. - -> **Note**: Legacy `.apm/chatmodes/` directory with `.chatmode.md` files is still supported. - -### 2. Explore Generated Files - -Let's look at what was created: - -```bash -# See project structure -ls -la .apm/ - -# Check the main configuration -cat apm.yml - -# Look at available workflows -ls .apm/prompts/ -``` - -### 3. Compile Context - -Transform your context into agent-specific formats: - -```bash -apm compile -``` - -**Auto-Detection:** APM automatically detects which integrations to generate based on folder presence: -- If `.github/` exists → VSCode/Copilot integration (generates `AGENTS.md`) -- If `.claude/` exists → Claude Code integration (generates `CLAUDE.md`) -- Both can coexist - APM generates outputs for all detected integrations - -**Generated Files:** -- `AGENTS.md` - Contains instructions grouped by `applyTo` patterns (VSCode-compatible) -- `CLAUDE.md` - Contains instructions with `@import` syntax (Claude-compatible) - -> **Note:** These files contain **only instructions** - prompts and agents are installed separately during `apm install`. - -### 4. Install Dependencies - -Install APM and MCP dependencies from your `apm.yml` configuration: - -```bash -apm install -``` - -**What gets installed:** - -For VSCode/Copilot (when `.github/` exists): -- `.github/prompts/*.prompt.md` - Reusable prompt templates -- `.github/agents/*.agent.md` - Agent definitions -- `.github/skills/{folder-name}/` - Skills with `SKILL.md` meta-guide - -For Claude Code (when `.claude/` exists): -- `.claude/commands/*.md` - Slash commands - -> **Tip:** Both integrations can coexist in the same project. APM installs to all detected targets. - -#### Adding APM Dependencies (Optional) - -For reusable context from other projects, add APM dependencies: - -```yaml -# Add to apm.yml -dependencies: - apm: - - microsoft/apm-sample-package # Design standards, prompts - - github/awesome-copilot/skills/review-and-refactor # Code review skill - mcp: - - io.github.github/github-mcp-server -``` - -```bash -# Install APM dependencies -apm install --only=apm - -# View installed dependencies -apm deps list - -# See dependency tree -apm deps tree -``` - -#### Virtual Packages - -APM supports **virtual packages** - installing individual files directly from any repository without requiring a full APM package structure. This is perfect for reusing individual workflow files or configuration from existing projects. - -> 💡 **Explore ready-to-use prompts and agents!** -> Browse [github/awesome-copilot](https://github.com/github/awesome-copilot) for a curated collection of community-contributed skills, instructions, and agents across all major languages and frameworks. Install any subdirectory directly with APM. Also works with Awesome Copilot's plugins. - -**What are Virtual Packages?** +### Authentication errors when installing packages -Instead of installing an entire package (`owner/repo`), you can install specific files: +If `apm install` fails with authentication errors for private repositories, ensure you have a valid GitHub token configured: ```bash -# Install individual files directly -apm install github/awesome-copilot/skills/architecture-blueprint-generator -apm install myorg/standards/instructions/code-review.instructions.md -apm install company/templates/chatmodes/qa-assistant.chatmode.md +curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user ``` -**How it Works:** - -1. **Path Detection**: APM detects paths with 3+ segments as virtual packages -2. **File Download**: Downloads the file from GitHub's raw content API -3. **Structure Generation**: Creates a minimal APM package automatically: - - Generates `apm.yml` with metadata extracted from file frontmatter - - Places file in correct `.apm/` subdirectory based on extension - - Creates sanitized package name from path - -**Supported File Types:** - -- `.prompt.md` - Agent workflows -- `.instructions.md` - Context and rules -- `.agent.md` - Agent definitions - -**Installation Structure:** - -Files install to `apm_modules/{owner}/{sanitized-package-name}/`: - -```bash -apm install github/awesome-copilot/skills/review-and-refactor -``` - -Creates: -``` -apm_modules/ -└── github/ - └── awesome-copilot/ - └── skills/ - └── review-and-refactor/ - ├── apm.yml - └── SKILL.md -``` - -**Adding to apm.yml:** - -Virtual packages work in `apm.yml` just like regular packages: - -```yaml -dependencies: - apm: - # Regular packages - - microsoft/apm-sample-package - - # Virtual packages - individual files - - github/awesome-copilot/skills/architecture-blueprint-generator - - myorg/engineering/instructions/testing-standards.instructions.md -``` - -**Branch/Tag Support:** - -Use `@ref` syntax for specific versions: - -```bash -# Install from specific branch -apm install github/awesome-copilot/skills/review-and-refactor@develop - -# Install from tag -apm install myorg/templates/chatmodes/assistant.chatmode.md@v2.1.0 -``` - -**Use Cases:** - -- **Quick Prototyping**: Test individual workflows without package overhead -- **Selective Adoption**: Pull single files from large repositories -- **Cross-Team Sharing**: Share individual standards without full package structure -- **Legacy Migration**: Gradually adopt APM by importing existing files - -**Example Workflow:** - -```bash -# 1. Find useful prompt in another repo -# Browse: github.com/awesome-org/best-practices - -# 2. Install specific file -apm install awesome-org/best-practices/prompts/security-scan.prompt.md - -# 3. Use immediately - no apm.yml configuration needed! -apm run security-scan --param target="./src" - -# 4. Or add explicit script to apm.yml for custom flags -# scripts: -# security: "copilot --full-auto -p security-scan.prompt.md" -``` - -**Benefits:** - -- ✅ **Zero overhead** - No package creation required -- ✅ **Instant reuse** - Install any file from any repository -- ✅ **Auto-discovery** - Run installed prompts without script configuration -- ✅ **Automatic structure** - APM creates package layout for you -- ✅ **Full compatibility** - Works with `apm compile` and all commands -- ✅ **Version control** - Support for branches and tags - -### Runnable Prompts (Auto-Discovery) - -Starting with v0.5.0, installed prompts are **immediately runnable** without manual configuration: - -```bash -# Install a prompt -apm install github/awesome-copilot/skills/architecture-blueprint-generator - -# Run immediately - APM auto-discovers it! -apm run architecture-blueprint-generator --param project_name="my-app" - -# Auto-discovery works for: -# - Installed virtual packages -# - Local prompts (./my-prompt.prompt.md) -# - Prompts in .apm/prompts/ or .github/prompts/ -# - All prompts from installed regular packages -``` - -**How auto-discovery works:** - -1. **No script found in apm.yml?** APM searches for matching prompt files -2. **Runtime detection:** Automatically uses GitHub Copilot CLI (preferred) or Codex -3. **Smart defaults:** Applies recommended flags for chosen runtime -4. **Collision handling:** If multiple prompts found, use qualified path: `owner/repo/prompt-name` - -**Priority:** -- Explicit scripts in `apm.yml` **always win** (power user control) -- Auto-discovery provides zero-config convenience for simple cases - -**Disambiguation with qualified paths:** - -```bash -# If you have prompts from multiple sources -apm run github/awesome-copilot/code-review -apm run acme/standards/code-review -``` - -See [Prompts Guide](../../guides/prompts/#running-prompts) for complete auto-discovery documentation. - -### 5. Run Your First Workflow - -Execute the default "start" workflow: - -```bash -apm run start --param name="" -``` - -This runs the AI workflow with your chosen runtime, demonstrating how APM enables reliable, reusable AI interactions. - -### 6. Explore Available Scripts - -See what workflows are available: - -```bash -apm list -``` - -### 7. Preview Workflows - -Before running, you can preview what will be executed: - -```bash -apm preview start --param name="" -``` - -## Common Troubleshooting - -### Token Issues - -**Problem**: "Authentication failed" or "Token invalid" -**Solution**: -1. Verify token has correct permissions -2. Check token expiration -3. Ensure environment variables are set correctly - -```bash -# Test token access -curl -H "Authorization: token $GITHUB_CLI_PAT" https://api.github.com/user -``` - -### Runtime Installation Fails - -**Problem**: `apm runtime setup` fails -**Solution**: -1. Check internet connection -2. Verify system requirements -3. Try installing specific runtime manually - -### Command Not Found - -**Problem**: `apm: command not found` -**Solution**: -1. Check if `/usr/local/bin` is in your PATH -2. Try `which apm` to locate the binary -3. Reinstall using the quick install script - -### Permission Denied - -**Problem**: Permission errors during installation -**Solution**: -1. Use `sudo` for system-wide installation -2. Or install to user directory: `~/bin/` - -## Next Steps - -Now that you have APM set up: - -1. **Learn the concepts**: Read [Core Concepts](../../introduction/how-it-works/) to understand the AI-Native Development framework -2. **Study examples**: Check [Examples & Use Cases](../../reference/examples/) for real-world patterns -3. **Build workflows**: See [Context Guide](../../introduction/key-concepts/) to create advanced workflows -4. **Explore dependencies**: See [Dependency Management](../../guides/dependencies/) for sharing context across projects -5. **Explore integrations**: Review [Integrations Guide](../../integrations/ide-tool-integration/) for tool compatibility - -## Quick Reference - -### Essential Commands -```bash -apm init # 🏗️ Initialize AI-native project -apm compile # ⚙️ Generate AGENTS.md compatibility layer -apm run # 🚀 Execute agent workflows -apm runtime setup # ⚡ Install coding agents -apm list # 📋 Show available workflows -apm install # 📦 Install APM & MCP dependencies -apm deps list # 🔗 Show installed APM dependencies -``` +## Next steps -### File Structure -- `apm.yml` - Project configuration and scripts -- `.apm/` - Context directory (source primitives) -- `SKILL.md` - Package meta-guide for AI discovery -- `AGENTS.md` - Generated VSCode/Copilot instructions -- `CLAUDE.md` - Generated Claude Code instructions -- `.github/prompts/`, `.github/agents/`, `.github/skills/` - Installed VSCode primitives and skills -- `.claude/commands/` - Installed Claude commands -- `apm_modules/` - Installed APM dependencies -- `*.prompt.md` - Executable agent workflows - -Ready to build reliable AI workflows? Let's explore the [core concepts](../../introduction/how-it-works/) next! \ No newline at end of file +See the [Quick Start](../quick-start/) to set up your first project. \ No newline at end of file diff --git a/docs/src/content/docs/getting-started/migration.md b/docs/src/content/docs/getting-started/migration.md index ef08dd7a..7342925e 100644 --- a/docs/src/content/docs/getting-started/migration.md +++ b/docs/src/content/docs/getting-started/migration.md @@ -1,48 +1,15 @@ --- -title: "Migrating Existing Projects" -description: "Adopt APM in projects that already have AI agent configuration — without disruption." +title: "Existing Projects" +description: "Add APM to a project that already has AI agent configuration." sidebar: order: 5 --- -Most teams adopting APM already have some form of AI agent configuration in place. This guide covers how to introduce APM into a project that already uses `.github/copilot-instructions.md`, `AGENTS.md`, `CLAUDE.md`, `.cursor-rules`, manually managed `.github/instructions/`, or plugin configurations — without breaking what already works. +APM is additive. It never deletes, overwrites, or modifies your existing configuration files. Your current `.github/copilot-instructions.md`, `AGENTS.md`, `.claude/` config, `.cursor-rules` — all stay exactly where they are, untouched. -## Before You Start +## Add APM in three steps -Take stock of what you currently have. Common configurations include: - -| File / Directory | Purpose | -|---|---| -| `.github/copilot-instructions.md` | Repository-level Copilot instructions | -| `.github/instructions/*.md` | File-pattern or task-specific Copilot instructions | -| `AGENTS.md` | Agent instructions (Codex, multi-agent workflows) | -| `CLAUDE.md` | Claude Code project instructions | -| `.cursor-rules` or `.cursorrules` | Cursor IDE rules | -| `.aider*` files | Aider conventions | -| Plugin configs (MCP servers, tools) | Manually installed tool integrations | - -If you have any of these, you are in the right place. - -## What APM Will (and Will Not) Do - -APM is additive. Running `apm init` and `apm compile` will never delete, overwrite, or modify your existing configuration files unless you explicitly ask it to. The compiled output targets (like `AGENTS.md` or `.github/copilot-instructions.md`) are clearly marked as generated, so there is no ambiguity about which files APM manages and which are yours. - -If you later decide APM is not for you, delete `apm.yml` and `apm.lock` and your original files remain untouched. - -## Step-by-Step Migration - -### Step 1: Inventory Your Existing Config - -List everything you currently have. A quick way to check: - -```bash -ls -la .github/copilot-instructions.md .github/instructions/ \ - AGENTS.md CLAUDE.md .cursor-rules .cursorrules 2>/dev/null -``` - -Write down which files are hand-maintained and which are copy-pasted from other projects or team templates. The copy-pasted ones are your best candidates for replacing with shared APM packages. - -### Step 2: Initialize APM +### 1. Initialize Run `apm init` in your project root: @@ -50,140 +17,46 @@ Run `apm init` in your project root: apm init ``` -This creates an `apm.yml` manifest alongside your existing files. Nothing is deleted or moved. If you already have an `apm.yml`, this step is a no-op. - -Review the generated `apm.yml` — it will contain a basic structure with empty dependency and primitive sections ready for you to populate. +This creates an `apm.yml` manifest alongside your existing files. Nothing is deleted or moved. -### Step 3: Wrap Existing Primitives (Optional) +### 2. Install packages -If you have local instructions, prompts, or agent definitions that you want APM to manage, move them into the `.apm/` directory structure: - -``` -.apm/ -├── instructions/ -│ └── coding-standards.instructions.md -├── prompts/ -│ └── review.prompt.md -└── agents/ - └── reviewer.agent.md -``` - -Then reference them in your `apm.yml`: - -```yaml -prompts: - - prompts/review.prompt.md - -instructions: - - instructions/coding-standards.instructions.md -``` - -This step is optional. APM also discovers files placed directly in `.github/instructions/` and other standard locations. Wrapping them in `.apm/` gives you explicit control over what gets compiled and where. - -### Step 4: Add External Dependencies - -Replace copy-pasted configuration with shared packages: +Add the shared packages your team needs: ```bash apm install microsoft/copilot-best-practices apm install your-org/team-standards ``` -Each package brings in versioned, maintained primitives instead of stale copies. Your `apm.yml` now tracks these as dependencies with pinned versions in `apm.lock`. +Each package brings in versioned, maintained configuration instead of stale copies. Your `apm.yml` tracks these as dependencies, and `apm.lock` pins exact versions. -### Step 5: Compile and Verify - -Run compilation to see what APM would generate: - -```bash -apm compile --verbose --dry-run -``` - -The `--dry-run` flag shows you the output without writing any files. Compare it against your current `AGENTS.md` or other target files. The compiled output should match or improve on what you had before. - -When satisfied, run without `--dry-run`: - -```bash -apm compile -``` - -Review the generated files. If a compiled file conflicts with a hand-maintained one, APM will warn you. You decide whether to let APM manage that file or keep your manual version. - -### Step 6: Commit the Manifest - -Add the APM manifest and lock file to version control: +### 3. Commit and share ```bash git add apm.yml apm.lock -git commit -m "Add APM manifest for agent configuration management" +git commit -m "Add APM manifest" ``` -Your teammates can now run `apm install` followed by `apm compile` to get an identical setup. No more copy-pasting configuration between repositories or Slack threads. - -### Step 7: Gradually Convert - -You do not need to migrate everything at once. A practical approach: - -1. Start with `apm install` for external packages only — keep all local config manual. -2. Move one or two local files into `.apm/` and verify the compiled output. -3. Over time, convert remaining hand-maintained files as you gain confidence. -4. Eventually, your `apm.yml` becomes the single source of truth for all agent configuration. - -There is no deadline. APM and manual configuration coexist indefinitely. - -## Common Migration Patterns - -### From Manual copilot-instructions.md - -**Before:** A hand-maintained `.github/copilot-instructions.md` that drifts across repositories. +Your teammates run `apm install` and get the same setup. No more copy-pasting configuration between repositories. -**After:** An instruction primitive in `.apm/instructions/` compiled into `.github/copilot-instructions.md` by `apm compile`. Changes propagate to every repo that depends on the package. +## What happens to your existing files? -### From Copy-Pasted AGENTS.md +They continue to work. APM-managed files coexist with manually-created ones. There is no conflict and no takeover. -**Before:** An `AGENTS.md` copied from a template repo, manually edited per project, gradually falling out of date. - -**After:** `apm compile` generates `AGENTS.md` from your dependency tree. Updates arrive via `apm update` instead of manual diffing. - -### From Individual Plugin Installs - -**Before:** Each developer manually installs MCP servers and tool integrations, with inconsistent versions across the team. - -**After:** Plugin dependencies declared in `apm.yml`. Running `apm install` gives every developer the same plugin set. - -### From Scattered Team Standards - -**Before:** Coding standards, review guidelines, and prompt templates live in a wiki, a shared drive, or a pinned Slack message. - -**After:** A shared APM package (`your-org/team-standards`) that every repository depends on. Update the package once, run `apm update` everywhere. +Over time, you may choose to move manual configuration into APM packages for portability across repositories, but there is no deadline or requirement to do so. APM and manual configuration coexist indefinitely. ## Rollback -APM does not take ownership of your project. If you want to stop using it: +If you decide APM is not for you: 1. Delete `apm.yml` and `apm.lock`. -2. Optionally remove the `.apm/` directory if you created one. -3. Your native configuration files (`.github/`, `.claude/`, `AGENTS.md`) continue to work exactly as they did before APM. - -No uninstall script, no cleanup command — just remove the manifest files. - -## Troubleshooting - -### Compiled output overwrites my manual file - -APM-generated files include a header comment marking them as managed. If you have a hand-maintained file at the same path, rename it or move your content into an APM primitive so compilation produces the combined result. - -### Existing AGENTS.md has custom sections - -Use `apm compile --verbose` to inspect how the output is assembled. You can add local primitives that contribute content to specific sections, preserving your custom additions in a structured way. - -### Team members do not have APM installed +2. Your original files are still there, unchanged. -APM-generated files are standard Markdown. Team members without APM installed can still read and use the generated `AGENTS.md`, `.github/copilot-instructions.md`, and other output files directly. APM is only needed to update or recompile them. +No uninstall script, no cleanup command. Zero risk. -## Next Steps +## Next steps -- [Compilation guide](../../guides/compilation/) — understand how `apm compile` assembles output +- [Quick start](../quickstart/) — first-time setup walkthrough - [Dependencies](../../guides/dependencies/) — managing external packages - [Manifest schema](../../reference/manifest-schema/) — full `apm.yml` reference - [CLI commands](../../reference/cli-commands/) — complete command reference diff --git a/docs/src/content/docs/getting-started/quick-start.md b/docs/src/content/docs/getting-started/quick-start.md index cf6fa950..cf266f1a 100644 --- a/docs/src/content/docs/getting-started/quick-start.md +++ b/docs/src/content/docs/getting-started/quick-start.md @@ -1,194 +1,131 @@ --- title: "Quick Start" -description: "Get from zero to a fully configured AI agent setup in 5 minutes." +description: "Get APM running and install your first package in under 3 minutes." sidebar: order: 2 --- -This walkthrough takes you from an empty directory to a fully configured AI agent setup. Every step is a command you can run right now. +Three commands. Three minutes. Your AI agent learns your project's standards automatically. -## 1. Install APM - -One command, no prerequisites beyond Python 3.10+: +## Install APM ```bash curl -sSL https://raw.githubusercontent.com/microsoft/apm/main/install.sh | sh ``` -Verify the installation: +Verify it worked: ```bash apm --version ``` -``` -apm, version x.x.x -``` - -For alternative methods (Homebrew, pip), see the [Installation guide](../installation/). +For Homebrew, pip, or manual install, see the [Installation guide](../installation/). -## 2. Initialize a project +## Start a project -Create a new project and move into it: +Create a new project: ```bash apm init my-project && cd my-project ``` -``` -Created project directory: my-project -Initializing APM project: my-project -APM project initialized successfully! +Or initialize inside an existing repository: - Created Files - ✨ apm.yml Project configuration +```bash +cd your-repo +apm init ``` -The generated `apm.yml` is your project manifest — equivalent to `package.json` or `requirements.txt`, but for AI agent configuration: +Either way, APM creates an `apm.yml` manifest -- your dependency file for AI agent configuration: -```yaml +```yaml title="apm.yml" name: my-project version: 1.0.0 dependencies: apm: [] ``` -If you already have a repository, run `apm init` (without a project name) inside it. APM detects your existing project metadata automatically. +## Install a package -## 3. Add your first dependency - -Install a sample package to see how APM works: +This is where it gets interesting. Install a package and watch what happens: ```bash apm install microsoft/apm-sample-package ``` -``` -Installing APM dependencies... -Resolving: microsoft/apm-sample-package -Downloaded: microsoft/apm-sample-package@latest -Deployed 3 files to .github/instructions/ -``` - -APM did three things: - -1. **Downloaded** the package from GitHub into `apm_modules/microsoft/apm-sample-package/`. -2. **Resolved** any transitive dependencies the package declares. -3. **Deployed** instruction files into `.github/instructions/` where your AI tools can find them. - -Your `apm.yml` now includes the dependency: - -```yaml -dependencies: - apm: - - microsoft/apm-sample-package -``` - -And a lockfile (`apm.lock`) pins the exact commit so every developer on your team gets the same version. - -## 4. See the result - -After install, your project tree looks like this: +APM downloads the package, resolves its dependencies, and deploys files directly into the directories your AI tools already watch: ``` my-project/ - apm.yml # Project manifest - apm.lock # Pinned dependency versions - apm_modules/ # Downloaded packages (like node_modules/) + apm.yml + apm.lock + apm_modules/ microsoft/ apm-sample-package/ - apm.yml - .apm/ - instructions/ - skills/ - prompts/ .github/ - instructions/ # Deployed instructions for Copilot/Cursor + instructions/ + apm-sample-package/ + design-standards.instructions.md + prompts/ + apm-sample-package/ + accessibility-audit.prompt.md + design-review.prompt.md + .claude/ + commands/ apm-sample-package/ ... ``` -The `.github/instructions/` directory is where VS Code, GitHub Copilot, and Cursor look for agent context. Open your editor — your AI agent is now configured with the skills, instructions, and prompts from the package you installed. +Three things happened: -## 5. Compile instructions - -For tools that read a single root file (like Claude Code or Codex), compile everything into one output: - -```bash -apm compile -``` - -``` -Compiling APM context... -Target: all (auto-detected) -Generated: AGENTS.md -Generated: CLAUDE.md -``` +1. The package was downloaded into `apm_modules/` (like `node_modules/`). +2. Instructions, prompts, and skills were deployed to `.github/` and `.claude/` -- the native directories that GitHub Copilot, Cursor, and Claude already read from. +3. A lockfile (`apm.lock`) was created, pinning the exact commit so every team member gets identical configuration. -By default, `apm compile` targets all platforms. You can narrow it: +Your `apm.yml` now tracks the dependency: -```bash -# Copilot/Cursor/Codex only — produces AGENTS.md -apm compile --target copilot - -# Claude Code only — produces CLAUDE.md -apm compile --target claude -``` - -Use `--dry-run` to preview what would be generated without writing any files: - -```bash -apm compile --dry-run +```yaml title="apm.yml" +name: my-project +version: 1.0.0 +dependencies: + apm: + - microsoft/apm-sample-package ``` -## 6. Check what is installed +## That's it -List all installed packages: - -```bash -apm deps list -``` +Open your editor. GitHub Copilot and Claude pick up the new context immediately -- no extra configuration, no compile step, no restart. The agent now knows your project's design standards, can run your prompt templates, and follows the conventions defined in the package. -``` -Installed APM Dependencies +This is the core idea: **packages define what your AI agent knows, and `apm install` puts that knowledge exactly where your tools expect it.** - Package Source Version - microsoft/apm-sample-package github abc1234 -``` +## Day-to-day workflow -View the full dependency tree, including transitive dependencies: +When a new developer joins your team: ```bash -apm deps tree -``` - -``` -my-project - microsoft/apm-sample-package@abc1234 +git clone +cd +apm install ``` -## 7. Day-to-day workflow +The lockfile ensures everyone gets the same agent configuration. Same as `npm install` after cloning a Node project. -Once set up, the workflow for your team is straightforward: +Add more packages as your project evolves: ```bash -# A new developer clones and installs — same as npm install -git clone -cd -apm install - -# Add another package later apm install github/awesome-copilot/skills/review-and-refactor - -# Recompile after adding dependencies -apm compile ``` -Commit `apm.yml` and `apm.lock` to version control. The `apm_modules/` directory should be in `.gitignore` — APM recreates it from the lockfile on `apm install`. +**What to commit:** +- `apm.yml` and `apm.lock` -- version-controlled, shared with the team. +- `apm_modules/` -- add to `.gitignore`. Rebuilt from the lockfile on install. + +:::note[Using Cursor, Codex, or Gemini?] +These tools use different configuration formats. Run `apm compile` after installing to generate their native files. See the [Compilation guide](../../guides/compilation/) for details. +::: -## What's next +## Next steps -- [Your First Package](../first-package/) — create and publish your own APM package. -- [Compilation guide](../../guides/compilation/) — learn about distributed compilation, targets, and options. -- [Dependency management](../../guides/dependencies/) — version pinning, updates, and transitive resolution. -- [CLI reference](../../reference/cli-commands/) — full list of commands, flags, and examples. +- [Your First Package](../first-package/) -- create and share your own APM package. +- [Dependency management](../../guides/dependencies/) -- version pinning, updates, and transitive resolution. +- [CLI reference](../../reference/cli-commands/) -- full list of commands and options. diff --git a/docs/src/content/docs/guides/agent-workflows.md b/docs/src/content/docs/guides/agent-workflows.md new file mode 100644 index 00000000..cd4c4c19 --- /dev/null +++ b/docs/src/content/docs/guides/agent-workflows.md @@ -0,0 +1,246 @@ +--- +title: "Agent Workflows (Experimental)" +description: "Run agentic workflows locally using APM scripts and AI runtimes." +sidebar: + order: 8 +--- + +:::caution[Experimental Feature] +APM's core value is dependency management — `apm install`, `apm.lock`, `apm audit`. The workflow execution features described on this page are experimental and may change. For most users, `apm install` is all you need. +::: + +## What are Agent Workflows? + +Agent workflows let you run `.prompt.md` files locally through AI runtimes — similar to [GitHub Agentic Workflows](https://github.blog/changelog/2025-05-19-github-copilot-coding-agent-in-public-preview/), but on your machine. + +Scripts are defined in `apm.yml` or auto-discovered from installed packages. You execute them with `apm run`, passing parameters and choosing a runtime (Copilot CLI, Codex, LLM). + +## Setting Up a Runtime + +Before running workflows, install at least one AI runtime: + +```bash +# GitHub Copilot CLI (recommended) +apm runtime setup copilot + +# OpenAI Codex CLI +apm runtime setup codex + +# LLM library +apm runtime setup llm +``` + +Verify installed runtimes: + +```bash +apm runtime list +``` + +### Runtime requirements + +| Runtime | Requirements | Notes | +|---------|-------------|-------| +| Copilot CLI | Node.js v22+, npm v10+ | Recommended. MCP config at `~/.copilot/` | +| Codex | Node.js | Set `GITHUB_TOKEN` for GitHub Models support | +| LLM | Python 3.9+ | Supports multiple model providers | + +**Copilot CLI** is the recommended runtime — it requires no API keys for installation and integrates with GitHub Copilot directly. + +For **Codex**, configure authentication after setup: + +```bash +export GITHUB_TOKEN=your_github_token +``` + +For **LLM**, configure at least one model provider: + +```bash +llm keys set github # GitHub Models (free) +llm keys set openai # OpenAI +llm keys set anthropic # Anthropic +``` + +For more details on runtime capabilities and configuration, see the [Runtime Compatibility](../../integrations/runtime-compatibility/) page. + +## Defining Scripts + +### Explicit scripts in apm.yml + +Define scripts in your `apm.yml` to map names to prompt files and runtimes: + +```yaml +scripts: + start: + description: "Default workflow" + prompt: .apm/prompts/start.prompt.md + runtime: copilot + review: + description: "Code review" + prompt: .apm/prompts/review.prompt.md + runtime: copilot + analyze: + description: "Log analysis" + prompt: .apm/prompts/analyze-logs.prompt.md + runtime: llm +``` + +You can also use the shorthand format for simple scripts: + +```yaml +scripts: + start: "copilot --full-auto -p analyze-logs.prompt.md" + debug: "RUST_LOG=debug codex analyze-logs.prompt.md" + llm-script: "llm analyze-logs.prompt.md -m github/gpt-4o-mini" +``` + +### Auto-discovery (zero configuration) + +When you install packages that include `.prompt.md` files, APM auto-discovers them as runnable scripts — no `apm.yml` configuration needed: + +```bash +apm install github/awesome-copilot/skills/review-and-refactor +apm run review-and-refactor # Works immediately +``` + +APM searches for prompts in this order: + +1. Local prompts in the project +2. `.apm/prompts/` directory +3. `.github/prompts/` directory +4. Installed package dependencies + +Use `apm list` to see all available scripts (both configured and auto-discovered). + +### Handling name collisions + +If multiple packages provide prompts with the same name, use qualified paths: + +```bash +apm run github/awesome-copilot/code-review --param pr_url=... +apm run acme/standards/code-review --param pr_url=... +``` + +## Running Workflows + +### Basic execution + +```bash +apm run start +``` + +### Passing parameters + +Use `--param` to pass input values that map to `${input:name}` placeholders in prompt files: + +```bash +apm run start --param service_name=api-gateway --param time_window="1h" +apm run code-review --param pull_request_url="https://github.com/org/repo/pull/123" +``` + +### Previewing before running + +Preview the compiled prompt (with parameters substituted) without executing it: + +```bash +apm preview start --param service_name=api-gateway --param time_window="1h" +``` + +### Listing available scripts + +```bash +apm list +``` + +This shows all scripts — both explicitly defined in `apm.yml` and auto-discovered from installed packages. + +## Prompt File Structure + +Prompt files (`.prompt.md`) use YAML frontmatter for metadata and Markdown for the prompt body: + +```markdown +--- +description: Analyzes application logs to identify errors and patterns +author: DevOps Team +mcp: + - logs-analyzer +input: + - service_name + - time_window + - log_level +--- + +# Analyze Application Logs + +You are an expert DevOps engineer specializing in log analysis. + +## Context + +- Service: ${input:service_name} +- Time window: ${input:time_window} +- Log level: ${input:log_level} + +## Task + +1. Retrieve logs for the specified service +2. Identify error patterns and anomalies +3. Suggest remediation steps +``` + +Use `${input:parameter_name}` syntax for dynamic values that are filled in at runtime via `--param`. + +For full details on prompt file syntax, compilation, and dependency management, see the [Prompts guide](../prompts/). + +## Example Workflows + +### Code review + +Install a code review prompt and run it against a pull request: + +```bash +apm install github/awesome-copilot/skills/review-and-refactor + +apm run review-and-refactor \ + --param pull_request_url="https://github.com/org/repo/pull/42" +``` + +### Security scan + +Define a security-focused workflow in `apm.yml`: + +```yaml +scripts: + security: + description: "Security vulnerability scan" + prompt: .apm/prompts/security-scan.prompt.md + runtime: copilot +``` + +Then run it: + +```bash +apm run security --param target_dir="src/" +``` + +### Multi-runtime setup + +Use different runtimes for different tasks: + +```yaml +scripts: + review: "copilot --full-auto -p code-review.prompt.md" + summarize: "llm summarize.prompt.md -m github/gpt-4o-mini" + debug: "RUST_LOG=debug codex debug-analysis.prompt.md" +``` + +```bash +apm run review --param files="src/" +apm run summarize --param scope="recent-changes" +``` + +## Troubleshooting + +**Runtime not found**: Run `apm runtime list` to verify installation. Re-run `apm runtime setup ` if needed. + +**Command not found after setup**: Ensure the runtime binary is on your PATH. For Copilot CLI, verify Node.js v22+ is installed. For LLM, ensure the Python virtual environment is active. + +**No scripts available**: Run `apm list` to check. If empty, either define scripts in `apm.yml` or install a package that includes `.prompt.md` files. diff --git a/docs/src/content/docs/guides/compilation.md b/docs/src/content/docs/guides/compilation.md index 43ca7112..50416c23 100644 --- a/docs/src/content/docs/guides/compilation.md +++ b/docs/src/content/docs/guides/compilation.md @@ -4,6 +4,8 @@ sidebar: order: 1 --- +Compilation is **optional for most users**. If your team uses GitHub Copilot or Claude, `apm install` deploys all primitives in their native format -- you can skip this guide entirely. `apm compile` is for teams that use Cursor, Codex, Gemini, or other tools that read single-root-file formats like `AGENTS.md` or `CLAUDE.md`. It is also useful when you want a consolidated view of all instructions in one file. + **Solving the AI agent scalability problem through constraint satisfaction optimization** APM's compilation system implements a mathematically rigorous solution to the **context pollution problem** that degrades AI agent performance as projects grow. Through constraint satisfaction optimization and hierarchical coverage guarantees, `apm compile` transforms scattered primitives into optimized context files for every major AI coding agent. @@ -221,9 +223,9 @@ def _calculate_hierarchical_coverage(self, placements: List[Path], target_direct apm compile # Example output: -📊 Analyzing 247 files across 12 directories... -🎯 Optimizing instruction placement... -✅ Generated 4 AGENTS.md files with guaranteed coverage +Analyzing 247 files across 12 directories... +Optimizing instruction placement... +Generated 4 AGENTS.md files with guaranteed coverage ``` ### Mathematical Analysis Mode @@ -233,14 +235,14 @@ apm compile apm compile --verbose # Example detailed output: -🔬 Mathematical Analysis: -├─ Distribution Scores: -│ ├─ **/*.py: 0.23 → Single-Point Strategy -│ ├─ **/*.tsx: 0.67 → Selective Multi Strategy -│ └─ **/*.md: 0.81 → Distributed Strategy -├─ Coverage Verification: ✓ Complete (100%) -├─ Constraint Satisfaction: All 8 constraints satisfied -└─ Generation Time: 127ms +Mathematical Analysis: +|- Distribution Scores: +| |- **/*.py: 0.23 -> Single-Point Strategy +| |- **/*.tsx: 0.67 -> Selective Multi Strategy +| +- **/*.md: 0.81 -> Distributed Strategy +|- Coverage Verification: Complete (100%) +|- Constraint Satisfaction: All 8 constraints satisfied ++- Generation Time: 127ms ``` ### Performance Analysis @@ -251,8 +253,8 @@ apm compile --dry-run # Timing instrumentation apm compile --verbose -# Shows: ⏱️ Project Analysis: 45.2ms -# ⏱️ Instruction Processing: 82.1ms +# Shows: Project Analysis: 45.2ms +# Instruction Processing: 82.1ms ``` ### Configuration Control @@ -421,16 +423,19 @@ The optimization engine implements: - **Performance-optimized caching strategies** - **Deterministic reproducible results** -## Universal Compatibility +## Tool Compatibility + +Different AI tools get different levels of support from `apm install` vs `apm compile`: -Generated AGENTS.md files work seamlessly across all major coding agents: +| AI Tool | What `apm install` deploys | What `apm compile` adds | Support level | +|---------|--------------------------|------------------------|---------------| +| GitHub Copilot | `.github/instructions/`, `.github/prompts/`, agents, hooks, plugins, MCP | `AGENTS.md` (optional) | **Full** | +| Claude | `.claude/` commands, skills, MCP | `CLAUDE.md` | **Full** | +| Cursor | -- | `.cursor/rules/` | Instructions via compile | +| Codex CLI | -- | `AGENTS.md` | Instructions via compile | +| Gemini | -- | `GEMINI.md` | Instructions via compile | -- ✅ **GitHub Copilot** (All variations) -- ✅ **Cursor** (Native AGENTS.md support) -- ✅ **Continue** (VS Code & JetBrains) -- ✅ **Codeium** (Universal compatibility) -- ✅ **Claude** (Anthropic's implementation) -- ✅ **Any AGENTS.md standard compliant tool** +For Copilot and Claude users, `apm install` handles everything natively. Compilation is the bridge that brings instruction support to tools that do not yet have first-class APM integration. ## Theoretical Foundations diff --git a/docs/src/content/docs/guides/dependencies.md b/docs/src/content/docs/guides/dependencies.md index 20cb7665..62f1c7cc 100644 --- a/docs/src/content/docs/guides/dependencies.md +++ b/docs/src/content/docs/guides/dependencies.md @@ -718,7 +718,6 @@ apm install apm compile # Now all team contexts and workflows are available -apm run design-review --param component="login-form" ``` ## Next Steps diff --git a/docs/src/content/docs/guides/prompts.md b/docs/src/content/docs/guides/prompts.md index 212b0ada..3c346905 100644 --- a/docs/src/content/docs/guides/prompts.md +++ b/docs/src/content/docs/guides/prompts.md @@ -4,26 +4,24 @@ sidebar: order: 3 --- -Prompts are the building blocks of APM - focused, reusable AI instructions that accomplish specific tasks. They are executed through scripts defined in your `apm.yml` configuration. +Prompts are the building blocks of APM -- focused, reusable AI instructions that accomplish specific tasks. They follow the `.prompt.md` convention and are distributed as shareable packages. ## How Prompts Work in APM -APM uses a script-based architecture: +APM treats prompts as deployable artifacts: -1. **Scripts** are defined in `apm.yml` and specify which runtime and prompt to use -2. **Prompts** (`.prompt.md` files) contain the AI instructions with parameter placeholders -3. **Compilation** happens when scripts reference `.prompt.md` files - APM compiles them with parameter substitution -4. **Execution** runs the compiled prompt through the specified runtime +1. **Prompts** (`.prompt.md` files) contain AI instructions with parameter placeholders +2. **Packages** bundle prompts for sharing via `apm publish` and `apm install` +3. **Deployment** places prompts into well-known directories (e.g., `.github/prompts/`) where tools like GitHub Copilot can discover and use them +4. **Compilation** resolves parameter placeholders, cross-file references, and link transforms at install time ```bash -# Script execution flow -apm run start --param key=value +# Deployment flow +apm install owner/my-prompt-package ↓ -Script: "codex my-prompt.prompt.md" +APM compiles .prompt.md files (parameter defaults, link resolution) ↓ -APM compiles my-prompt.prompt.md with parameters - ↓ -Codex executes the compiled prompt +Prompts land in .github/prompts/ for Copilot to discover ``` ## What are Prompts? @@ -103,7 +101,7 @@ Reference script inputs using the `${input:name}` syntax: ## MCP Tool Integration (Phase 2 - Coming Soon) -> **⚠️ Note**: MCP integration is planned work. Currently, prompts work with natural language instructions only. +> **Note**: MCP integration is planned work. Currently, prompts work with natural language instructions only. **Future capability** - Prompts will be able to use MCP servers for external tools: @@ -230,142 +228,12 @@ Verify the successful deployment of ${input:service_name} version ${input:deploy ## Running Prompts -APM provides two ways to run prompts: **explicit scripts** (configured in `apm.yml`) and **auto-discovery** (zero configuration). - -### Auto-Discovery (Zero Configuration) - -Starting with v0.5.0, APM can automatically discover and run prompts without manual script configuration: - -```bash -# Install a prompt from any repository -apm install github/awesome-copilot/skills/review-and-refactor - -# Run it immediately - no apm.yml configuration needed! -apm run review-and-refactor -``` - -**How it works:** - -1. APM searches for prompts with matching names in this priority order: - - Local root: `./prompt-name.prompt.md` - - APM prompts directory: `.apm/prompts/prompt-name.prompt.md` - - GitHub convention: `.github/prompts/prompt-name.prompt.md` - - Dependencies: `apm_modules/**/.apm/prompts/prompt-name.prompt.md` - -2. When found, APM automatically: - - Detects installed runtime (GitHub Copilot CLI or Codex) - - Generates appropriate command with recommended flags - - Compiles prompt with parameters - - Executes through the runtime - -**Qualified paths for disambiguation:** - -If you have multiple prompts with the same name from different sources: - -```bash -# Collision detected - APM shows all matches with guidance -apm run code-review -# Error: Multiple prompts found for 'code-review': -# - owner/test-repo (apm_modules/owner/test-repo-code-review/...) -# - acme/standards (apm_modules/acme/standards/...) -# -# Use qualified path: -# apm run github/awesome-copilot/code-review -# apm run acme/standards/code-review - -# Run specific version using qualified path -apm run github/awesome-copilot/code-review --param pr_url=... -``` - -**Local prompts always take precedence** over dependency prompts with the same name. - -### Explicit Scripts (Power Users) - -For advanced use cases, define scripts explicitly in `apm.yml`: - -```yaml -scripts: - # Custom runtime flags - start: "copilot --full-auto -p analyze-logs.prompt.md" - - # Specific model selection - llm: "llm analyze-logs.prompt.md -m github/gpt-4o-mini" - - # Environment variables - debug: "RUST_LOG=debug codex analyze-logs.prompt.md" - - # Friendly aliases - review: "copilot -p code-review.prompt.md" -``` - -**Explicit scripts always take precedence** over auto-discovery. This gives power users full control while maintaining zero-config convenience for simple cases. - -### Running Scripts - -```bash -# With auto-discovery (no apm.yml scripts needed) -apm run code-review --param pull_request_url="https://github.com/org/repo/pull/123" - -# With explicit scripts -apm run start --param service_name=api-gateway --param time_window="1h" -apm run llm --param service_name=api-gateway --param time_window="1h" -apm run debug --param service_name=api-gateway --param time_window="1h" - -# Preview compiled prompts before execution -apm preview start --param service_name=api-gateway --param time_window="1h" -``` - -### Example Project Structure - -``` -my-devops-project/ -├── apm.yml # Project configuration -├── README.md # Project documentation -├── analyze-logs.prompt.md # Main log analysis prompt -├── prompts/ -│ ├── code-review.prompt.md # Code review prompt -│ └── health-check.prompt.md # Deployment health check -└── .github/ - └── workflows/ - └── apm-ci.yml # CI using APM scripts -``` - -### Corresponding apm.yml - -```yaml -name: my-devops-project -version: 1.0.0 -description: DevOps automation prompts for log analysis and system monitoring -author: Platform Team - -scripts: - # Default script using Codex runtime - start: "codex analyze-logs.prompt.md" - - # LLM script with GitHub Models - llm: "llm analyze-logs.prompt.md -m github/gpt-4o-mini" - - # Debug script with environment variables - debug: "RUST_LOG=debug codex analyze-logs.prompt.md" - - # Code review script - review: "codex prompts/code-review.prompt.md" - - # Health check script - health: "llm prompts/health-check.prompt.md -m github/gpt-4o" - -dependencies: - mcp: - - ghcr.io/github/github-mcp-server - - ghcr.io/kubernetes/k8s-mcp-server -``` +Prompts can be executed locally using APM's experimental agent workflow system. +Define scripts in your `apm.yml` or let APM auto-discover `.prompt.md` files as +runnable workflows. -This structure allows you to run any prompt via scripts: -```bash -apm run start --param service_name=api-gateway --param time_window="1h" -apm run review --param pull_request_url=https://github.com/org/repo/pull/123 -apm run health --param service_name=frontend --param deployment_version=v2.1.0 -``` +See the [Agent Workflows guide](../agent-workflows/) for setup instructions, +runtime configuration, and execution examples. ## Best Practices @@ -393,6 +261,6 @@ Keep prompts in version control alongside scripts. Use semantic versioning for b ## Next Steps -- Learn about [Runtime Integration](../../integrations/runtime-compatibility/) to setup and use different AI runtimes -- See [CLI Reference](../../reference/cli-commands/) for complete script execution commands +- Learn about [Agent Workflows](../agent-workflows/) to run prompts locally with AI runtimes +- See [CLI Reference](../../reference/cli-commands/) for complete command documentation - Check [Development Guide](../../contributing/development-guide/) for local development setup diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx index d7ef6605..1f27f42c 100644 --- a/docs/src/content/docs/index.mdx +++ b/docs/src/content/docs/index.mdx @@ -7,7 +7,7 @@ hero: tagline: Same AI coding superpowers. Every developer. By default. actions: - text: Get Started - link: /apm/getting-started/installation/ + link: /apm/getting-started/quick-start/ icon: right-arrow variant: primary - text: View on GitHub diff --git a/docs/src/content/docs/integrations/gh-aw.md b/docs/src/content/docs/integrations/gh-aw.md index 016bce9b..001b5e8a 100644 --- a/docs/src/content/docs/integrations/gh-aw.md +++ b/docs/src/content/docs/integrations/gh-aw.md @@ -1,68 +1,47 @@ --- title: "GitHub Agentic Workflows" -description: "Use APM packages with GitHub Agentic Workflows (gh-aw) for automated repository maintenance." +description: "How APM integrates with GitHub Agentic Workflows for automated agent pipelines." sidebar: - order: 1 + order: 2 --- -[GitHub Agentic Workflows](https://github.github.com/gh-aw/) (gh-aw) lets you write repository automation in markdown and run it as GitHub Actions using AI agents. APM and gh-aw complement each other naturally. +[GitHub Agentic Workflows](https://github.github.com/gh-aw/) (gh-aw) lets you write repository automation in markdown and run it as GitHub Actions using AI agents. APM and gh-aw have a native integration: gh-aw recognizes APM packages as first-class dependencies. ## How They Work Together | Tool | Role | |------|------| -| **APM** | Manages the *context* your AI agents use — skills, instructions, prompts | -| **gh-aw** | Manages the *automation* that triggers AI agents — event-driven workflows | +| **APM** | Manages the *context* your AI agents use -- skills, instructions, prompts, agents | +| **gh-aw** | Manages the *automation* that triggers AI agents -- event-driven workflows | APM defines **what** agents know. gh-aw defines **when** and **how** they act. -## Example: Automated Code Review +## Integration Approaches -1. **APM** installs your team's review standards: +### Frontmatter Dependencies (Recommended) -```yaml -# apm.yml -dependencies: - apm: - - your-org/code-review-standards - - github/awesome-copilot/agents/api-architect.agent.md -``` - -2. **gh-aw** triggers a review workflow on every PR: +gh-aw natively supports APM through a [`dependencies:` frontmatter field](https://github.github.com/gh-aw/reference/frontmatter/#apm-dependencies-dependencies). Declare APM packages directly in your workflow's frontmatter and gh-aw handles the rest. -```markdown - -# Code Review Workflow - -When a pull request is opened, review the changed files against -the project's coding standards in AGENTS.md. - -Post review comments on any violations found. -``` +**Simple array format:** -3. The AI agent uses the context APM compiled into `AGENTS.md` to perform a standards-aware review automatically. - -## Setup +```yaml +--- +on: + pull_request: + types: [opened] +engine: copilot -1. Install both tools: +dependencies: + - microsoft/apm-sample-package + - github/awesome-copilot/skills/review-and-refactor +--- -```bash -# APM -curl -sSL https://raw.githubusercontent.com/microsoft/apm/main/install.sh | sh +# Code Review -# gh-aw (GitHub CLI extension) -gh extension install github/gh-aw +Review the pull request using the installed coding standards and skills. ``` -2. Configure your project with APM packages, then add gh-aw workflows that reference the compiled context. - -## Integration Tiers - -APM integrates with GitHub Agentic Workflows at three levels of depth. - -### Tier 1: Pre-Step with apm-action (Works Today) - -The minimum viable integration. Zero changes to gh-aw. Uses the `steps:` frontmatter field: +**Object format with options:** ```yaml --- @@ -71,80 +50,106 @@ on: types: [opened] engine: copilot -steps: - - name: Install agent primitives - uses: microsoft/apm-action@v1 - with: - script: install - env: - GITHUB_TOKEN: ${{ github.token }} +dependencies: + packages: + - microsoft/apm-sample-package + - your-org/security-compliance + isolated: true --- # Issue Triage -Triage this issue using the installed compliance rules and security skills. +Analyze the opened issue for security implications. ``` -The repo has an `apm.yml` with dependencies and `apm.lock` for reproducibility. The APM action runs `apm install && apm compile` as a pre-agent step. Primitives deploy to `.github/`. The coding agent discovers them naturally. +Each entry is a standard APM package reference -- either `owner/repo` for a full package or `owner/repo/path/to/skill` for an individual primitive. + +**How it works:** + +1. The gh-aw compiler detects the `dependencies:` field in your workflow frontmatter. +2. In the **activation job**, APM resolves the full dependency tree and packs the result. +3. In the **agent job**, the bundle is unpacked into the workspace and the agent discovers the primitives. -### Tier 2: Inline Dependencies (APM Enhancement) +The APM compilation target is automatically inferred from the configured `engine:` field (`copilot`, `claude`, or `all` for other engines). No manual target configuration is needed. -Declare dependencies directly in workflow frontmatter -- no separate `apm.yml` needed: +### apm-action Pre-Step + +For more control over the installation process, use [`microsoft/apm-action@v1`](https://github.com/microsoft/apm-action) as an explicit workflow step. This approach runs `apm install && apm compile` directly, giving you access to the full APM CLI. ```yaml --- on: - issues: + pull_request: types: [opened] engine: copilot steps: - - uses: microsoft/apm-action@v1 + - name: Install agent primitives + uses: microsoft/apm-action@v1 with: - dependencies: | - microsoft/compliance-rules@v2.1.0 - myorg/security-skill@v1.0.0 - isolated: true + script: install + env: + GITHUB_TOKEN: ${{ github.token }} --- -# Issue Triage -Analyze the opened issue for security implications. +# Code Review + +Review the PR using the installed coding standards. ``` -`isolated: true` means: install packages to a clean workspace, ignore the repo's existing `.github/instructions/`. The agent sees only APM-managed context. +The repo needs an `apm.yml` with dependencies and `apm.lock` for reproducibility. The action runs as a pre-agent step, deploying primitives to `.github/` where the agent discovers them. + +**When to use this over frontmatter dependencies:** -### Tier 3: Native Frontmatter Integration (Future Vision) +- Custom compilation options (specific targets, flags) +- Running additional APM commands (audit, preview) +- Workflows that need `apm.yml`-based configuration +- Debugging dependency resolution -The endgame: gh-aw recognizes APM as a dependency manager natively via an `apm:` frontmatter field. No `steps:` boilerplate. Subject to gh-aw team collaboration. +## Using APM Bundles -## Using APM Bundles with gh-aw +For sandboxed environments where network access is restricted during workflow execution, use pre-built APM bundles: -For sandboxed environments where network access is restricted, use pre-built APM bundles: +1. Run `apm pack` in your CI pipeline to produce a self-contained bundle. +2. Distribute the bundle as a workflow artifact or commit it to the repository. +3. Reference the bundled primitives in your workflow. ```yaml --- on: pull_request engine: copilot imports: - - .github/agents/code-reviewer.md # produced by APM bundle - - .github/agents/security-auditor.md # produced by APM bundle + - .github/agents/code-reviewer.md + - .github/agents/security-auditor.md --- # Code Review Review the PR using team standards. ``` -Bundles complement gh-aw's native `imports:` -- resolving full dependency trees rather than individual files, with zero network required at workflow runtime. +Bundles resolve full dependency trees ahead of time, so workflows need zero network access at runtime. -See the [CI/CD Integration guide](/apm/integrations/ci-cd/) for details on building and distributing bundles. +See the [CI/CD Integration guide](../ci-cd/) for details on building and distributing bundles. -## Solving Instruction Pollution +## Isolated Mode + +When a gh-aw workflow runs in a repository that already has developer-focused instructions (like "use 4-space tabs" or "prefer functional style"), those instructions become noise for an automated agent that should only follow its declared dependencies. + +The `isolated` flag addresses this. When set to `true` in the object format: + +```yaml +dependencies: + packages: + - your-org/triage-rules + isolated: true +``` -When a gh-aw workflow runs in a repo with developer-focused instructions (like "use 4-space tabs"), those instructions become noise for an automated triage bot. APM's `--isolated` mode (Tier 2) addresses this by creating a clean execution context with only the workflow's declared dependencies. +gh-aw clears existing `.github/` primitive directories (instructions, skills, agents) before unpacking the APM bundle. The agent sees only the context declared by the workflow, preventing instruction pollution from the host repository. ## Learn More - [gh-aw Documentation](https://github.github.com/gh-aw/) -- [APM Compilation Guide](/apm/guides/compilation/) -- [APM CLI Reference](/apm/reference/cli-commands/) -- [CI/CD Integration](/apm/integrations/ci-cd/) +- [gh-aw Frontmatter Reference](https://github.github.com/gh-aw/reference/frontmatter/) +- [APM Compilation Guide](../../guides/compilation/) +- [APM CLI Reference](../../reference/cli-commands/) +- [CI/CD Integration](../ci-cd/) diff --git a/docs/src/content/docs/integrations/runtime-compatibility.md b/docs/src/content/docs/integrations/runtime-compatibility.md index a71c7284..2352175f 100644 --- a/docs/src/content/docs/integrations/runtime-compatibility.md +++ b/docs/src/content/docs/integrations/runtime-compatibility.md @@ -6,6 +6,8 @@ sidebar: APM manages LLM runtime installation and configuration automatically. This guide covers the supported runtimes, how to use them, and how to extend APM with additional runtimes. +> **Note:** This page covers APM's experimental runtime management. See also the [Agent Workflows guide](../../guides/agent-workflows/) for running workflows locally. + ## Overview APM acts as a runtime package manager, downloading and configuring LLM runtimes from their official sources. Currently supports three runtimes: diff --git a/docs/src/content/docs/introduction/key-concepts.md b/docs/src/content/docs/introduction/key-concepts.md index f84d4598..3a4a3f04 100644 --- a/docs/src/content/docs/introduction/key-concepts.md +++ b/docs/src/content/docs/introduction/key-concepts.md @@ -10,13 +10,13 @@ Context components are the configurable tools that deploy proven prompt engineer APM implements Context - the configurable tools that deploy prompt engineering and context engineering techniques to transform unreliable AI interactions into engineered systems. -### 🏗️ Initialize a project with AI-Native structure +### Initialize a project with AI-Native structure ```bash apm init my-project # Creates complete Context scaffolding + apm.yml ``` -### ⚙️ Generated Project Structure +### Generated Project Structure ```yaml my-project/ @@ -36,7 +36,7 @@ my-project/ └── architecture.context.md # Project patterns and decisions ``` -### 🔄 Intelligent Compilation +### Intelligent Compilation APM automatically compiles your primitives into optimized AGENTS.md files using mathematical optimization: @@ -66,9 +66,8 @@ dependencies: **Share and reuse across projects:** ```bash -apm install # Install MCP dependencies -apm run impl-copilot --param feature="user-auth" -apm run review-copilot --param files="src/auth/" +apm install # Install dependencies and deploy primitives +apm compile # Generate optimized AGENTS.md files ``` ## Overview @@ -434,7 +433,7 @@ APM automatically resolves context file links during installation and compilatio 3. **Direct Linking**: Links point to files in `apm_modules/` and `.apm/` directories 4. **Persistence**: Commit `apm_modules/` for link availability, or run `apm install` in CI/CD -**Result**: Links work everywhere—IDE, GitHub, all coding agents—pointing directly to source files. +**Result**: Links work in IDE and GitHub, pointing directly to source files. Copilot and Claude resolve links natively via `apm install`; other tools pick them up through `apm compile`. ### Link Resolution Examples diff --git a/docs/src/content/docs/introduction/what-is-apm.md b/docs/src/content/docs/introduction/what-is-apm.md index c9cbdcd4..9e0be2bc 100644 --- a/docs/src/content/docs/introduction/what-is-apm.md +++ b/docs/src/content/docs/introduction/what-is-apm.md @@ -126,25 +126,35 @@ running `apm install` on the same lock file get identical setups. **Build.** `apm compile` produces optimized output files for each AI tool — `AGENTS.md` for Copilot, Cursor, and Codex; `CLAUDE.md` for Claude. +`apm pack` creates self-contained bundles for portable distribution. ```bash apm compile +apm pack ``` **Distribute.** Any git repository is a valid APM package. Publish by pushing -to a git remote. No registry required. +to a git remote — no registry required. For offline distribution, CI artifact +pipelines, or air-gapped environments, use `apm pack` and `apm unpack` to +create and consume portable bundles without network access. ## Supported tools -APM compiles agent configuration into the native format of each supported tool: - -| AI Tool | Output format | Integration | -|---|---|---| -| GitHub Copilot | `AGENTS.md`, `.github/instructions/`, `.github/prompts/` | Full | -| Cursor | `.cursor/rules/`, `.cursor/prompts/` | Full | -| Claude | `CLAUDE.md`, `.claude/commands/` | Full | -| Codex | `AGENTS.md` | Full | -| Gemini | `GEMINI.md` | Full | +APM deploys and compiles agent configuration into the native format of each +supported tool: + +| AI Tool | What `apm install` deploys | What `apm compile` adds | Support level | +|---|---|---|---| +| GitHub Copilot | `.github/instructions/`, `.github/prompts/`, agents, hooks, plugins, MCP | `AGENTS.md` (optional) | **Full** | +| Claude | `.claude/` commands, skills, MCP | `CLAUDE.md` | **Full** | +| Cursor | — | `.cursor/rules/` | Instructions via compile | +| Codex CLI | — | `AGENTS.md` | Instructions via compile | +| Gemini | — | `GEMINI.md` | Instructions via compile | + +For tools with **Full** support, `apm install` deploys all primitives in their +native format — no additional steps needed. For other tools, `apm compile` +generates their configuration format from your instructions. See the +[Compilation guide](../../guides/compilation/) for details. The output is native. Each tool reads its own format — APM is transparent to the AI agent at runtime. diff --git a/docs/src/content/docs/reference/cli-commands.md b/docs/src/content/docs/reference/cli-commands.md index eaf2f66a..4038c80d 100644 --- a/docs/src/content/docs/reference/cli-commands.md +++ b/docs/src/content/docs/reference/cli-commands.md @@ -695,10 +695,12 @@ apm mcp show a5e8a7f0-d4e4-4a1d-b12f-2896a23fd4f1 - Available installation packages - Installation instructions -### `apm run` - Execute prompts +### `apm run` (Experimental) - Execute prompts Execute a script defined in your apm.yml with parameters and real-time output streaming. +> See the [Agent Workflows guide](../../guides/agent-workflows/) for usage details. + ```bash apm run [SCRIPT_NAME] [OPTIONS] ``` @@ -1012,12 +1014,14 @@ apm config set auto-integrate yes apm config set auto-integrate 1 ``` -## Runtime Management +## Runtime Management (Experimental) -### `apm runtime` - Manage AI runtimes +### `apm runtime` (Experimental) - Manage AI runtimes APM manages AI runtime installation and configuration automatically. Currently supports three runtimes: `copilot`, `codex`, and `llm`. +> See the [Agent Workflows guide](../../guides/agent-workflows/) for usage details. + ```bash apm runtime COMMAND [OPTIONS] ``` diff --git a/docs/src/content/docs/reference/examples.md b/docs/src/content/docs/reference/examples.md index 5542fc72..bda59bbd 100644 --- a/docs/src/content/docs/reference/examples.md +++ b/docs/src/content/docs/reference/examples.md @@ -6,6 +6,8 @@ sidebar: This guide showcases real-world APM workflows, from simple automation to enterprise-scale AI development patterns. Learn through practical examples that demonstrate the power of structured AI workflows. +> **Note:** Examples using `apm run` reference APM's experimental [Agent Workflows](../../guides/agent-workflows/) feature. + ## Before & After: Traditional vs APM ### Traditional Approach (Unreliable)