@amsterdamdatalabs/enact-extensions 0.1.0 → 0.1.3

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

@@ -0,0 +1,233 @@
+# 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

@@ -0,0 +1,193 @@
+# 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