git:20260415.03791dd to git:20260420.c6a0047

18 added, 153 removed. Audit A to A.

# CLAUDE.md

- This file provides guidance to Claude Code when working with the foundry-skills plugin.

- ## Plugin Overview

- This plugin provides specialized Claude Code skills for systematic CrowdStrike Foundry development. Clone and configure:

- ```bash

- git clone https://github.com/CrowdStrike/foundry-skills.git

- ```

- ## Prerequisites

- - **Foundry CLI**: Install cross-platform:

- - macOS/Linux: `brew tap crowdstrike/foundry-cli && brew install crowdstrike/foundry-cli/foundry`

- - Windows: Download https://assets.foundry.crowdstrike.com/cli/latest/foundry_Windows_x86_64.zip, expand it, add the installation directory to PATH

- - **Authentication**: Run `foundry login` to authenticate with CrowdStrike, or use `foundry profile create --no-prompt` for headless environments

- - **Development Environment**: Node.js, Python, or Go depending on your app requirements

- - **CLI Reference**: https://docs.crowdstrike.com/r/v5114866

- ## Foundry Development Skills Ecosystem

- ### Overview

- The `skills/` directory contains specialized Claude Code skills that provide systematic approaches for Foundry development. These skills enforce best practices, prevent technical debt, and ensure platform-specific patterns are followed correctly.

- ### Core Principles

- **Mandatory Sub-Skill Delegation**: The foundry-development-workflow skill enforces that all capability development must use the appropriate specialized sub-skill. This prevents platform-specific mistakes and ensures consistent quality.

- **Capability-Based Architecture**: Each skill maps to specific Foundry platform capabilities:

- - **UI capabilities** → foundry-ui-development

- - **Data capabilities** → foundry-collections-development

- - **Logic capabilities** → foundry-functions-development

- - **Automation capabilities** → foundry-workflows-development

- **Security-First Design**: Security patterns are integrated throughout all skills, with dedicated foundry-security-patterns for specialized security guidance.

- ### Use Cases

- The `use-cases/` directory contains real-world implementation patterns extracted from [CrowdStrike Tech Hub](https://www.crowdstrike.com/tech-hub/ng-siem/?cspage=0&lang=English&type=Article) blog posts. Each file captures an actionable pattern (not a summary) that Claude can apply when users describe similar scenarios. The orchestrator searches use-case frontmatter to match user requests, and sub-skills reference specific use cases for context.

- ### Primary Workflow Skills

- #### Foundry Development Workflow (Primary Orchestrator)

- **Always starts here** - coordinates complete app lifecycle and enforces sub-skill delegation.

- **Critical Functions**:

- - CLI state management (`foundry profile`, authentication, `foundry ui run`)

- - Manifest.yml coordination across all capabilities

- - Sub-skill delegation enforcement (NO direct implementation allowed)

+ Before responding to any Foundry development request, read [AGENTS.md](./AGENTS.md) for the complete CLI reference, skills ecosystem, and development guide.

- #### Capability-Specific Skills

- **Specialized skills for each Foundry capability type:**

+ Below are Claude Code-specific additions for this plugin.

- - **foundry-ui-development**: Vue/React + Shoelace UI components and extensions

- - **foundry-collections-development**: JSON Schema data modeling and CRUD operations

- - **foundry-functions-development**: Go/Python serverless functions with CrowdStrike SDK

- - **foundry-workflows-development**: YAML automation workflows and Fusion orchestration

- - **foundry-functions-falcon-api**: Calling Falcon APIs from within Functions (OAuth, SDKs)

- - **foundry-api-integrations**: Exposing external APIs via OpenAPI specs

+ ## Plugin Hook Behavior

- #### Support Skills

- **Cross-cutting concerns and troubleshooting:**

+ This plugin includes four hooks that run automatically:

- - **foundry-security-patterns**: OAuth scoping, input validation, UI security

- - **foundry-debugging-workflows**: Systematic troubleshooting for CLI, manifest, and API issues

+ - **SessionStart**: `set-foundry-env.sh` initializes the Foundry environment

+ - **UserPromptSubmit**: `foundry-skill-router.sh` routes user intents to the appropriate skill

+ - **PreToolUse (Bash)**: `foundry-cli-guard.sh` validates all Bash commands to ensure Foundry CLI commands include `--no-prompt` and blocks manual directory/file creation for app structure

+ - **PreToolUse (Skill)**: `superpowers-foundry-bridge.sh` intercepts `superpowers:brainstorming` and redirects to the Foundry development workflow skill

- ### Skills Usage Patterns

+ ## Automated Safety Enforcement

- #### Starting New Foundry Development

- ```

- 1. foundry-development-workflow coordinates the lifecycle

- 2. Specialized sub-skills for each capability (UI, Collections, Functions, Workflows)

- 3. foundry-security-patterns for security review

- ```

+ The `foundry-cli-guard.sh` hook automatically validates all Bash commands to ensure:

- #### Working with Existing Foundry Apps

- ```

- 1. foundry-development-workflow assesses current state

- 2. Appropriate sub-skill for the capability being modified

- 3. foundry-debugging-workflows if issues arise

- 4. foundry-security-patterns for security validation

- ```

+ - Foundry CLI commands always include `--no-prompt` flag (prevents `Error: EOF` failures)

+ - Manual directory/file creation for app structure is blocked (prevents invalid manifest.yml)

+ - Commands are corrected before execution with clear error messages

- #### Common Development Scenarios

- - **"Add UI extension"** → foundry-ui-development skill

- - **"Create data schema"** → foundry-collections-development skill

- - **"Build API endpoint"** → foundry-functions-development skill

- - **"Automate workflow"** → foundry-workflows-development skill

- - **"Call Falcon API from Function"** → foundry-functions-falcon-api skill

- - **"Expose external API to Foundry"** → foundry-api-integrations skill

- - **"Troubleshoot deployment"** → foundry-debugging-workflows skill

+ This enforcement runs automatically. You don't need to remember the rules; the hook will catch mistakes before they cause failures.

- ### Skills Integration with Claude Code Workflows

+ ## Skills Integration with Claude Code Workflows

**Planning Integration**: For structured planning with review checkpoints, install [superpowers](https://github.com/obra/superpowers) (`superpowers:writing-plans`, `superpowers:executing-plans`). Without superpowers, the orchestrator provides basic planning guidance that accounts for Foundry's 47 capability types and manifest dependencies.

**Execution Integration**: If superpowers is installed, `superpowers:executing-plans` provides batch execution with review checkpoints between capabilities. Otherwise, use the orchestrator's built-in execution checkpoints.

**Testing Integration**: If superpowers is installed, `superpowers:test-driven-development` enforces RED-GREEN-REFACTOR discipline. Each Foundry sub-skill also has its own capability-specific testing patterns.

**Handoff Integration**: Preserve Foundry-specific CLI state (profiles, authentication, `foundry ui run` status) when handing off between sessions.

- ### Counter-Rationalizations

+ ## Counter-Rationalizations

- **The skills enforce discipline to prevent common failures:**

+ The skills enforce discipline to prevent common failures:

| Your Excuse | Reality |

|-------------|---------|

| "I have API experience" | Foundry APIs have platform-specific auth, discovery, and error handling |

| "Time pressure means skip sub-skills" | Sub-skills PREVENT rework that costs 10x more time |

| "I can learn patterns during implementation" | Learning while implementing = building on wrong assumptions |

| "Sub-skills are overkill for simple cases" | No Foundry capability is simple - platform complexity is hidden |

- ### Essential Skills Commands

+ ## Essential Skills Commands

**Accessing Skills**: Skills are automatically invoked by Claude Code when working on Foundry development tasks. You can reference them explicitly using `@skills/skill-name` syntax.

**Skills Documentation**: Each skill includes comprehensive documentation in its `SKILL.md` file with specific patterns, testing approaches, and integration guidance.

**Skills Coordination**: The foundry-development-workflow skill ensures proper coordination between all sub-skills and maintains CLI state consistency throughout development.

- **Automated Safety Enforcement**: The plugin includes a PreToolUse hook (`foundry-cli-guard.sh`) that automatically validates all Bash commands to ensure:

- - Foundry CLI commands always include `--no-prompt` flag (prevents `Error: EOF` failures)

- - Manual directory/file creation for app structure is blocked (prevents invalid manifest.yml)

- - Commands are corrected before execution with clear error messages

- This enforcement runs automatically - you don't need to remember the rules, the hook will catch mistakes before they cause failures.

- ## Essential Foundry CLI Commands

- > **⚠️ CRITICAL: Always use `--no-prompt` with creation commands**

- >

- > Claude Code operates in a non-interactive environment. Commands that prompt for user input will fail with `Error: EOF`. **ALWAYS** include `--no-prompt` on any command that supports it.

- > **🚫 NEVER CREATE APP DIRECTORIES OR FILES MANUALLY**

- >

- > **ABSOLUTELY FORBIDDEN:** Using `mkdir`, `touch`, or manually creating app-related directories (api-integrations/, workflows/,

- > functions/, collections/, ui/) or files (manifest.yml, etc.). The Foundry CLI generates these with correct structure, IDs,

- > and manifest entries.

- >

- > **If a CLI command fails:**

- > 1. ✅ Fix the command (add `--no-prompt`, check flags, verify auth)

- > 2. ✅ Retry the corrected CLI command

- > 3. ❌ **NEVER** fall back to `mkdir` or manual creation

- >

- > **Manual creation causes:** Invalid manifest.yml, missing generated IDs, broken app structure, hours of debugging

- ```bash

- # Authentication & Environment Management

- foundry login # OAuth-based authentication

- foundry profile list # View available profiles (US-1, US-2, EU-1, US-GOV)

- foundry profile active # Show current active profile

- foundry profile activate --name <name> # Switch between environments

- # App Development Lifecycle

- foundry apps create --name "X" --no-prompt --no-git # Create new app

- foundry apps run # Start full app locally in dev mode

- foundry apps deploy --change-type Patch --change-log "msg" --no-prompt # Deploy to cloud

- foundry apps release --change-type Patch --deployment-id <id> --notes "notes" # Release to app catalog

- foundry ui run # Local UI development server

- # Scaffolding Commands (ALWAYS use --no-prompt)

- foundry api-integrations create --name "X" --spec path.json --no-prompt # Create API integration

- foundry ui pages create --name "X" --from-template React --no-prompt # Create UI page

- foundry ui extensions create --name "X" --from-template React --sockets "socket.name" --no-prompt # Create UI extension

- foundry ui navigation add --name "X" --path / --ref pages.xxx # Add navigation

- foundry functions create --name "X" --language python --no-prompt # Create function

- foundry collections create --name "X" --schema path.json --no-prompt # Create collection

- foundry workflows create --name "X" --spec path.yaml --no-prompt # Create workflow

- ```

- ## Quality and Thoroughness

- When building Falcon Foundry apps, take your time and do each step thoroughly. Quality is more important than speed. Specifically:

- - Do not skip validation steps (deploy early after API integrations and collections to catch spec issues)

- - Do not skip the Vite `noAttr()` fix for UI pages — a blank page wastes more time than the 30 seconds to add it

- - Read each sub-skill's Common Pitfalls section before implementing that capability

- - Verify CLI commands succeed before moving to the next step — do not chain multiple scaffolding commands blindly

- ## Security Considerations

- - **Never commit credentials** - CLI handles authentication

- - **Scoped permissions** - Request minimal required permissions in manifest

- - **Iframe security** - UI runs in sandboxed environment

- - **API rate limiting** - Respect CrowdStrike API limits