agnostic-prompt-aps 1.1.5__py3-none-any.whl → 1.1.7__py3-none-any.whl

aps_cli/core.py

@@ -3,21 +3,51 @@ from __future__ import annotations
 import json
 import os
 import shutil
-from dataclasses import dataclass
+import sys
+from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Iterable, Optional
+from typing import Callable, Literal, Optional
+
+from .schemas import safe_parse_platform_manifest
 
 SKILL_ID = "agnostic-prompt-standard"
 
+# Explicit ordering for known adapters in UI
+DEFAULT_ADAPTER_ORDER: tuple[str, ...] = ("vscode-copilot", "claude-code", "opencode")
+
+KnownAdapterId = Literal["vscode-copilot", "claude-code", "opencode"]
+
+
+@dataclass(frozen=True)
+class DetectionMarker:
+    """A marker file or directory used to detect a platform."""
+
+    kind: Literal["file", "dir"]
+    label: str
+    rel_path: str
+
 
 @dataclass(frozen=True)
 class Platform:
+    """Information about a platform adapter."""
+
     platform_id: str
     display_name: str
     adapter_version: Optional[str]
+    detection_markers: tuple[DetectionMarker, ...] = field(default_factory=tuple)
+
+
+@dataclass(frozen=True)
+class AdapterDetection:
+    """Result of detecting a platform adapter in a workspace."""
+
+    platform_id: str
+    detected: bool
+    reasons: tuple[str, ...]
 
 
 def is_tty() -> bool:
+    """Check if running in interactive terminal."""
     try:
         return bool(os.isatty(0) and os.isatty(1))
     except Exception:
@@ -25,6 +55,7 @@ def is_tty() -> bool:
 
 
 def find_repo_root(start_dir: Path) -> Optional[Path]:
+    """Find git repository root by walking up from start directory."""
     cur = start_dir.resolve()
     while True:
         if (cur / ".git").exists():
@@ -35,6 +66,13 @@ def find_repo_root(start_dir: Path) -> Optional[Path]:
         cur = parent
 
 
+def pick_workspace_root(cli_root: Optional[str]) -> Optional[Path]:
+    """Resolve workspace root from CLI option or auto-detect."""
+    if cli_root:
+        return Path(cli_root).expanduser().resolve()
+    return find_repo_root(Path.cwd())
+
+
 def default_project_skill_path(repo_root: Path, *, claude: bool = False) -> Path:
     """Return the project-skill path for the detected agent ecosystem.
 
@@ -55,11 +93,70 @@ def default_personal_skill_path(*, claude: bool = False) -> Path:
     return base / SKILL_ID
 
 
+def is_claude_platform(platform_id: str) -> bool:
+    """Check if platform uses Claude-specific paths."""
+    return platform_id == "claude-code"
+
+
+def compute_skill_destinations(
+    scope: Literal["repo", "personal"],
+    workspace_root: Optional[Path],
+    selected_platforms: list[str],
+) -> list[Path]:
+    """Compute skill installation destinations based on selected platforms.
+
+    Args:
+        scope: Installation scope (repo or personal)
+        workspace_root: Workspace root path (required for repo scope)
+        selected_platforms: List of selected platform IDs
+
+    Returns:
+        List of unique destination paths
+    """
+    wants_claude = any(is_claude_platform(p) for p in selected_platforms)
+    wants_non_claude = any(not is_claude_platform(p) for p in selected_platforms)
+
+    # Default to non-Claude location if no adapters selected
+    include_claude = wants_claude
+    include_non_claude = wants_non_claude or len(selected_platforms) == 0
+
+    if scope == "repo":
+        if not workspace_root:
+            raise ValueError("Repo install selected but no workspace root found.")
+        dests: list[Path] = []
+        if include_non_claude:
+            dests.append(default_project_skill_path(workspace_root, claude=False))
+        if include_claude:
+            dests.append(default_project_skill_path(workspace_root, claude=True))
+        return _unique_paths(dests)
+
+    dests = []
+    if include_non_claude:
+        dests.append(default_personal_skill_path(claude=False))
+    if include_claude:
+        dests.append(default_personal_skill_path(claude=True))
+    return _unique_paths(dests)
+
+
+def _unique_paths(paths: list[Path]) -> list[Path]:
+    """Remove duplicate paths while preserving order."""
+    seen: set[Path] = set()
+    out: list[Path] = []
+    for p in paths:
+        if p not in seen:
+            seen.add(p)
+            out.append(p)
+    return out
+
+
 def infer_platform_id(workspace_root: Path) -> Optional[str]:
+    """Infer platform ID based on workspace directory structure (legacy)."""
     gh = workspace_root / ".github"
     has_agents = (gh / "agents").exists()
     has_prompts = (gh / "prompts").exists()
-    has_instructions = (gh / "copilot-instructions.md").exists() or (gh / "instructions").exists()
+    has_instructions = (gh / "copilot-instructions.md").exists() or (
+        gh / "instructions"
+    ).exists()
     if has_agents or has_prompts or has_instructions:
         return "vscode-copilot"
     return None
@@ -83,12 +180,16 @@ def resolve_payload_skill_dir() -> Path:
     if dev.is_dir():
         return dev
 
-    raise FileNotFoundError("APS payload not found. (Did you run tools/sync_payload.py before building?)")
+    raise FileNotFoundError(
+        "APS payload not found. (Did you run tools/sync_payload.py before building?)"
+    )
 
 
 def load_platforms(skill_dir: Path) -> list[Platform]:
+    """Load all platform adapters from the skill's platforms directory."""
     platforms_dir = skill_dir / "platforms"
     out: list[Platform] = []
+
     for entry in platforms_dir.iterdir():
         if not entry.is_dir():
             continue
@@ -97,42 +198,152 @@ def load_platforms(skill_dir: Path) -> list[Platform]:
         manifest_path = entry / "manifest.json"
         if not manifest_path.exists():
             continue
+
         try:
-            manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+            raw = json.loads(manifest_path.read_text(encoding="utf-8"))
         except Exception:
             continue
-        platform_id = manifest.get("platformId", entry.name)
-        display_name = manifest.get("displayName", entry.name)
-        adapter_version = manifest.get("adapterVersion")
+
+        # Validate with Pydantic
+        manifest, error = safe_parse_platform_manifest(raw)
+        if error:
+            print(
+                f"Warning: Invalid platform manifest at {manifest_path}: {error}",
+                file=sys.stderr,
+            )
+            # Fall back to partial extraction
+            platform_id = raw.get("platformId", entry.name)
+            display_name = raw.get("displayName", entry.name)
+            adapter_version = raw.get("adapterVersion")
+            detection_markers: tuple[DetectionMarker, ...] = ()
+        else:
+            assert manifest is not None
+            platform_id = manifest.platform_id
+            display_name = manifest.display_name
+            adapter_version = manifest.adapter_version
+            # Get normalized detection markers from manifest
+            detection_markers = tuple(
+                DetectionMarker(
+                    kind=m.kind,  # type: ignore[arg-type]
+                    label=m.label,
+                    rel_path=m.rel_path,
+                )
+                for m in manifest.detection_markers
+            )
+
         out.append(
             Platform(
                 platform_id=platform_id,
                 display_name=display_name,
                 adapter_version=adapter_version,
+                detection_markers=detection_markers,
             )
         )
-    out.sort(key=lambda p: p.display_name.lower())
+
+    return out
+
+
+def sort_platforms_for_ui(platforms: list[Platform]) -> list[Platform]:
+    """Sort platforms with known adapters first in defined order."""
+    known_order = {pid: i for i, pid in enumerate(DEFAULT_ADAPTER_ORDER)}
+    known = [p for p in platforms if p.platform_id in known_order]
+    remaining = [p for p in platforms if p.platform_id not in known_order]
+
+    known.sort(key=lambda p: known_order[p.platform_id])
+    remaining.sort(key=lambda p: p.display_name.lower())
+
+    return known + remaining
+
+
+def _marker_exists(workspace_root: Path, marker: DetectionMarker) -> bool:
+    """Check if a marker file or directory exists."""
+    full = workspace_root / marker.rel_path
+    if marker.kind == "dir":
+        return full.is_dir()
+    return full.exists()
+
+
+def detect_adapters(
+    workspace_root: Path, platforms: list[Platform]
+) -> dict[str, AdapterDetection]:
+    """Detect which platform adapters are present in a workspace.
+
+    Args:
+        workspace_root: Workspace root directory
+        platforms: List of platforms with detection markers
+
+    Returns:
+        Dict mapping platform IDs to detection results
+    """
+    out: dict[str, AdapterDetection] = {}
+
+    for platform in platforms:
+        reasons: list[str] = []
+        for marker in platform.detection_markers:
+            if _marker_exists(workspace_root, marker):
+                reasons.append(marker.label)
+
+        out[platform.platform_id] = AdapterDetection(
+            platform_id=platform.platform_id,
+            detected=len(reasons) > 0,
+            reasons=tuple(reasons),
+        )
+
     return out
 
 
+def format_detection_label(detection: AdapterDetection) -> str:
+    """Format a detection result as a label suffix."""
+    if not detection.detected:
+        return ""
+    return " (detected)"
+
+
+def detect_platforms(workspace_root: Path, skill_dir: Path) -> list[str]:
+    """Detect all platforms with markers present in workspace (legacy API).
+
+    Args:
+        workspace_root: Path to workspace root
+        skill_dir: Path to skill directory with platform manifests
+
+    Returns:
+        List of detected platform IDs
+    """
+    platforms = load_platforms(skill_dir)
+    detections = detect_adapters(workspace_root, platforms)
+    return [pid for pid, det in detections.items() if det.detected]
+
+
 def ensure_dir(p: Path) -> None:
+    """Ensure a directory exists, creating it recursively if needed."""
     p.mkdir(parents=True, exist_ok=True)
 
 
 def remove_dir(p: Path) -> None:
+    """Remove a directory recursively."""
     shutil.rmtree(p, ignore_errors=True)
 
 
 def copy_dir(src: Path, dst: Path) -> None:
+    """Copy a directory recursively."""
     shutil.copytree(src, dst)
 
 
+def list_files_recursive(root_dir: Path) -> list[Path]:
+    """Recursively list all files in a directory."""
+    results: list[Path] = []
+    for item in root_dir.rglob("*"):
+        if item.is_file():
+            results.append(item)
+    return results
+
+
 def copy_template_tree(
     src_dir: Path,
     dst_root: Path,
     *,
     force: bool = False,
-    filter_fn: Optional[callable] = None,
+    filter_fn: Optional[Callable[[str], bool]] = None,
 ) -> list[str]:
     """Copy template files individually with optional filtering.
 
@@ -159,6 +370,4 @@ def copy_template_tree(
         dst_file.parent.mkdir(parents=True, exist_ok=True)
         shutil.copy2(src_file, dst_file)
         copied.append(rel_str)
-    return copied
-
-
+    return copied

aps_cli/payload/agnostic-prompt-standard/SKILL.md

@@ -3,9 +3,10 @@ name: agnostic-prompt-standard
 description: The reference framework to generate, compile, and lint greenfield prompts that conform to the Agnostic Prompt Standard (APS) v1.0.
 license: MIT
 metadata:
+  repository: "https://github.com/chris-buckley/agnostic-prompt-standard"
   authors: "Christopher Buckley; Juan Burckhardt; Anastasiya Smirnova"
   spec_version: "1.0"
-  framework_revision: "1.1.5"
+  framework_revision: "1.1.7"
   last_updated: "2026-01-15"
 ---
 

aps_cli/payload/agnostic-prompt-standard/assets/formats/format-docs-index-v1.0.0.example.md

@@ -0,0 +1,25 @@
+<format id="DOCS_INDEX_V1" name="Documentation Index" purpose="Token-efficient hierarchical documentation map for AI navigation.">
+# <PROJECT_TITLE> Documentation Map
+
+> Fetch the complete documentation index at: <INDEX_URL>
+> Last updated: <TIMESTAMP>
+
+## <GROUP_NAME>
+
+### [<PAGE_TITLE>](<PAGE_URL>)
+* <HEADING_TEXT>
+  * <SUBHEADING_TEXT>
+
+...
+
+WHERE:
+- <PROJECT_TITLE> is String; name of the project or documentation set.
+- <INDEX_URL> is URI; URL where this index can be fetched.
+- <TIMESTAMP> is ISO8601; when the index was generated.
+- <GROUP_NAME> is String; documentation section/category name.
+- <PAGE_TITLE> is String; title of the documentation page.
+- <PAGE_URL> is URI; link to the documentation page.
+- <HEADING_TEXT> is String; H2/H3 heading text from the page.
+- <SUBHEADING_TEXT> is String; nested heading under parent.
+- ... denotes repetition; groups contain pages, pages contain headings.
+</format>

aps_cli/payload/agnostic-prompt-standard/platforms/_schemas/platform-manifest.schema.json

@@ -6,7 +6,8 @@
   "required": [
     "platformId",
     "displayName",
-    "adapterVersion"
+    "adapterVersion",
+    "fileConventions"
   ],
   "properties": {
     "platformId": {
@@ -60,8 +61,11 @@
         },
         "instructions": {
           "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
           "items": {
-            "type": "string"
+            "type": "string",
+            "minLength": 1
           },
           "description": "Instruction/memory file locations"
         },

aps_cli/payload/agnostic-prompt-standard/platforms/claude-code/manifest.json

@@ -3,6 +3,15 @@
   "displayName": "Claude Code CLI",
   "adapterVersion": "1.0.0",
   "lastUpdated": "2026-01-20",
+  "detectionMarkers": [
+    ".claude",
+    "CLAUDE.md",
+    "CLAUDE.local.md",
+    ".mcp.json",
+    ".claude/settings.json",
+    ".claude/agents",
+    ".claude/rules"
+  ],
   "docs": {
     "memory": "https://docs.anthropic.com/en/docs/claude-code/memory",
     "settings": "https://docs.anthropic.com/en/docs/claude-code/settings",
@@ -67,5 +76,21 @@
     "mcpTools": "MCP tools use pattern: mcp__<server>__<tool>",
     "qualification": "No qualification needed - tool names are global identifiers."
   },
-  "notes": "Claude Code uses a hierarchical memory system with CLAUDE.md files. Custom subagents are defined in .claude/agents/*.md with YAML frontmatter."
+  "notes": "Claude Code uses a hierarchical memory system with CLAUDE.md files. Custom subagents are defined in .claude/agents/*.md with YAML frontmatter.",
+  "agentVersioning": {
+    "templates": [
+      {
+        "path": "templates/.claude/agents/aps-v{major}.{minor}.{patch}.md",
+        "currentPath": "templates/.claude/agents/aps-v1.1.7.md",
+        "frontmatter": {
+          "name": {
+            "pattern": "aps-v{major}-{minor}-{patch}"
+          },
+          "description": {
+            "pattern": "Generate APS v{major}.{minor}.{patch} subagent files: load APS+Claude Code adapter, extract intent, then generate+lint (and write if allowed)."
+          }
+        }
+      }
+    ]
+  }
 }

aps_cli/payload/agnostic-prompt-standard/platforms/opencode/manifest.json

@@ -0,0 +1,32 @@
+{
+  "platformId": "opencode",
+  "displayName": "OpenCode",
+  "adapterVersion": "1.0.0",
+  "lastUpdated": "2026-01-27",
+  "detectionMarkers": [
+    ".opencode",
+    ".opencode/opencode.jsonc",
+    ".opencode/opencode.json",
+    "opencode.json",
+    "opencode.jsonc",
+    ".opencode.json"
+  ],
+  "docs": {
+    "official": "https://opencode.ai/docs",
+    "config": "https://opencode.ai/docs/config"
+  },
+  "fileConventions": {
+    "instructions": [
+      "AGENTS.md",
+      ".opencode/instructions.md"
+    ],
+    "config": [
+      ".opencode/opencode.jsonc",
+      ".opencode/opencode.json",
+      "opencode.json",
+      "opencode.jsonc",
+      ".opencode.json"
+    ]
+  },
+  "notes": "OpenCode is an AI coding agent by anomalyco. Configuration supports JSONC (JSON with comments). The AGENTS.md file follows the OpenAI agents.md standard and is a shared marker with other platforms."
+}

aps_cli/payload/agnostic-prompt-standard/platforms/opencode/tools-registry.json

@@ -0,0 +1,9 @@
+{
+  "platformId": "opencode",
+  "adapterVersion": "1.0.0",
+  "lastUpdated": "2026-01-29",
+  "toolNaming": {},
+  "toolSets": [],
+  "tools": [],
+  "recommended": {}
+}

aps_cli/payload/agnostic-prompt-standard/platforms/vscode-copilot/manifest.json

@@ -3,6 +3,13 @@
   "displayName": "VS Code + GitHub Copilot",
   "adapterVersion": "1.0.0",
   "lastUpdated": "2026-01-15",
+  "detectionMarkers": [
+    ".github/copilot-instructions.md",
+    ".github/agents",
+    ".github/prompts",
+    ".github/instructions",
+    ".github/skills"
+  ],
   "docs": {
     "agentSkills": "https://code.visualstudio.com/docs/copilot/customization/agent-skills",
     "promptFiles": "https://code.visualstudio.com/docs/copilot/customization/prompt-files",
@@ -35,5 +42,21 @@
     "frontmatterTools": "Prompt/agent YAML frontmatter uses tool names (no leading #).",
     "qualification": "Newer VS Code versions may require fully-qualified tool names (example: search/codebase). Always prefer the name displayed in the VS Code tools picker."
   },
-  "notes": "This adapter documents VS Code Copilot-specific frontmatter and tool naming so APS prompts can be generated reproducibly."
+  "notes": "This adapter documents VS Code Copilot-specific frontmatter and tool naming so APS prompts can be generated reproducibly.",
+  "agentVersioning": {
+    "templates": [
+      {
+        "path": "templates/.github/agents/aps-v{major}.{minor}.{patch}.agent.md",
+        "currentPath": "templates/.github/agents/aps-v1.1.7.agent.md",
+        "frontmatter": {
+          "name": {
+            "pattern": "APS v{major}.{minor}.{patch} Agent"
+          },
+          "description": {
+            "pattern": "Generate APS v{major}.{minor}.{patch} .prompt.md files: load APS+VS Code adapter, extract intent, then generate+lint (and write if allowed)."
+          }
+        }
+      }
+    ]
+  }
 }

aps_cli/schemas.py

@@ -0,0 +1,170 @@
+"""Pydantic v2 schemas for manifest and skill validation."""
+
+from __future__ import annotations
+
+from typing import Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+
+class FileConventions(BaseModel):
+    """File convention paths for a platform."""
+
+    instructions: Optional[list[str]] = None
+    agents: Optional[list[str]] = None
+    prompts: Optional[list[str]] = None
+    skills: Optional[list[str]] = None
+
+
+class DetectionMarkerObject(BaseModel):
+    """A marker file or directory used to detect a platform (object format)."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    kind: str = Field(..., pattern="^(file|dir)$")
+    label: str
+    rel_path: str = Field(..., alias="relPath")
+
+
+class DetectionMarker(BaseModel):
+    """Normalized detection marker with all fields."""
+
+    kind: str
+    label: str
+    rel_path: str
+
+
+def normalize_detection_marker(
+    input_marker: Union[str, dict, DetectionMarkerObject],
+) -> DetectionMarker:
+    """Convert a detection marker input (string or object) to normalized format.
+
+    Args:
+        input_marker: String path or marker object/dict
+
+    Returns:
+        Normalized DetectionMarker
+    """
+    if isinstance(input_marker, str):
+        # String format: ".github/agents/" -> dir, ".github/copilot-instructions.md" -> file
+        is_dir = input_marker.endswith("/")
+        rel_path = input_marker.rstrip("/") if is_dir else input_marker
+        return DetectionMarker(
+            kind="dir" if is_dir else "file",
+            label=input_marker,
+            rel_path=rel_path,
+        )
+    elif isinstance(input_marker, DetectionMarkerObject):
+        return DetectionMarker(
+            kind=input_marker.kind,
+            label=input_marker.label,
+            rel_path=input_marker.rel_path,
+        )
+    elif isinstance(input_marker, dict):
+        # Validate dict input to match Node's strictness.
+        try:
+            obj = DetectionMarkerObject.model_validate(input_marker)
+        except ValidationError as e:
+            raise ValueError(f"Invalid detection marker object: {e}") from e
+        return DetectionMarker(kind=obj.kind, label=obj.label, rel_path=obj.rel_path)
+    else:
+        raise ValueError(f"Invalid detection marker type: {type(input_marker)}")
+
+
+class PlatformManifest(BaseModel):
+    """Schema for platform manifest.json files."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    platform_id: str = Field(..., min_length=1, alias="platformId")
+    display_name: str = Field(..., min_length=1, alias="displayName")
+    adapter_version: Optional[str] = Field(None, alias="adapterVersion")
+    description: Optional[str] = None
+    skill_root: Optional[str] = Field(None, alias="skillRoot")
+    file_conventions: Optional[FileConventions] = Field(None, alias="fileConventions")
+    detection_markers_raw: Optional[list[Union[str, DetectionMarkerObject]]] = Field(
+        None, alias="detectionMarkers"
+    )
+
+    @property
+    def detection_markers(self) -> list[DetectionMarker]:
+        """Get normalized detection markers."""
+        if not self.detection_markers_raw:
+            return []
+        return [normalize_detection_marker(m) for m in self.detection_markers_raw]
+
+
+class SkillFrontmatter(BaseModel):
+    """Schema for SKILL.md frontmatter."""
+
+    model_config = ConfigDict(extra="allow")
+
+    name: Optional[str] = None
+    version: Optional[str] = None
+    description: Optional[str] = None
+    author: Optional[str] = None
+    license: Optional[str] = None
+
+
+def parse_platform_manifest(data: dict) -> PlatformManifest:
+    """Parse and validate a platform manifest.
+
+    Args:
+        data: Raw manifest data
+
+    Returns:
+        Validated PlatformManifest
+
+    Raises:
+        ValidationError: If validation fails
+    """
+    return PlatformManifest.model_validate(data)
+
+
+def safe_parse_platform_manifest(
+    data: dict,
+) -> tuple[Optional[PlatformManifest], Optional[ValidationError]]:
+    """Safely parse a platform manifest without raising.
+
+    Args:
+        data: Raw manifest data
+
+    Returns:
+        Tuple of (manifest, error) - one will be None
+    """
+    try:
+        return parse_platform_manifest(data), None
+    except ValidationError as e:
+        return None, e
+
+
+def parse_skill_frontmatter(data: dict) -> SkillFrontmatter:
+    """Parse and validate skill frontmatter.
+
+    Args:
+        data: Raw frontmatter data
+
+    Returns:
+        Validated SkillFrontmatter
+
+    Raises:
+        ValidationError: If validation fails
+    """
+    return SkillFrontmatter.model_validate(data)
+
+
+def safe_parse_skill_frontmatter(
+    data: dict,
+) -> tuple[Optional[SkillFrontmatter], Optional[ValidationError]]:
+    """Safely parse skill frontmatter without raising.
+
+    Args:
+        data: Raw frontmatter data
+
+    Returns:
+        Tuple of (frontmatter, error) - one will be None
+    """
+    try:
+        return parse_skill_frontmatter(data), None
+    except ValidationError as e:
+        return None, e