Add APM CLI - init, install, compile, deps

.github/CODEOWNERS

@@ -1,2 +1,7 @@
 # Global code owner
 * @localden
+
+# APM CLI code owner
+src/apm_cli/ @danielmeppiel
+templates/apm/ @danielmeppiel
+docs/context-management.md @danielmeppiel

README.md

@@ -18,7 +18,8 @@
 - [⚡ Get started](#-get-started)
 - [📽️ Video Overview](#️-video-overview)
 - [🔧 Specify CLI Reference](#-specify-cli-reference)
-- [📚 Core philosophy](#-core-philosophy)
+- [� APM Integration](#-apm-integration)
+- [�📚 Core philosophy](#-core-philosophy)
 - [🌟 Development phases](#-development-phases)
 - [🎯 Experimental goals](#-experimental-goals)
 - [🔧 Prerequisites](#-prerequisites)
@@ -82,6 +83,7 @@ The `specify` command supports the following options:
 |-------------|----------------------------------------------------------------|
 | `init`      | Initialize a new Specify project from the latest template      |
 | `check`     | Check for installed tools (`git`, `claude`, `gemini`, `code`/`code-insiders`, `cursor-agent`) |
+| `apm`       | APM - Agent Package Manager commands for Context management   |
 
 ### `specify init` Arguments & Options
 
@@ -95,6 +97,7 @@ The `specify` command supports the following options:
 | `--here`               | Flag     | Initialize project in the current directory instead of creating a new one   |
 | `--skip-tls`           | Flag     | Skip SSL/TLS verification (not recommended)                                 |
 | `--debug`              | Flag     | Enable detailed debug output for troubleshooting                            |
+| `--use-apm`            | Flag     | Include APM (Agent Package Manager) structure for context management       |
 
 ### Examples
 
@@ -105,14 +108,17 @@ specify init my-project
 # Initialize with specific AI assistant
 specify init my-project --ai claude
 
+# Initialize with APM support
+specify init my-project --ai claude --use-apm
+
 # Initialize with Cursor support
 specify init my-project --ai cursor
 
 # Initialize with PowerShell scripts (Windows/cross-platform)
 specify init my-project --ai copilot --script ps
 
-# Initialize in current directory
-specify init --here --ai copilot
+# Initialize in current directory with APM
+specify init --here --ai copilot --use-apm
 
 # Skip git initialization
 specify init my-project --ai gemini --no-git
@@ -124,7 +130,49 @@ specify init my-project --ai claude --debug
 specify check
 ```
 
-## 📚 Core philosophy
+## 📦 APM Integration - NPM for Agent Context
+
+**Context as Code Packages**: Package and share agent intelligence like npm packages. With APM, your agents get:
+
+- **Team knowledge** from reusable context packages
+- **Optimized context** through mathematical relevance scoring  
+- **Universal compatibility** via dynamically generated Agents.md files
+
+[Complete Context Management Guide →](docs/context-management.md)
+
+Spec Kit includes full APM (Agent Package Manager) functionality for managing modular context packages and files:
+
+### Unified Initialization
+```bash
+# The --use-apm flag creates both SDD and APM structures 
+specify init my-project --ai claude --use-apm
+```
+
+### APM Commands
+```bash
+# Core APM commands available under 'apm' subcommand
+
+# Install APM packages from apm.yml
+specify apm install       
+
+# Add APM package to apm.yml and install                      
+specify apm install org/repo   
+
+# Remove package from apm.yml and apm_modules
+specify apm uninstall org/repo              
+
+# Remove orphaned packages not in apm.yml
+specify apm prune   
+
+# List installed APM packages
+specify apm deps list    
+
+# Generate nested optimal AGENTS.md tree
+# Uses installed APM packages and local context files
+specify apm compile                                
+```
+
+## �📚 Core philosophy
 
 Spec-Driven Development is a structured process that emphasizes:
 
@@ -427,6 +475,7 @@ rm gcm-linux_amd64.2.6.1.deb
 
 - Den Delimarsky ([@localden](https://github.com/localden))
 - John Lam ([@jflam](https://github.com/jflam))
+- Daniel Meppiel [@danielmeppiel](https://github.com/danielmeppiel)
 
 ## 💬 Support
 

docs/context-management.md

@@ -0,0 +1,59 @@
+# Context Management with APM
+
+## NPM for Agent Context
+
+Just like npm revolutionized JavaScript by enabling package reuse, APM creates an ecosystem for sharing agent context.
+
+## Package Composition & Reuse
+
+```yaml
+# Your project inherits team knowledge via apm.yml file in the root
+dependencies:
+  apm:
+    - company/design-system     # UI patterns, brand guidelines
+    - company/security-standards # Auth patterns, data handling
+    - community/best-practices  # Industry standards
+```
+
+**Result**: Your project gets all the instructions of above packages applied via dynamically generated Agents.md files using `specify apm compile`. These files are optimally generated to minimize contextual load for Agents compatible with the Agents.md standard.
+
+**Enterprise Scenario**: Design team creates accessibility guidelines once → entire organization uses them → agents work consistently across all projects.
+
+## Mathematical Context Optimization
+
+**The Technical Foundation**: APM uses mathematical optimization to solve the context efficiency problem.
+
+```
+Context_Efficiency = Relevant_Instructions / Total_Instructions_Loaded
+```
+
+**Why This Matters**: When agents work in `/styles/` directory, they shouldn't load Python compliance rules. APM's Context Optimization Engine ensures agents get minimal, highly relevant context.
+
+**The Algorithm**: Constraint satisfaction optimization that finds placement minimizing context pollution while maximizing relevance. Each instruction gets mathematically optimal placement across the project hierarchy.
+
+## Quick Start
+
+```bash
+specify init my-project --use-apm --ai copilot
+specify apm install company/design-system  
+specify apm compile  # Mathematical optimization generates distributed AGENTS.md files
+```
+
+## Universal Agent Compatibility
+
+APM generates distributed `AGENTS.md` files compatible with the [agents.md standard](https://agents.md), working with any coding agent (GitHub Copilot, Cursor, Claude, Codex, Aider, etc.).
+
+## Authentication Setup (Optional)
+
+```bash
+export GITHUB_APM_PAT=your_fine_grained_token_here
+```
+
+Only needed for private packages. Public community packages work without authentication.
+
+## The Complete Value
+
+1. **Package Ecosystem** - Share and compose agent intelligence like code dependencies
+2. **Mathematical Optimization** - Context Optimization Engine ensures relevance without pollution  
+3. **Universal Standards** - Works with any agent via industry-standard agents.md format
+4. **Enterprise Ready** - Team knowledge scales across entire organizations

pyproject.toml

@@ -4,20 +4,41 @@ version = "0.0.4"
 description = "Setup tool for Specify spec-driven development projects"
 requires-python = ">=3.11"
 dependencies = [
+    # Existing spec-kit dependencies
     "typer",
-    "rich",
+    "rich>=13.0.0",
     "httpx[socks]",
     "platformdirs",
     "readchar",
     "truststore>=0.10.4",
+    # APM dependencies (from awd-cli, excluding runtime/embargo items)
+    "click>=8.0.0",
+    "colorama>=0.4.6",
+    "pyyaml>=6.0.0",
+    "requests>=2.28.0",
+    "python-frontmatter>=1.0.0",
+    "tomli>=1.2.0; python_version<'3.11'",
+    "toml>=0.10.2",
+    "rich-click>=1.7.0",
+    "watchdog>=3.0.0",
+    "GitPython>=3.1.0",
 ]
 
 [project.scripts]
 specify = "specify_cli:main"
 
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "black>=23.0.0",
+    "isort>=5.0.0",
+    "mypy>=1.0.0",
+]
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
-packages = ["src/specify_cli"]
+packages = ["src/specify_cli", "src/apm_cli"]

src/apm_cli/__init__.py

@@ -0,0 +1,5 @@
+"""APM-CLI package."""
+
+from .version import get_version
+
+__version__ = get_version()

src/apm_cli/adapters/__init__.py

@@ -0,0 +1 @@
+"""Adapters package."""

src/apm_cli/adapters/client/__init__.py

@@ -0,0 +1 @@
+"""Client adapters package."""

src/apm_cli/adapters/client/base.py

@@ -0,0 +1,39 @@
+"""Base adapter interface for MCP clients."""
+
+from abc import ABC, abstractmethod
+
+
+class MCPClientAdapter(ABC):
+    """Base adapter for MCP clients."""
+
+    @abstractmethod
+    def get_config_path(self):
+        """Get the path to the MCP configuration file."""
+        pass
+
+    @abstractmethod
+    def update_config(self, config_updates):
+        """Update the MCP configuration."""
+        pass
+
+    @abstractmethod
+    def get_current_config(self):
+        """Get the current MCP configuration."""
+        pass
+
+    @abstractmethod
+    def configure_mcp_server(self, server_url, server_name=None, enabled=True, env_overrides=None, server_info_cache=None, runtime_vars=None):
+        """Configure an MCP server in the client configuration.
+
+        Args:
+            server_url (str): URL of the MCP server.
+            server_name (str, optional): Name of the server. Defaults to None.
+            enabled (bool, optional): Whether to enable the server. Defaults to True.
+            env_overrides (dict, optional): Environment variable overrides. Defaults to None.
+            server_info_cache (dict, optional): Pre-fetched server info to avoid duplicate registry calls.
+            runtime_vars (dict, optional): Runtime variable values. Defaults to None.
+
+        Returns:
+            bool: True if successful, False otherwise.
+        """
+        pass