@amsterdamdatalabs/enact-extensions 0.1.42 → 0.1.48

package/extensions/plugin-dev/skills/plugin-structure/references/github-actions.md

@@ -1,233 +0,0 @@
-# GitHub Actions Integration for Plugins
-
-Plugins interact with GitHub Actions through `claude-code-action`, Anthropic's official action for running Claude Code in CI workflows. Understanding this integration helps plugin developers ensure their plugins work seamlessly in automated pipelines.
-
-## Overview
-
-The `claude-code-action@v1` runs Claude Code inside GitHub Actions, enabling:
-
-- Automated code review on PRs
-- Issue implementation from comments
-- Custom automation triggered by @claude mentions
-- Scheduled analysis and reporting
-
-## Setup
-
-### Quick Setup
-
-From inside Claude Code:
-
-```bash
-/install-github-app
-```
-
-This guides through installing the Claude GitHub app and configuring workflows.
-
-### Manual Setup
-
-1. Install the Claude GitHub App: `https://github.com/apps/claude`
-2. Add `ANTHROPIC_API_KEY` to repository secrets
-3. Create workflow file at `.github/workflows/claude.yml`
-
-### Basic Workflow
-
-```yaml
-name: Claude Code
-on:
-  issue_comment:
-    types: [created]
-  pull_request_review_comment:
-    types: [created]
-
-jobs:
-  claude:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: anthropics/claude-code-action@v1
-        with:
-          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
-```
-
-## How Plugins Work in Actions
-
-### CLAUDE.md Integration
-
-The most direct way plugins interact with CI is through CLAUDE.md. Project-level instructions (`.claude/CLAUDE.md`) load automatically in CI runs, providing:
-
-- Code style requirements
-- Review criteria
-- Project-specific rules
-- Plugin references
-
-### Hooks in CI
-
-Plugin hooks execute in the CI environment:
-
-- **Command hooks:** Run normally (ensure scripts are executable and dependencies available)
-- **Prompt hooks:** Work as expected
-- **SessionStart hooks:** Fire at the beginning of each CI run
-- **Environment:** `$CI=true` is set, use for conditional logic
-
-**CI-aware hook example:**
-
-```bash
-#!/bin/bash
-# Skip interactive checks in CI
-if [ "$CI" = "true" ]; then
-  echo '{"continue": true}'
-  exit 0
-fi
-# Full validation in local development
-# ...
-```
-
-### Skills via prompt Parameter
-
-Reference plugin skills in the workflow's `prompt` parameter:
-
-```yaml
-- uses: anthropics/claude-code-action@v1
-  with:
-    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
-    prompt: "Review this PR for security issues following our coding standards"
-    claude_args: "--max-turns 15"
-```
-
-Since slash commands don't work in headless mode, describe the task instead. If the skill has `user-invocable: false`, Claude will use it automatically based on context.
-
-## Configuration Options
-
-### Key Parameters
-
-| Parameter           | Purpose                 | Example                                |
-| ------------------- | ----------------------- | -------------------------------------- |
-| `prompt`            | Instructions for Claude | `"Review this PR"`                     |
-| `claude_args`       | CLI arguments           | `"--max-turns 10 --model haiku"`       |
-| `anthropic_api_key` | API key secret          | `${{ secrets.ANTHROPIC_API_KEY }}`     |
-| `github_token`      | GitHub API access       | `${{ secrets.GITHUB_TOKEN }}`          |
-| `trigger_phrase`    | Custom trigger          | `"@review-bot"` (default: `"@claude"`) |
-
-### claude_args for Plugin Control
-
-Pass CLI flags through `claude_args`:
-
-```yaml
-claude_args: >-
-  --max-turns 20
-  --model claude-sonnet-4-5-20250929
-  --allowedTools "Read,Grep,Glob,Bash(npm:*)"
-```
-
-### Custom Trigger Phrases
-
-Change the default `@claude` trigger:
-
-```yaml
-trigger_phrase: "@security-review"
-```
-
-Users then mention `@security-review` in PR comments to trigger the workflow.
-
-## Provider Configurations
-
-### AWS Bedrock
-
-```yaml
-- uses: anthropics/claude-code-action@v1
-  with:
-    use_bedrock: "true"
-    claude_args: "--model us.anthropic.claude-sonnet-4-5-20250929-v1:0"
-  env:
-    AWS_ROLE_TO_ASSUME: ${{ secrets.AWS_ROLE_TO_ASSUME }}
-    AWS_REGION: us-east-1
-```
-
-Requires AWS OIDC configuration with Bedrock permissions.
-
-### Google Vertex AI
-
-```yaml
-- uses: anthropics/claude-code-action@v1
-  with:
-    use_vertex: "true"
-    claude_args: "--model claude-sonnet-4@20250514"
-  env:
-    ANTHROPIC_VERTEX_PROJECT_ID: ${{ secrets.GCP_PROJECT_ID }}
-    CLOUD_ML_REGION: us-east5
-```
-
-Requires GCP Workload Identity Federation.
-
-## Cost Management
-
-### Limit Turns
-
-```yaml
-claude_args: "--max-turns 10"
-```
-
-Each tool call is one turn. Start low and increase as needed.
-
-### Use Cheaper Models
-
-```yaml
-claude_args: "--model haiku"
-```
-
-Use Haiku for routine checks, Sonnet for standard reviews, Opus for complex analysis.
-
-### Set Workflow Timeouts
-
-```yaml
-jobs:
-  claude:
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    steps:
-      - uses: anthropics/claude-code-action@v1
-        # ...
-```
-
-### Restrict Tool Access
-
-```yaml
-claude_args: "--allowedTools 'Read,Grep,Glob'"
-```
-
-Read-only tools prevent expensive write/execute loops.
-
-## Plugin Design for CI
-
-### Document CI Workflows
-
-Include example workflow snippets in your plugin README:
-
-```markdown
-## GitHub Actions Usage
-
-Add to `.github/workflows/claude.yml`:
-
-\`\`\`yaml
-
-- uses: anthropics/claude-code-action@v1
-  with:
-  anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
-  prompt: "Analyze code using [your-plugin] standards"
-  claude_args: "--max-turns 15 --allowedTools 'Read,Grep,Glob'"
-  \`\`\`
-```
-
-### Ensure CI Compatibility
-
-- Test hooks with `CI=true` environment variable
-- Ensure scripts don't require interactive input
-- Handle missing dependencies gracefully (not all CI images have `jq`, etc.)
-- Use `${CLAUDE_PLUGIN_ROOT}` for all paths (cache directories differ in CI)
-
-### MCP Servers in CI
-
-MCP servers bundled with plugins start in CI, but:
-
-- OAuth-based servers won't have tokens (configure environment variables instead)
-- Local stdio servers need their dependencies installed in the CI image
-- Document required CI setup in README

package/extensions/plugin-dev/skills/plugin-structure/references/headless-ci-mode.md

@@ -1,193 +0,0 @@
-# Headless & CI Mode Plugin Compatibility
-
-Plugins behave differently in headless mode (`claude -p`) versus interactive sessions. Understanding these differences is critical for building plugins that work reliably across all runtime contexts.
-
-## Headless Mode Basics
-
-Headless mode executes Claude Code as a single-shot command-line tool:
-
-```bash
-claude -p "Analyze this codebase for security issues" --allowedTools "Read,Grep,Glob"
-```
-
-### What Works in Headless Mode
-
-- **Hooks:** Command hooks execute normally. Prompt hooks work for supported events.
-- **MCP servers:** Start and connect as usual. Tools are available.
-- **CLAUDE.md:** Project and user memory files load normally.
-- **Agents:** Can be spawned via Task tool during execution.
-- **Skills (as context):** Skill content with `user-invocable: false` loads into context and is available for Claude to use.
-
-### What Does NOT Work in Headless Mode
-
-- **Slash commands:** `/skill-name` invocation requires an interactive session. Skills cannot be invoked via slash commands in `-p` mode.
-- **Interactive prompts:** `AskUserQuestion` tool is not available — there's no user to answer.
-- **Skill tool (manual):** Users can't type `/` to invoke skills. Instead, describe the task and let Claude use the skill content if loaded.
-
-### Workaround for Skills
-
-Instead of invoking `/review` in headless mode, describe the task:
-
-```bash
-# Won't work:
-claude -p "/review"
-
-# Works — describe what you want:
-claude -p "Review the codebase for code quality issues"
-```
-
-If the skill has `user-invocable: false` and is loaded via plugin, Claude can still use its knowledge automatically.
-
-## Permission Control
-
-### --allowedTools
-
-Auto-approve specific tools without interactive prompts:
-
-```bash
-claude -p "Fix the bug" --allowedTools "Read,Write,Edit,Bash(git *)"
-```
-
-**Permission rule syntax:**
-
-| Pattern                | Matches                                                      |
-| ---------------------- | ------------------------------------------------------------ |
-| `Read`                 | All Read tool calls                                          |
-| `Bash(git *)`          | Bash commands starting with "git " (prefix match with space) |
-| `mcp__*`               | All MCP tool calls                                           |
-| `mcp__plugin_myplug_*` | Tools from a specific plugin's MCP server                    |
-| `Write,Edit`           | Multiple tools (comma-separated)                             |
-
-**Plugin design tip:** Document recommended `--allowedTools` values in your plugin README for CI usage.
-
-### --max-turns
-
-Limit autonomous tool-use iterations to control cost and runtime:
-
-```bash
-claude -p "Run tests and fix failures" --allowedTools "Read,Edit,Bash" --max-turns 10
-```
-
-Each tool call counts as one turn. Without this limit, Claude may iterate indefinitely on complex tasks.
-
-## Structured Output
-
-### JSON Output
-
-Get machine-readable responses:
-
-```bash
-claude -p "List all TODO comments" --output-format json
-```
-
-Returns:
-
-```json
-{
-  "result": "Found 5 TODO comments...",
-  "session_id": "abc123",
-  "metadata": { ... }
-}
-```
-
-### JSON Schema Validation
-
-Enforce a specific output structure:
-
-```bash
-claude -p "Extract function signatures from auth.py" \
-  --output-format json \
-  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'
-```
-
-**Plugin design tip:** If your plugin provides analysis workflows, document example JSON schemas users can use for structured CI output.
-
-## System Prompt Interaction
-
-### --append-system-prompt
-
-Add instructions alongside the default system prompt (and any loaded plugin content):
-
-```bash
-claude -p "Review code" --append-system-prompt "Focus on security vulnerabilities only"
-```
-
-Plugin skill content loads before system prompt overrides. The append adds to (not replaces) existing context.
-
-### --system-prompt
-
-Replace the default system prompt entirely:
-
-```bash
-claude -p "Analyze" --system-prompt "You are a security auditor..."
-```
-
-**Caution:** This replaces the default prompt but plugin content still loads. The interaction between `--system-prompt` and plugin skills may produce unexpected behavior.
-
-## Session Management
-
-### Continue Last Session
-
-```bash
-claude -p "What was the last change you made?" --continue
-```
-
-### Resume Specific Session
-
-```bash
-claude -p "Continue fixing the auth bug" --resume "$SESSION_ID"
-```
-
-Plugin state (hooks, MCP servers, skill context) reloads when resuming a session.
-
-## Plugin Design Guidelines for CI Compatibility
-
-### 1. Test in Headless Mode
-
-```bash
-# Test your plugin works in non-interactive mode
-claude -p "Run the plugin's primary workflow" \
-  --plugin-dir /path/to/plugin \
-  --allowedTools "Read,Write,Edit,Bash"
-```
-
-### 2. Avoid Interactive-Only Patterns
-
-- Don't rely on `AskUserQuestion` for critical workflows
-- Provide sensible defaults when user input is unavailable
-- Design hooks that work without user confirmation
-
-### 3. Document CI Usage
-
-Include a CI section in your plugin README:
-
-```markdown
-## CI/Headless Usage
-
-This plugin works in headless mode. Example:
-
-\`\`\`bash
-claude -p "Run security audit" \
- --allowedTools "Read,Grep,Glob,Bash(npm:\*)" \
- --max-turns 20 \
- --output-format json
-\`\`\`
-```
-
-### 4. Handle Missing Environment Gracefully
-
-In CI environments, some tools or context may be unavailable:
-
-- MCP servers may not have authentication tokens
-- Git history may be shallow clones
-- Environment variables may differ from local dev
-
-Design hooks and skills to handle these cases without failing hard.
-
-### 5. Cost-Conscious Design
-
-CI runs can accumulate significant API costs. Help users control spending:
-
-- Recommend `--max-turns` values for common workflows
-- Use `haiku` model for simple analysis skills
-- Document expected token usage for key workflows