# 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)

#### Capability-Specific Skills
**Specialized skills for each Foundry capability type:**

- **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

#### Support Skills
**Cross-cutting concerns and troubleshooting:**

- **foundry-security-patterns**: OAuth scoping, input validation, UI security
- **foundry-debugging-workflows**: Systematic troubleshooting for CLI, manifest, and API issues

### Skills Usage Patterns

#### 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
```

#### 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
```

#### 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

### 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

**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

**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_FF_ENHANCED_UI=false foundry apps deploy --change-type Patch --change-log "msg" --no-prompt  # Deploy to cloud
FOUNDRY_FF_ENHANCED_UI=false 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