@agnostic-prompt/aps 1.1.2 → 1.1.4

package/README.md

@@ -23,16 +23,20 @@ aps init
 ## Commands
 
 ```bash
-aps init [--repo|--personal] [--platform <id>] [--templates] [--yes] [--force]
+aps init [--repo|--personal] [--platform <id>] [--yes] [--force]
 aps doctor [--json]
 aps platforms
 aps version
 ```
 
-## Claude platform path
+## Platform-specific paths
 
-If you need the Claude platform `.claude/skills` location, pass `--claude`:
+Use `--platform <id>` to specify a platform adapter:
 
 ```bash
-aps init --claude
+# VS Code / Copilot (default paths: .github/skills, ~/.copilot/skills)
+aps init --platform vscode-copilot
+
+# Claude Code (paths: .claude/skills, ~/.claude/skills)
+aps init --platform claude-code
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agnostic-prompt/aps",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "CLI to install and manage the Agnostic Prompt Standard (APS) skill and platform templates.",
   "type": "module",
   "bin": {

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

@@ -5,7 +5,7 @@ license: Apache-2.0
 metadata:
   authors: "Christopher Buckley; Juan Burckhardt; Anastasiya Smirnova"
   spec_version: "1.0"
-  framework_revision: "1.1.2"
+  framework_revision: "1.1.4"
   last_updated: "2026-01-15"
 ---
 
@@ -55,7 +55,6 @@ This `SKILL.md` is the **entrypoint** for the Agnostic Prompt Standard (APS) v1.
     - `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).
 
 ---

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

@@ -6,10 +6,10 @@ DEFAULT_TZ: "Z"
 
 API_CONFIG: JSON<<
 {
-  "apiBasePath": "/v1",
-  "defaultTimeZone": DEFAULT_TZ,
+  "api_base_path": "/v1",
+  "default_time_zone": DEFAULT_TZ,
   "retries": 3,
-  "timeoutMs": 2000
+  "timeout_ms": 2000
 }
 >>
 </constants>

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

@@ -20,7 +20,6 @@ platforms/
     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
@@ -37,3 +36,10 @@ platforms/
 - Anything under `platforms/` is **non-normative** (documentation/templates/mappings only).
 - Adapters should prefer **mapping + configuration** over rewriting APS core rules.
 
+## Scope and Philosophy
+
+Adapters are intended to **map** the APS standard to a host platform. They are **not** project generators.
+We do not provide generic project scaffolding (like `settings.json` or root `CLAUDE.md` templates).
+
+> See [ADR 0001: Adapter Scope](https://github.com/chris-buckley/agnostic-prompt-standard/blob/main/docs/adr/0001-adapter-scope-no-scaffolding.md)
+

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

@@ -6,8 +6,7 @@
   "required": [
     "platformId",
     "displayName",
-    "adapterVersion",
-    "fileConventions"
+    "adapterVersion"
   ],
   "properties": {
     "platformId": {
@@ -35,9 +34,6 @@
     "fileConventions": {
       "type": "object",
       "required": [
-        "skills",
-        "agents",
-        "prompts",
         "instructions"
       ],
       "properties": {
@@ -45,25 +41,102 @@
           "type": "array",
           "items": {
             "type": "string"
-          }
+          },
+          "description": "Skill file locations (platform-specific)"
         },
         "agents": {
           "type": "array",
           "items": {
             "type": "string"
-          }
+          },
+          "description": "Agent file locations (platform-specific)"
         },
         "prompts": {
           "type": "array",
           "items": {
             "type": "string"
-          }
+          },
+          "description": "Prompt file locations (platform-specific)"
         },
         "instructions": {
           "type": "array",
           "items": {
             "type": "string"
-          }
+          },
+          "description": "Instruction/memory file locations"
+        },
+        "settings": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Platform-specific settings file locations"
+        },
+        "mcp": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "MCP server configuration file locations"
+        }
+      },
+      "additionalProperties": true
+    },
+    "hooks": {
+      "type": "object",
+      "description": "Platform-specific automation hooks",
+      "properties": {
+        "available": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "List of available hook types"
+        },
+        "configLocation": {
+          "type": "string",
+          "description": "Where hooks are configured"
+        },
+        "docsUrl": {
+          "type": "string",
+          "description": "Documentation URL for hooks"
+        }
+      },
+      "additionalProperties": true
+    },
+    "imports": {
+      "type": "object",
+      "description": "File import/reference syntax supported by the platform",
+      "properties": {
+        "syntax": {
+          "type": "string",
+          "description": "Import syntax pattern (e.g., @path)"
+        },
+        "examples": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Example import statements"
+        }
+      },
+      "additionalProperties": true
+    },
+    "permissions": {
+      "type": "object",
+      "description": "Permission/approval system documentation",
+      "properties": {
+        "configLocation": {
+          "type": "string",
+          "description": "Where permissions are configured"
+        },
+        "syntax": {
+          "type": "string",
+          "description": "Permission syntax description"
+        },
+        "docsUrl": {
+          "type": "string",
+          "description": "Documentation URL for permissions"
         }
       },
       "additionalProperties": true
@@ -81,4 +154,4 @@
     }
   },
   "additionalProperties": false
-}
+}

package/payload/agnostic-prompt-standard/platforms/_template/README.md

@@ -4,7 +4,5 @@ Copy this folder to `platforms/<your-platform-id>/` and fill in:
 
 - `manifest.json`
 - `tools-registry.json`
-- `frontmatter/` templates
-- `templates/` ready-to-copy artifacts
 
 Then validate JSON against the schemas in `platforms/_schemas/`.

package/payload/agnostic-prompt-standard/platforms/_template/manifest.json

@@ -17,8 +17,7 @@
       ".github/prompts/*.prompt.md"
     ],
     "instructions": [
-      ".github/copilot-instructions.md",
-      "AGENTS.md"
+      ".github/copilot-instructions.md"
     ]
   },
   "notes": "Describe platform-specific constraints here."

package/payload/agnostic-prompt-standard/platforms/claude-code/README.md

@@ -0,0 +1,247 @@
+# Claude Code CLI adapter
+
+This adapter documents **how APS fits into Claude Code's configuration system**.
+
+## What this adapter provides
+
+- `manifest.json` — file conventions, docs links, hooks/imports/permissions
+- `tools-registry.json` — built-in tools with risk levels and capabilities
+- `frontmatter/` — YAML templates for rules and subagents
+
+## Quickstart
+
+1. Install this APS skill into your repo at:
+   - `.github/skills/agnostic-prompt-standard/`
+   - OR `.claude/skills/agnostic-prompt-standard/`
+
+## Claude Code file locations (summary)
+
+Claude Code discovers these files:
+
+### Memory (instructions)
+- `./CLAUDE.md` — project-level memory (checked into repo)
+- `./.claude/CLAUDE.md` — alternative project memory location
+- `./.claude/rules/*.md` — path-scoped rules with glob patterns
+- `./CLAUDE.local.md` — local overrides (gitignored)
+- `~/.claude/CLAUDE.md` — user-level memory
+- `~/.claude/rules/*.md` — user-level rules
+
+### Settings
+- `./.claude/settings.json` — project settings (checked into repo)
+- `./.claude/settings.local.json` — local settings (gitignored)
+- `~/.claude/settings.json` — user settings
+
+### Custom subagents
+- `./.claude/agents/*.md` — project-level subagents
+- `~/.claude/agents/*.md` — user-level subagents (all projects)
+
+### MCP servers
+- `./.mcp.json` — MCP server configuration
+
+See `manifest.json` for the full matrix.
+
+## Memory hierarchy
+
+Claude Code loads memory in this order (later overrides earlier):
+
+1. **Enterprise** — managed by organization admins
+2. **Project** — `./CLAUDE.md`, `./.claude/CLAUDE.md`
+3. **Rules** — `./.claude/rules/*.md` (path-scoped)
+4. **User** — `~/.claude/CLAUDE.md`, `./CLAUDE.local.md`
+
+## @path imports
+
+Claude Code supports importing file content using `@path` syntax:
+
+```markdown
+@README.md
+@docs/architecture.md
+@~/.claude/shared-rules.md
+```
+
+The referenced file content is injected into the memory context.
+
+## Path-scoped rules
+
+Rules in `.claude/rules/*.md` can be scoped to specific paths using frontmatter:
+
+```yaml
+---
+paths:
+  - "src/**/*.ts"
+  - "src/**/*.tsx"
+---
+```
+
+When a rule has `paths:` frontmatter, it only applies when working with files matching those globs.
+
+## Hooks system
+
+Claude Code supports hooks that execute shell commands at various lifecycle events:
+
+| Hook | When it fires |
+|------|---------------|
+| PreToolUse | Before a tool executes |
+| PostToolUse | After a tool executes |
+| PermissionRequest | When permission is needed |
+| Stop | When Claude stops |
+| SubagentStop | When a subagent stops |
+| UserPromptSubmit | When user submits a prompt |
+| SessionStart | When a session begins |
+| SessionEnd | When a session ends |
+| PreCompact | Before context compaction |
+| Notification | When a notification fires |
+
+Configure hooks in `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "command": "echo 'About to run bash'"
+      }
+    ]
+  }
+}
+```
+
+## Permission rules
+
+Control tool permissions in `.claude/settings.json`:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Read",
+      "Glob",
+      "Grep"
+    ],
+    "deny": [
+      "Bash(rm -rf *)"
+    ],
+    "ask": [
+      "Write",
+      "Edit"
+    ]
+  }
+}
+```
+
+## Custom subagents
+
+Claude Code supports custom subagents — specialized agents with their own instructions, tool permissions, and behaviors. Subagents are invoked via the `Task` tool when their description matches the user's request.
+
+### Subagent file locations
+
+| Location | Scope |
+|----------|-------|
+| `.claude/agents/*.md` | Project-level |
+| `~/.claude/agents/*.md` | User-level (all projects) |
+| `plugins/agents/` | Plugin-provided |
+| `--agents` CLI flag | Session-only |
+
+### Subagent frontmatter fields
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `name` | Yes | String | Unique identifier (lowercase, hyphens) |
+| `description` | Yes | String | Triggers when Claude recognizes this description |
+| `model` | No | String | AI model: `sonnet`, `opus`, `haiku`, `inherit` (default: sonnet) |
+| `tools` | No | Comma-separated | Allowed tools (allowlist) |
+| `disallowedTools` | No | Comma-separated | Denied tools (denylist) |
+| `permissionMode` | No | String | Permission handling mode |
+| `skills` | No | Comma-separated | Skills to inject |
+| `hooks` | No | Object | Lifecycle hooks (PreToolUse, PostToolUse, Stop) |
+
+### Permission modes
+
+| Mode | Description |
+|------|-------------|
+| `default` | Normal permission prompts |
+| `acceptEdits` | Auto-accept file edits |
+| `dontAsk` | Minimal prompts |
+| `bypassPermissions` | Skip all prompts (use with caution) |
+| `plan` | Plan mode — research only, no edits |
+
+### Subagent example
+
+```yaml
+---
+name: code-reviewer
+description: Expert code review specialist. Use after writing or modifying code.
+model: inherit
+tools: Read, Grep, Glob, Bash
+disallowedTools: Write, Edit
+permissionMode: default
+---
+
+You are a senior code reviewer ensuring high standards of code quality.
+
+When invoked:
+1. Run git diff to see recent changes
+2. Review modified files for:
+   - Code style consistency
+   - Potential bugs
+   - Performance issues
+   - Security concerns
+3. Provide actionable feedback
+```
+
+### Subagent hooks
+
+Subagents can define their own hooks that only apply during subagent execution:
+
+```yaml
+---
+name: safe-bash-runner
+description: Run bash commands with validation
+hooks:
+  PreToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "./scripts/validate-command.sh"
+---
+```
+
+See `frontmatter/agent-frontmatter.md` for the full YAML template.
+
+## Tools: built-in tools
+
+Claude Code provides built-in tools directly by name (no qualification needed):
+
+- `Read` — read file contents
+- `Write` — create/overwrite files
+- `Edit` — edit existing files
+- `Bash` — execute shell commands
+- `Glob` — find files by pattern
+- `Grep` — search file contents
+- `WebFetch` — fetch URL content
+- `WebSearch` — web search
+- `Task` — run subagents
+- `TodoWrite` — manage task list
+- `NotebookEdit` — edit Jupyter notebooks
+- `AskUserQuestion` — ask user questions
+
+### MCP tools
+
+MCP tools use the pattern: `mcp__<server>__<tool>`
+
+For example: `mcp__filesystem__read_file`
+
+See `tools-registry.json` for the full tool catalog with risk levels.
+
+## Differences from VS Code Copilot
+
+| Aspect | VS Code Copilot | Claude Code |
+|--------|-----------------|-------------|
+| Instructions | `.github/copilot-instructions.md` | `CLAUDE.md`, `.claude/rules/*.md` |
+| Agents | `.github/agents/*.agent.md` | `.claude/agents/*.md` |
+| Prompts | `.github/prompts/*.prompt.md` | N/A (uses slash commands) |
+| Skills | `.github/skills/<id>/SKILL.md` | N/A (uses MCP servers) |
+| Settings | VS Code settings.json | `.claude/settings.json` |
+| Tool syntax | `#tool` mentions, qualified names | Direct tool names |
+| Extensions | MCP servers, extensions | MCP servers, hooks, plugins |

package/payload/agnostic-prompt-standard/platforms/claude-code/frontmatter/agent-frontmatter.md

@@ -0,0 +1,98 @@
+```yaml
+---
+# Custom subagent frontmatter for Claude Code
+# Subagents are stored in .claude/agents/*.md
+
+# Required: unique identifier (lowercase, hyphens only)
+name: my-subagent
+
+# Required: description that triggers this subagent
+description: "What this subagent does and when to use it."
+
+# Optional: AI model to use
+# Options: sonnet, opus, haiku, inherit (default: sonnet)
+model: inherit
+
+# Optional: allowed tools (allowlist)
+# Comma-separated tool names
+tools: Read, Grep, Glob, Bash
+
+# Optional: denied tools (denylist)
+# Comma-separated tool names
+disallowedTools: Write, Edit
+
+# Optional: permission handling mode
+# Options: default, acceptEdits, dontAsk, bypassPermissions, plan
+permissionMode: default
+
+# Optional: skills to inject
+# Comma-separated skill names
+skills: ""
+
+# Optional: lifecycle hooks (only apply during subagent execution)
+hooks:
+  PreToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "./scripts/validate.sh"
+---
+```
+
+Notes:
+- Claude Code loads subagents from `.claude/agents/*.md` (project) and `~/.claude/agents/*.md` (user).
+- Subagents are invoked via the `Task` tool when their description matches the request.
+- The `name` field must be unique across all loaded subagents.
+- Both `tools` (allowlist) and `disallowedTools` (denylist) can be used together.
+
+Permission modes:
+
+| Mode | Description |
+|------|-------------|
+| `default` | Normal permission prompts |
+| `acceptEdits` | Auto-accept file edits |
+| `dontAsk` | Minimal prompts |
+| `bypassPermissions` | Skip all prompts (use with caution) |
+| `plan` | Plan mode — research only, no edits |
+
+Examples:
+
+```yaml
+---
+# Read-only research agent
+name: researcher
+description: Research and explore the codebase without making changes
+model: haiku
+tools: Read, Grep, Glob, WebFetch, WebSearch
+disallowedTools: Write, Edit, Bash
+permissionMode: plan
+---
+```
+
+```yaml
+---
+# Code reviewer with validation hooks
+name: code-reviewer
+description: Expert code review specialist for reviewing changes
+model: inherit
+tools: Read, Grep, Glob, Bash
+disallowedTools: Write, Edit
+hooks:
+  PreToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "echo 'Running: $TOOL_INPUT'"
+---
+```
+
+```yaml
+---
+# Test runner agent
+name: test-runner
+description: Run tests and report results
+model: sonnet
+tools: Bash, Read, Glob
+permissionMode: acceptEdits
+---
+```

package/payload/agnostic-prompt-standard/platforms/claude-code/frontmatter/rules-frontmatter.md

@@ -0,0 +1,47 @@
+```yaml
+---
+# Path-scoped rules frontmatter for Claude Code
+# Rules with paths: only apply when working with files matching these globs
+
+paths:
+  - "src/**/*.ts"
+  - "src/**/*.tsx"
+---
+```
+
+Notes:
+- Claude Code loads rules from `.claude/rules/*.md`.
+- Rules without `paths:` frontmatter apply globally.
+- Rules with `paths:` frontmatter only apply when working with files matching those glob patterns.
+- Multiple glob patterns can be specified as an array.
+- Globs use standard glob syntax (e.g., `**` for recursive matching, `*` for single directory).
+
+Examples:
+
+```yaml
+---
+# Apply only to TypeScript files
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+---
+```
+
+```yaml
+---
+# Apply only to test files
+paths:
+  - "**/*.test.ts"
+  - "**/*.spec.ts"
+  - "tests/**/*"
+---
+```
+
+```yaml
+---
+# Apply only to documentation
+paths:
+  - "docs/**/*.md"
+  - "README.md"
+---
+```