feat: add support for Awesome Copilot Collections as APM packages

CHANGELOG.md

@@ -5,6 +5,38 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2025-10-30
+
+### Added - Virtual Packages
+- **Virtual Package Support**: Install individual files directly from any repository without requiring full APM package structure
+  - Individual file packages: `apm install owner/repo/path/to/file.prompt.md`
+- **Collection Support**: Install curated collections of primitives from [Awesome Copilot](https://github.com/github/awesome-copilot): `apm install github/awesome-copilot/collections/collection-name`
+  - Collection manifest parser for `.collection.yml` format
+  - Batch download of collection items into organized `.apm/` structure
+  - Integration with github/awesome-copilot collections
+
+### Added - Runnable Prompts
+- **Auto-Discovery of Prompts**: Run installed prompts without manual script configuration
+  - `apm run <prompt-name>` automatically discovers and executes prompts without having to wire a script in `apm.yml`
+  - Search priority: local root → .apm/prompts → .github/prompts → dependencies
+  - Qualified path support: `apm run owner/repo/prompt-name` for disambiguation
+  - Collision detection with helpful error messages when multiple prompts found
+  - Explicit scripts in apm.yml always take precedence over auto-discovery
+- **Automatic Runtime Detection**: Detects installed runtime (copilot > codex) and generates proper commands
+- **Zero-Configuration Execution**: Install and run prompts immediately without apm.yml scripts section
+
+### Changed
+- Enhanced dependency resolution to support virtual package unique keys
+- Improved GitHub downloader with virtual file and collection package support
+- Extended `DependencyReference.parse()` to detect and validate virtual packages (3+ path segments)
+- Script runner now falls back to prompt discovery when script not found in apm.yml
+
+### Developer Experience
+- Streamlined workflow: `apm install <file>` → `apm run <name>` works immediately
+- No manual script configuration needed for simple use cases
+- Power users retain full control via explicit scripts in apm.yml
+- Better error messages for ambiguous prompt names with disambiguation guidance
+
 ## [0.4.3] - 2025-10-29
 
 ### Added

README.md

@@ -11,8 +11,6 @@
 ✅ **2-minute setup** - zero config  
 ✅ **Team collaboration** - composable context, without wheel reinvention
 
-**Compound innovation** - reuse [packages built with APM by the community](#built-with-apm)
-
 ## What Goes in Packages
 
 📦 **Mix and match what your team needs**:
@@ -22,7 +20,7 @@
 
 ![APM Demo](docs/apm-demo.gif)
 
-## Quick Start (2 minutes)
+## Quick Start
 
 > [!NOTE] 
 > **📋 Prerequisites**: Get tokens at [github.com/settings/personal-access-tokens/new](https://github.com/settings/personal-access-tokens/new)  
@@ -31,29 +29,41 @@
 >
 > 📖 **Complete Setup Guide**: [Getting Started](docs/getting-started.md)
 
-```bash
-# 1. Set your GitHub token (minimal setup)
-export GITHUB_COPILOT_PAT=your_fine_grained_token_here
+### 30 Seconds: Zero-Config Prompt Execution
 
-# 2. Install APM CLI
+```bash
+# Set up APM (one-time)
+export GITHUB_COPILOT_PAT=your_token_here
 curl -sSL "https://raw.githubusercontent.com/danielmeppiel/apm/main/install.sh" | sh
 
-# 3. Set up runtime (GitHub Copilot CLI with native MCP support)
+# 3. Set up GitHub Copilot CLI
 apm runtime setup copilot
 
-# 3. Create your first AI package
+# Run any prompt from GitHub - zero config needed
+apm run github/awesome-copilot/prompts/architecture-blueprint-generator
+```
+
+### 2 Minutes: Guardrailing with packaged context
+
+```bash
+# Create project with layered context from multiple APM packages
 apm init my-project && cd my-project
 
-# 4. Install APM and MCP dependencies
-apm install
+# Install context + workflows from packages
+apm install danielmeppiel/design-guidelines
+apm install danielmeppiel/compliance-rules
+
+# Compile into single AGENTS.md guardrails
+# Now all agents respect design + compliance rules automatically
+apm compile
 
-# 5. Run your first workflow
-apm compile && apm run start --param name="<YourGitHubHandle>"
+# Run a prompt from the installed packages above
+apm run design-review
 ```
 
 **That's it!** Your project now has reliable AI workflows that work with any coding agent.
 
-**GitHub Enterprise Support:** Works with Enterprise Server and Data Residency Cloud. [Configuration →](docs/getting-started.md#github-enterprise-support)
+**GitHub Enterprise**: Works with GitHub Enterprise Server and Data Residency Cloud. [Configuration →](docs/getting-started.md#github-enterprise-support)
 
 ### Example `apm.yml` - Like package.json for AI Native projects
 

docs/getting-started.md

@@ -443,22 +443,62 @@ apm install myorg/templates/chatmodes/assistant.chatmode.md@v2.1.0
 # 2. Install specific file
 apm install awesome-org/best-practices/prompts/security-scan.prompt.md
 
-# 3. Use immediately
-apm compile
-apm run security-scan
+# 3. Use immediately - no apm.yml configuration needed!
+apm run security-scan --param target="./src"
 
-# 4. Add to apm.yml for team
-echo "  - awesome-org/best-practices/prompts/security-scan.prompt.md" >> apm.yml
+# 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/prompts/architecture-blueprint-generator.prompt.md
+
+# 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](prompts.md#running-prompts) for complete auto-discovery documentation.
+
 ### 5. Run Your First Workflow
 
 Execute the default "start" workflow:

docs/prompts.md

@@ -226,24 +226,89 @@ Verify the successful deployment of ${input:service_name} version ${input:deploy
 
 ## Running Prompts
 
-Prompts are executed through scripts defined in your `apm.yml`. When a script references a `.prompt.md` file, APM compiles it with parameter substitution before execution:
+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
-# Run scripts that reference .prompt.md files
-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"
+# Install a prompt from any repository
+apm install github/awesome-copilot/prompts/code-review.prompt.md
 
-# Preview compiled prompts before execution
-apm preview start --param service_name=api-gateway --param time_window="1h"
+# Run it immediately - no apm.yml configuration needed!
+apm run code-review
 ```
 
-**Script Configuration (apm.yml):**
+**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':
+#   - github/awesome-copilot (apm_modules/github/awesome-copilot-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:
-  start: "codex analyze-logs.prompt.md"
+  # 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

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "apm-cli"
-version = "0.4.3"
+version = "0.5.0"
 description = "MCP configuration tool"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -72,4 +72,5 @@ warn_unused_configs = true
 [tool.pytest.ini_options]
 markers = [
     "integration: marks tests as integration tests that may require network access",
+    "slow: marks tests as slow running tests",
 ]

scripts/github-token-helper.sh

@@ -25,16 +25,6 @@ setup_github_tokens() {
         echo -e "${BLUE}Setting up GitHub tokens...${NC}"
     fi
 
-    # DEBUG: Show all GitHub-related environment variables
-    echo -e "${YELLOW}🔍 DEBUG: GitHub token environment analysis:${NC}"
-    echo "  GITHUB_TOKEN: ${GITHUB_TOKEN:+SET(${#GITHUB_TOKEN} chars)}${GITHUB_TOKEN:-UNSET}"
-    echo "  GITHUB_APM_PAT: ${GITHUB_APM_PAT:+SET(${#GITHUB_APM_PAT} chars)}${GITHUB_APM_PAT:-UNSET}"
-    echo "  GH_MODELS_PAT: ${GH_MODELS_PAT:+SET(${#GH_MODELS_PAT} chars)}${GH_MODELS_PAT:-UNSET}"
-    echo "  GH_CLI_PAT: ${GH_CLI_PAT:+SET(${#GH_CLI_PAT} chars)}${GH_CLI_PAT:-UNSET}"
-    echo "  GH_PKG_PAT: ${GH_PKG_PAT:+SET(${#GH_PKG_PAT} chars)}${GH_PKG_PAT:-UNSET}"
-    echo "  CI environment: ${CI:-UNSET}"
-    echo "  GITHUB_ACTIONS: ${GITHUB_ACTIONS:-UNSET}"
-
     # CRITICAL: Preserve existing GITHUB_TOKEN if set (for Models access)
     local preserve_github_token=""
     if [[ -n "${GITHUB_TOKEN:-}" ]]; then
@@ -72,13 +62,7 @@ setup_github_tokens() {
     if [[ -n "${GITHUB_TOKEN:-}" ]] && [[ -z "${GITHUB_MODELS_KEY:-}" ]]; then
         export GITHUB_MODELS_KEY="${GITHUB_TOKEN}"
     fi
-
-    # DEBUG: Show final token state
-    echo -e "${YELLOW}🔍 DEBUG: Final token configuration:${NC}"
-    echo "  GITHUB_TOKEN: ${GITHUB_TOKEN:+SET(${#GITHUB_TOKEN} chars)}${GITHUB_TOKEN:-UNSET}"
-    echo "  GITHUB_APM_PAT: ${GITHUB_APM_PAT:+SET(${#GITHUB_APM_PAT} chars)}${GITHUB_APM_PAT:-UNSET}"
-    echo "  GITHUB_MODELS_KEY: ${GITHUB_MODELS_KEY:+SET(${#GITHUB_MODELS_KEY} chars)}${GITHUB_MODELS_KEY:-UNSET}"
-
+
     if [[ "$quiet_mode" != "true" ]]; then
         echo -e "${GREEN}✅ GitHub token environment configured${NC}"
     fi

scripts/runtime/setup-codex.sh

@@ -91,11 +91,6 @@ setup_codex() {
         local latest_release_url="https://api.github.com/repos/$CODEX_REPO/releases/latest"
         local latest_tag
 
-        # DEBUG: Show token state right before API call
-        log_info "🔍 DEBUG: Token state before GitHub API call:"
-        log_info "  GITHUB_TOKEN: ${GITHUB_TOKEN:+SET(${#GITHUB_TOKEN} chars)}${GITHUB_TOKEN:-UNSET}"
-        log_info "  GITHUB_APM_PAT: ${GITHUB_APM_PAT:+SET(${#GITHUB_APM_PAT} chars)}${GITHUB_APM_PAT:-UNSET}"
-
         # Try to get the latest release tag using curl
         if command -v curl >/dev/null 2>&1; then
             # Use authenticated request if GITHUB_TOKEN or GITHUB_APM_PAT is available