agnostic-prompt-aps 1.1.2__py3-none-any.whl → 1.1.4__py3-none-any.whl

aps_cli/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 |

aps_cli/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
+---
+```

aps_cli/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"
+---
+```

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

@@ -0,0 +1,71 @@
+{
+  "platformId": "claude-code",
+  "displayName": "Claude Code CLI",
+  "adapterVersion": "1.0.0",
+  "lastUpdated": "2026-01-20",
+  "docs": {
+    "memory": "https://docs.anthropic.com/en/docs/claude-code/memory",
+    "settings": "https://docs.anthropic.com/en/docs/claude-code/settings",
+    "hooks": "https://docs.anthropic.com/en/docs/claude-code/hooks",
+    "mcp": "https://docs.anthropic.com/en/docs/claude-code/mcp",
+    "tools": "https://docs.anthropic.com/en/docs/claude-code/cli-reference",
+    "subagents": "https://docs.anthropic.com/en/docs/claude-code/sub-agents"
+  },
+  "fileConventions": {
+    "instructions": [
+      "./CLAUDE.md",
+      "./.claude/CLAUDE.md",
+      "./.claude/rules/*.md",
+      "./CLAUDE.local.md",
+      "~/.claude/CLAUDE.md",
+      "~/.claude/rules/*.md"
+    ],
+    "settings": [
+      "./.claude/settings.json",
+      "./.claude/settings.local.json",
+      "~/.claude/settings.json"
+    ],
+    "mcp": [
+      "./.mcp.json"
+    ],
+    "agents": [
+      "./.claude/agents/*.md",
+      "~/.claude/agents/*.md"
+    ]
+  },
+  "hooks": {
+    "available": [
+      "PreToolUse",
+      "PostToolUse",
+      "PermissionRequest",
+      "Stop",
+      "SubagentStop",
+      "UserPromptSubmit",
+      "SessionStart",
+      "SessionEnd",
+      "PreCompact",
+      "Notification"
+    ],
+    "configLocation": ".claude/settings.json (hooks field)",
+    "docsUrl": "https://docs.anthropic.com/en/docs/claude-code/hooks"
+  },
+  "imports": {
+    "syntax": "@path",
+    "examples": [
+      "@README.md",
+      "@docs/guide.md",
+      "@~/.claude/shared-rules.md"
+    ]
+  },
+  "permissions": {
+    "configLocation": ".claude/settings.json (permissions field)",
+    "syntax": "Tool(specifier) with allow/deny/ask arrays",
+    "docsUrl": "https://docs.anthropic.com/en/docs/claude-code/settings"
+  },
+  "toolNaming": {
+    "style": "Tools are referenced by their exact names (e.g., Bash, Read, Edit).",
+    "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."
+}