agnostic-prompt-aps 1.1.1__py3-none-any.whl

aps_cli/core.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+import json
+import os
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, Optional
+
+SKILL_ID = "agnostic-prompt-standard"
+
+
+@dataclass(frozen=True)
+class Platform:
+    platform_id: str
+    display_name: str
+    adapter_version: Optional[str]
+    has_templates: bool
+
+
+def is_tty() -> bool:
+    try:
+        return bool(os.isatty(0) and os.isatty(1))
+    except Exception:
+        return False
+
+
+def find_repo_root(start_dir: Path) -> Optional[Path]:
+    cur = start_dir.resolve()
+    while True:
+        if (cur / ".git").exists():
+            return cur
+        parent = cur.parent
+        if parent == cur:
+            return None
+        cur = parent
+
+
+def default_project_skill_path(repo_root: Path, *, claude: bool = False) -> Path:
+    """Return the project-skill path for the detected agent ecosystem.
+
+    - Default: `.github/skills/<skill-id>/` (Copilot Agent Skills)
+    - Claude:  `.claude/skills/<skill-id>/` (Claude platform)
+    """
+    base = repo_root / (".claude" if claude else ".github") / "skills"
+    return base / SKILL_ID
+
+
+def default_personal_skill_path(*, claude: bool = False) -> Path:
+    """Return the per-user skill path.
+
+    - Default: `~/.copilot/skills/<skill-id>/`
+    - Claude:  `~/.claude/skills/<skill-id>/`
+    """
+    base = Path.home() / (".claude" if claude else ".copilot") / "skills"
+    return base / SKILL_ID
+
+
+def infer_platform_id(workspace_root: Path) -> Optional[str]:
+    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()
+    if has_agents or has_prompts or has_instructions:
+        return "vscode-copilot"
+    return None
+
+
+def resolve_payload_skill_dir() -> Path:
+    """Locate the bundled APS skill directory.
+
+    Priority:
+    1) Installed package payload: aps_cli/payload/agnostic-prompt-standard
+    2) Repo checkout: ../../../../skill/agnostic-prompt-standard (relative to this file)
+    """
+    here = Path(__file__).resolve().parent
+    packaged = here / "payload" / SKILL_ID
+    if packaged.is_dir():
+        return packaged
+
+    # repo fallback
+    repo_root = Path(__file__).resolve().parents[4]
+    dev = repo_root / "skill" / SKILL_ID
+    if dev.is_dir():
+        return dev
+
+    raise FileNotFoundError("APS payload not found. (Did you run tools/sync_payload.py before building?)")
+
+
+def load_platforms(skill_dir: Path) -> list[Platform]:
+    platforms_dir = skill_dir / "platforms"
+    out: list[Platform] = []
+    for entry in platforms_dir.iterdir():
+        if not entry.is_dir():
+            continue
+        if entry.name.startswith("_"):
+            continue
+        manifest_path = entry / "manifest.json"
+        if not manifest_path.exists():
+            continue
+        try:
+            manifest = 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")
+        has_templates = (entry / "templates").is_dir()
+        out.append(
+            Platform(
+                platform_id=platform_id,
+                display_name=display_name,
+                adapter_version=adapter_version,
+                has_templates=has_templates,
+            )
+        )
+    out.sort(key=lambda p: p.display_name.lower())
+    return out
+
+
+def ensure_dir(p: Path) -> None:
+    p.mkdir(parents=True, exist_ok=True)
+
+
+def remove_dir(p: Path) -> None:
+    shutil.rmtree(p, ignore_errors=True)
+
+
+def copy_dir(src: Path, dst: Path) -> None:
+    shutil.copytree(src, dst)
+
+
+def copy_templates(templates_dir: Path, workspace_root: Path, force: bool) -> dict[str, list[str]]:
+    """Merge-copy templates_dir into workspace_root.
+
+    Returns {"copied": [...], "skipped": [...]}
+    """
+    copied: list[str] = []
+    skipped: list[str] = []
+
+    for root, dirs, files in os.walk(templates_dir):
+        root_path = Path(root)
+        rel_root = root_path.relative_to(templates_dir)
+        for d in dirs:
+            ensure_dir(workspace_root / rel_root / d)
+        for f in files:
+            src = root_path / f
+            rel = (rel_root / f)
+            dst = workspace_root / rel
+            ensure_dir(dst.parent)
+            if dst.exists() and not force:
+                skipped.append(str(rel))
+                continue
+            shutil.copy2(src, dst)
+            copied.append(str(rel))
+
+    return {"copied": copied, "skipped": skipped}

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

@@ -0,0 +1,73 @@
+---
+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: Apache-2.0
+metadata:
+  authors: "Christopher Buckley; Juan Burckhardt; Anastasiya Smirnova"
+  spec_version: "1.0"
+  framework_revision: "1.1.1"
+  last_updated: "2026-01-15"
+---
+
+# Agnostic Prompt Standard (APS) v1.0 — Skill Entry
+
+This `SKILL.md` is the **entrypoint** for the Agnostic Prompt Standard (APS) v1.0.
+
+- The APS **normative spec** is in `references/` (those documents define the standard).
+- Everything else in this repository is **supporting material** (examples, templates, platform adapters).
+
+## Normative spec (APS v1.0)
+
+1. [00 Structure](references/00-structure.md)
+2. [01 Vocabulary](references/01-vocabulary.md)
+3. [02 Linting and formatting](references/02-linting-and-formatting.md)
+4. [03 Agentic control](references/03-agentic-control.md)
+5. [04 Schemas and types](references/04-schemas-and-types.md)
+6. [05 Grammar](references/05-grammar.md)
+7. [06 Logging and privacy](references/06-logging-and-privacy.md)
+8. [07 Error taxonomy](references/07-error-taxonomy.md)
+
+## Skill layout
+
+- `SKILL.md` — this file (skill entrypoint).
+- `references/` — the APS v1.0 normative documents (this is what an LSP/linter should ingest).
+- `assets/` — reusable examples for `<format>` and `<constants>` blocks.
+  - `constants/` — example constants blocks.
+    - `constants-json-block-v1.0.0.example.md`
+    - `constants-text-block-v1.0.0.example.md`
+  - `formats/` — example format blocks.
+    - `format-code-changes-full-v1.0.0.example.md`
+    - `format-code-map-v1.0.0.example.md`
+    - `format-error-v1.0.0.example.md`
+    - `format-hierarchical-outline-v1.0.0.example.md`
+    - `format-ideation-list-v1.0.0.example.md`
+    - `format-markdown-table-v1.0.0.example.md`
+    - `format-table-api-coverage-v1.0.0.example.md`
+- `platforms/` — **non-normative** platform adapters (file conventions, frontmatter, tool registries, templates).
+  - `README.md` — platforms overview and contract.
+  - `_schemas/` — JSON Schemas for adapter validation.
+    - `platform-manifest.schema.json`
+    - `tools-registry.schema.json`
+  - `_template/` — skeleton for new platform adapters.
+    - `README.md`, `manifest.json`, `tools-registry.json`
+  - `vscode-copilot/` — VS Code + GitHub Copilot adapter.
+    - `README.md` — adapter quickstart and nuances.
+    - `manifest.json` — file discovery rules.
+    - `tools-registry.json` — tool names, sets, and renames.
+    - `frontmatter/` — copy/paste YAML frontmatter templates.
+    - `templates/` — drop-in workspace artifacts (`AGENTS.md`, `.github/agents/`).
+- `scripts/` — optional build / compile / lint scripts (empty by default).
+
+---
+
+## Platform adapters
+
+Platform-specific details (file discovery, frontmatter dialects, tool naming) are documented in `platforms/`.
+
+→ See [platforms/README.md](platforms/README.md) for overview and how to add new adapters.
+
+### VS Code + GitHub Copilot
+
+The initial adapter for VS Code + GitHub Copilot is at `platforms/vscode-copilot/`.
+
+→ See [platforms/vscode-copilot/README.md](platforms/vscode-copilot/README.md) for quickstart, file discovery, frontmatter templates, and tool naming.

aps_cli/payload/agnostic-prompt-standard/assets/agents/vscode-agent-v1.0.0.agent.md

@@ -0,0 +1,187 @@
+---
+name: APS v1.0 Agent
+description: "Generate APS v1.0 .prompt.md files: load APS+VS Code adapter, extract intent, then generate+lint (and write if allowed)."
+tools: ['search', 'read', 'edit', 'execute', 'todo', 'web/fetch', 'read/problems', 'search/changes', 'search/usages']
+model: Claude Opus 4.5 (copilot)
+argument-hint: Goal in 1-2 sentences.
+target: vscode
+infer: true
+---
+
+<instructions>
+You MUST follow APS v1.0 section order and the tag newline rule.
+You MUST keep one directive per line inside <instructions>.
+You MUST load SKILL_PATH and ADAPTER_TOOLS_PATH once per session before probing.
+You MUST infer VS Code Copilot defaults (paths + tool names) from the adapter; avoid obvious questions.
+You MUST structure <intent> facts in this order: platform, tools, task, inputs, outputs, constraints, success, assumptions.
+You MUST default VS Code prompt frontmatter + tool names from the adapter; only ask if user overrides.
+You MUST interleave intent refinement and tool/permission constraints; ask <=2 blocker questions per turn.
+You MUST mark assumptions inside the <intent> artifact.
+You MUST emit exactly one user-visible fenced block whose info string is format:<ID> per turn.
+You MUST derive PROMPT_SLUG deterministically from the final intent using SLUG_RULES.
+You MUST always return the generated prompt text and a lint report; write files only when WRITE_OK is true.
+You MUST redact secrets and personal data in any logs or artifacts.
+</instructions>
+
+<constants>
+PROMPTS_DIR: ".github/prompts/"
+PROMPT_EXT: ".prompt.md"
+SKILL_PATH: ".github/skills/agnostic-prompt-standard/SKILL.md"
+ADAPTER_TOOLS_PATH: ".github/skills/agnostic-prompt-standard/platforms/vscode-copilot/tools-registry.json"
+CTA: "Reply with letter choices (e.g., '1a, 2c') or 'ok' to accept defaults."
+
+SLUG_RULES: TEXT<<
+- lowercase ascii
+- space/_ -> -
+- keep [a-z0-9-]
+- collapse/trim -
+>>
+
+ASK_RULES: TEXT<<
+- ask only what blocks prompt generation
+- 0-2 questions per turn
+- each question MUST have 4 suggested answers (a-d) plus option (e) for "all of the above" or "none/other"
+- format each question as:
+  Q1: <question text>
+    a) <option 1>
+    b) <option 2>
+    c) <option 3>
+    d) <option 4>
+    e) All of the above / None / Other (specify)
+- include tool/permission limits if relevant
+- accept defaults on reply: ok, or reply with letter(s) like "1a, 2c"
+>>
+
+LINT_CHECKS: TEXT<<
+- section order: instructions, constants, formats, runtime, triggers, processes, input
+- tag newline rule
+- no tabs
+- no // inside triggers/processes
+- ids in RUN/USE are backticked
+- where: keys are lexicographic
+- every format:<ID> referenced exists
+- output is exactly one fenced block per turn
+>>
+
+PROMPT_SKELETON: TEXT<<
+<instructions>\n...\n</instructions>\n<constants>\n...\n</constants>\n<formats>\n...\n</formats>\n<runtime>\n...\n</runtime>\n<triggers>\n...\n</triggers>\n<processes>\n...\n</processes>\n<input>\n...\n</input>
+>>
+</constants>
+
+<formats>
+<format id="ERROR" name="Format Error" purpose="Emit a single-line reason when a requested format cannot be produced.">
+- Output wrapper starts with a fenced block whose info string is exactly format:ERROR.
+- Body is AG-036 FormatContractViolation: <ONE_LINE_REASON>.
+WHERE:
+- <ONE_LINE_REASON> is String.
+- <ONE_LINE_REASON> is <=160 characters.
+- <ONE_LINE_REASON> contains no newlines.
+</format>
+
+<format id="ASK_V1" name="Intent + Minimal Probe" purpose="Show the current intent and ask up to 2 blocker questions with suggested answers.">
+STATE: <STATE>
+
+<intent>
+<INTENT>
+</intent>
+
+ASK
+<QUESTIONS>
+
+CTA: <CTA>
+WHERE:
+- <STATE> is String.
+- <INTENT> is String.
+- <QUESTIONS> is MultilineQuestions where each question has format:
+  Q<N>: <question_text>
+    a) <option_1>
+    b) <option_2>
+    c) <option_3>
+    d) <option_4>
+    e) All of the above / None / Other (specify)
+- <CTA> is String.
+</format>
+
+<format id="OUT_V1" name="Generated Prompt + Lint" purpose="Return the prompt text, lint report, and (optional) write location.">
+# <PROMPT_NAME>
+File: <FILE_PATH>
+Written: <WRITTEN>
+
+<PROMPT>
+
+## Lint
+<LINT>
+WHERE:
+- <FILE_PATH> is Path.
+- <LINT> is String.
+- <PROMPT> is String.
+- <PROMPT_NAME> is String.
+- <WRITTEN> is Boolean.
+</format>
+</formats>
+
+<runtime>
+USER_INPUT: ""
+SESSION_INIT: false
+SKILL_CONTENT: ""
+ADAPTER_TOOLS: ""
+STATE: ""
+INTENT: ""
+QUESTIONS: ""
+INTENT_OK: false
+WRITE_OK: false
+PROMPT_SLUG: ""
+FILE_PATH: ""
+PROMPT: ""
+LINT: ""
+WRITTEN: false
+</runtime>
+
+<triggers>
+<trigger event="user_message" target="router" />
+</triggers>
+
+<processes>
+<process id="router" name="Route">
+IF SESSION_INIT is false:
+  RUN `init`
+RUN `refine`
+IF INTENT_OK is false:
+  RETURN: format="ASK_V1", cta=CTA, intent=INTENT, questions=QUESTIONS, state=STATE
+RUN `generate`
+RETURN: format="OUT_V1", file_path=FILE_PATH, lint=LINT, prompt=PROMPT, prompt_name=PROMPT_SLUG, written=WRITTEN
+</process>
+
+<process id="init" name="Init+Load Context">
+SET SESSION_INIT := true (from "Agent Inference")
+USE `read/readFile` where: filePath=SKILL_PATH
+CAPTURE SKILL_CONTENT from `read/readFile`
+USE `read/readFile` where: filePath=ADAPTER_TOOLS_PATH
+CAPTURE ADAPTER_TOOLS from `read/readFile`
+</process>
+
+<process id="refine" name="Intent">
+SET STATE := <STATE_TEXT> (from "Agent Inference" using USER_INPUT)
+SET INTENT := <INTENT_FACTS> (from "Agent Inference" using USER_INPUT, SKILL_CONTENT, ADAPTER_TOOLS)
+SET QUESTIONS := <BLOCKERS> (from "Agent Inference" using INTENT, ASK_RULES)
+SET INTENT_OK := <DONE> (from "Agent Inference")
+SET WRITE_OK := <OK_TO_WRITE> (from "Agent Inference")
+</process>
+
+<process id="generate" name="Generate+Lint+MaybeWrite">
+SET PROMPT_SLUG := <SLUG> (from "Agent Inference" using INTENT, SLUG_RULES)
+SET FILE_PATH := <PROMPT_FILE_PATH> (from "Agent Inference" using PROMPT_SLUG, PROMPTS_DIR, PROMPT_EXT)
+SET PROMPT := <PROMPT_TEXT> (from "Agent Inference" using INTENT, SKILL_CONTENT, ADAPTER_TOOLS, PROMPT_SKELETON)
+SET LINT := <LINT_TEXT> (from "Agent Inference" using PROMPT, LINT_CHECKS)
+IF WRITE_OK is true:
+  USE `edit/createDirectory` where: dirPath=PROMPTS_DIR
+  USE `edit/createFile` where: content=PROMPT, filePath=FILE_PATH
+  SET WRITTEN := true (from "Agent Inference")
+ELSE:
+  SET WRITTEN := false (from "Agent Inference")
+</process>
+</processes>
+
+<input>
+USER_INPUT is the user's latest message containing goals or answers.
+</input>

aps_cli/payload/agnostic-prompt-standard/assets/constants/constants-json-block-v1.0.0.example.md

@@ -0,0 +1,15 @@
+<constants>
+// Example: multi-line JSON constant using JSON<< ... >>.
+// Engines parse BODY as JsonValue then compile it to canonical JSON (see json_spacing).
+
+DEFAULT_TZ: "Z"
+
+API_CONFIG: JSON<<
+{
+  "apiBasePath": "/v1",
+  "defaultTimeZone": DEFAULT_TZ,
+  "retries": 3,
+  "timeoutMs": 2000
+}
+>>
+</constants>

aps_cli/payload/agnostic-prompt-standard/assets/constants/constants-text-block-v1.0.0.example.md

@@ -0,0 +1,15 @@
+<constants>
+// Example: multi-line TEXT constant using TEXT<< ... >>.
+// NOTE: Comment stripping (//) does NOT apply inside TEXT<< bodies.
+
+REPO_TREE: TEXT<<
+cb-agnostic-prompt-protocol
+├── assets
+│   ├── constants
+│   │   └── constants-json-block-v1.0.0.example.md
+│   └── formats
+│       ├── format-code-map-v1.0.0.example.md
+│       └── format-error-v1.0.0.example.md
+└── SKILL.md
+>>
+</constants>

aps_cli/payload/agnostic-prompt-standard/assets/formats/format-code-changes-full-v1.0.0.example.md

@@ -0,0 +1,21 @@
+<format id="CODE_CHANGES_V1" name="Code Changes" purpose="Display updated and new files with complete code.">
+## <CHANGE_TITLE>
+
+<CHANGE_DESCRIPTION>
+File: <FILE_PATH>
+```<LANG>
+<COMPLETE_CODE>
+```
+
+---
+
+…
+
+WHERE:
+- <CHANGE_TITLE> is String; title for the set of changes.
+- <CHANGE_DESCRIPTION> is String; terse description of the change; present voice; NO changelog style.
+- <FILE_PATH> is Path; relative from repository root; MUST NOT start with "/".
+- <LANG> is String; valid code language for GitHub-flavored Markdown.
+- <COMPLETE_CODE> is String; complete file contents; best practices; comments MUST be terse and present voice.
+- … denotes repetition; one block per updated or new file; each separated by "---"; AVOID unchanged files.
+</format>

aps_cli/payload/agnostic-prompt-standard/assets/formats/format-code-map-v1.0.0.example.md

@@ -0,0 +1,18 @@
+<format id="CODE_MAP_V1" name="Code Map" purpose="Display relevant code snippets with links to source">
+<AREA_TITLE>
+> [<SHORT_DESC>](../../../<REPO_NAME>/<REL_PATH>#L<LINE_FROM>-L<LINE_TO>)
+```<LANG>
+<LINE_FROM>: <code line>
+<LINE_FROM+1>: <code line>
+…
+<LINE_TO>: <code line>
+```
+
+WHERE:
+- <AREA_TITLE> is the title of the area being described.
+- <REPO_NAME> is a single path segment.
+- <REL_PATH> is repo-relative and MUST NOT start with "/".
+- <LINE_FROM> and <LINE_TO> are integers; LINE_TO ≥ LINE_FROM.
+- <SHORT_DESC> is a short description of the code snippet.
+- <LANG> is a valid code language for GitHub-flavored Markdown.
+</format>

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

@@ -0,0 +1,9 @@
+<format id="ERROR" name="Format Error" purpose="Emit a single-line reason when a requested format cannot be produced.">
+- Output wrapper starts with a fenced block whose info string is exactly `format:ERROR`.
+- Body is `AG-036 FormatContractViolation: <ONE_LINE_REASON>`.
+- Body MUST be a single line.
+WHERE:
+- <ONE_LINE_REASON> is String.
+- <ONE_LINE_REASON> is ≤ 160 characters.
+- <ONE_LINE_REASON> contains no newlines.
+</format>

aps_cli/payload/agnostic-prompt-standard/assets/formats/format-hierarchical-outline-v1.0.0.example.md

@@ -0,0 +1,17 @@
+<format id="OUTLINE_V1" name="Hierarchical Outline" purpose="Generate a semantic multilevel numbered outline.">
+## <OUTLINE_TITLE>
+
+<LEVEL_1_NUMBER> <STATEMENT>
+ <LEVEL_2_NUMBER> <STATEMENT>
+  <LEVEL_3_NUMBER> <STATEMENT>
+
+…
+
+WHERE:
+- <OUTLINE_TITLE> is String; title for the outline.
+- <LEVEL_1_NUMBER> is String; format "N" (e.g., "1", "2", "3").
+- <LEVEL_2_NUMBER> is String; format "N.N" (e.g., "1.1", "1.2").
+- <LEVEL_3_NUMBER> is String; format "N.N.N" (e.g., "1.1.1", "1.1.2"); maximum depth.
+- <STATEMENT> is String; single atomic statement; topic, instruction, or information; NO obvious statements.
+- … denotes repetition; one space indentation per level; up to 3 levels deep.
+</format>

aps_cli/payload/agnostic-prompt-standard/assets/formats/format-ideation-list-v1.0.0.example.md

@@ -0,0 +1,20 @@
+<format id="IDEATION_LIST_V1" name="Ideation List" purpose="Generate structured brainstorming ideas for a given task.">
+## <TASK_TITLE>
+
+[<ITEM_NUMBER>] <IDEA_TITLE>
+Summary: <IDEA_SUMMARY>
+Details: <IDEA_DETAILS>
+
+---
+
+…
+
+WHERE:
+- <TASK_TITLE> is String; the task or topic for ideation.
+- <ITEM_COUNT> is Integer; total number of ideation items to generate.
+- <ITEM_NUMBER> is Integer; sequential from 1 to <ITEM_COUNT>.
+- <IDEA_TITLE> is String; short descriptive title; present tense; active voice.
+- <IDEA_SUMMARY> is String; one sentence; present tense; active voice.
+- <IDEA_DETAILS> is String; 2–4 sentences; conceptual only; NO implementation, code, or pseudo-code.
+- … denotes repetition; exactly <ITEM_COUNT> items; each separated by "---".
+</format>

aps_cli/payload/agnostic-prompt-standard/assets/formats/format-markdown-table-v1.0.0.example.md

@@ -0,0 +1,17 @@
+<format id="TABLE_PROCESS_RESULTS_V1" name="Process Results Table" purpose="Summarize process execution across processes in lexical order.">
+- Output wrapper starts with a fenced block whose info string is exactly `format:TABLE_PROCESS_RESULTS_V1`.
+- Header row MUST be:
+  | ProcessId | Name | Status | StartedAt | EndedAt | DurationMs | Outcome | Artifacts | Errors |
+- Example row:
+  | <PROCESS_ID> | <PROCESS_NAME> | <STATUS> | <STARTED_AT> | <ENDED_AT> | <DURATION_MS> | <OUTCOME> | <ARTIFACTS> | <ERRORS> |
+WHERE:
+- <PROCESS_ID> is String.
+- <PROCESS_NAME> is String.
+- <STATUS> is one of: PENDING, RUNNING, OK, WARN, ERROR.
+- <STARTED_AT> is ISO8601.
+- <ENDED_AT> is ISO8601.
+- <DURATION_MS> is Integer.
+- <OUTCOME> is String.
+- <ARTIFACTS> is String.
+- <ERRORS> is String.
+</format>

aps_cli/payload/agnostic-prompt-standard/assets/formats/format-table-api-coverage-v1.0.0.example.md

@@ -0,0 +1,13 @@
+<format id="TABLE_API_COVERAGE_V1" name="API Coverage Table" purpose="Report API operation coverage against a specification.">
+## <TABLE_NAME>
+| Operation | URI | SpecRef | Gap |
+| --- | --- | --- | --- |
+| <OPERATION> | <URI> | <SPEC_REF> | <GAP> |
+
+WHERE:
+- <TABLE_NAME> is the title for the API coverage table.
+- <OPERATION> is the HTTP method, one of: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`.
+- <URI> is the absolute path of the API endpoint, starting with `/`.
+- <SPEC_REF> is a reference to the relevant part of the API specification, one of: `OpenAPI: <PATH_OR_COMPONENT>` or `Swagger: <PATH_OR_COMPONENT>`.
+- <GAP> is the coverage gap analysis code, one of: `OK`, `MISSING_PATH`, `MISSING_METHOD`, `REQ_SCHEMA_MISMATCH`, `RESP_SCHEMA_MISMATCH`, `STATUS_CODE_MISSING`.
+</format>

aps_cli/payload/agnostic-prompt-standard/platforms/README.md

@@ -0,0 +1,39 @@
+# Platforms
+
+APS is designed to be **platform-agnostic**, but real hosts (IDEs, agent runtimes, CI bots) differ in:
+
+- File discovery conventions (where prompts/agents/skills live)
+- YAML frontmatter dialects (which fields exist, required/optional)
+- Tool availability, naming, and approval UX
+- Safety constraints (auto-approve settings, restricted file paths)
+
+This folder contains **platform adapters** that describe those differences *without changing the APS v1.0 spec*.
+
+## Adapter layout (recommended)
+
+```
+platforms/
+  _schemas/                       # JSON Schemas for adapter files
+  _template/                      # skeleton for new adapters
+  <platform-id>/
+    README.md
+    manifest.json                 # validates against _schemas/platform-manifest.schema.json
+    tools-registry.json           # validates against _schemas/tools-registry.schema.json
+    frontmatter/                  # copy/paste blocks for this platform
+    templates/                    # ready-to-copy workspace artifacts
+```
+
+## Add a new platform adapter
+
+1. Copy `platforms/_template/` to `platforms/<platform-id>/`
+2. Fill in:
+   - `manifest.json` (file discovery rules + docs links)
+   - `tools-registry.json` (available tools + naming + risk tags)
+3. Do **not** change `references/` unless you are intentionally publishing an APS spec revision.
+
+## Contract
+
+- Anything under `references/` is **normative** APS.
+- Anything under `platforms/` is **non-normative** (documentation/templates/mappings only).
+- Adapters should prefer **mapping + configuration** over rewriting APS core rules.
+